> ## Documentation Index > Fetch the complete documentation index at: https://docs.trackup.me/llms.txt > Use this file to discover all available pages before exploring further. # API externa > Endpoints autenticados por API Key para visitantes, conversões e requisições. Todas as rotas exigem autenticação via API Key. O corpo das requisições é JSON. Respostas de sucesso retornam status `201`. ## URL base **Produção:** `https://dash-api.trackup.me/v1` Monte a URL completa concatenando o endpoint ao base. Exemplo: `https://dash-api.trackup.me/v1/visitors`. | Método | Endpoint | | ------ | -------------- | | `POST` | `/visitors` | | `POST` | `/conversions` | | `POST` | `/requests` | ## Autenticação Envie a chave no header `X-Api-Key` em cada requisição. | Status | Condição | | ------ | -------------------------------- | | `401` | Header ausente ou chave inválida | | `403` | Chave revogada ou expirada | *** ## POST /visitors Cria um visitante no projeto vinculado à API Key. ### Corpo da requisição Todos os campos são opcionais. | Campo | Tipo | Obrigatório | Descrição | | ---------------- | ------ | ----------- | ------------ | | `utmSource` | string | não | Origem UTM | | `utmMedium` | string | não | Meio UTM | | `utmCampaign` | string | não | Campanha UTM | | `utmTerm` | string | não | Termo UTM | | `utmContent` | string | não | Conteúdo UTM | | `clickId` | string | não | ID de clique | | `name` | string | não | Nome | | `email` | string | não | E-mail | | `phone` | string | não | Telefone | | `addressStreet` | string | não | Rua | | `addressCity` | string | não | Cidade | | `addressState` | string | não | Estado | | `addressZip` | string | não | CEP | | `addressCountry` | string | não | País | ### Resposta | Campo | Tipo | Descrição | | ----------------- | -------------- | -------------------------- | | `id` | string | ID do visitante | | `createdAt` | string | Data de criação (ISO 8601) | | `name` | string \| null | Nome | | `email` | string \| null | E-mail | | `phone` | string \| null | Telefone | | `address` | object | Endereço | | `address.street` | string \| null | Rua | | `address.city` | string \| null | Cidade | | `address.state` | string \| null | Estado | | `address.zip` | string \| null | CEP | | `address.country` | string \| null | País | | `utmSource` | string | Origem UTM | | `utmMedium` | string | Meio UTM | | `utmCampaign` | string | Campanha UTM | | `clickId` | string | ID de clique | ### Exemplo ```bash theme={"dark"} curl -X POST 'https://dash-api.trackup.me/v1/visitors' \ -H 'Content-Type: application/json' \ -H 'X-Api-Key: YOUR_API_KEY' \ -d '{ "name": "Maria Silva", "email": "maria@example.com", "utmSource": "google", "utmCampaign": "black-friday" }' ``` *** ## POST /conversions Registra uma conversão no projeto vinculado à API Key. O campo `value` é convertido para a moeda configurada no projeto. ### Corpo da requisição | Campo | Tipo | Obrigatório | Descrição | | --------------- | ------ | ----------- | ----------------------------------------------------------- | | `value` | number | **sim** | Valor da conversão | | `transactionId` | string | não | ID da transação | | `currency` | string | não | Moeda de origem (ex.: `BRL`, `USD`) | | `paymentMethod` | string | não | Método de pagamento | | `ip` | string | não | Endereço IP | | `userAgent` | string | não | User agent | | `visitorId` | string | não | ID do visitante | | `trafficSource` | string | não | Fonte de tráfego | | `utmSource` | string | não | Origem UTM | | `utmMedium` | string | não | Meio UTM | | `utmCampaign` | string | não | Campanha UTM | | `utmTerm` | string | não | Termo UTM | | `utmContent` | string | não | Conteúdo UTM | | `clickId` | string | não | ID de clique | | `sub1` | string | não | Sub ID 1 | | `sub2` | string | não | Sub ID 2 | | `sub3` | string | não | Sub ID 3 | | `sub4` | string | não | Sub ID 4 | | `sub5` | string | não | Sub ID 5 | | `sub6` | string | não | Sub ID 6 | | `sub7` | string | não | Sub ID 7 | | `sub8` | string | não | Sub ID 8 | | `status` | string | não | Status da conversão (padrão: `"paid"`) — ver valores abaixo | Valores aceitos para `status`: | Valor | Descrição | | ------------ | ----------------------------- | | `paid` | Pagamento confirmado (padrão) | | `refunded` | Reembolso | | `chargeback` | Chargeback | ### Resposta | Campo | Tipo | Descrição | | --------------- | ------ | -------------------- | | `id` | string | ID da conversão | | `timestamp` | string | Data/hora (ISO 8601) | | `transactionId` | string | ID da transação | | `value` | number | Valor convertido | | `currency` | string | Moeda do projeto | | `paymentMethod` | string | Método de pagamento | | `status` | string | Status da conversão | | `visitorId` | string | ID do visitante | ### Exemplo ```bash theme={"dark"} curl -X POST 'https://dash-api.trackup.me/v1/conversions' \ -H 'Content-Type: application/json' \ -H 'X-Api-Key: YOUR_API_KEY' \ -d '{ "value": 199.90, "currency": "BRL", "transactionId": "txn_abc123", "visitorId": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee" }' ``` *** ## POST /requests Registra um evento ou requisição no projeto vinculado à API Key. Requisições criadas via API Key não disparam triggers ou pixels — apenas persistem o registro. ### Corpo da requisição Todos os campos são opcionais. | Campo | Tipo | Obrigatório | Descrição | | --------------- | ------ | ----------- | ------------------------------------- | | `host` | string | não | Host da requisição (padrão: `""`) | | `path` | string | não | Caminho da requisição (padrão: `""`) | | `event` | string | não | Nome do evento (padrão: `""`) | | `ip` | string | não | Endereço IP | | `userAgent` | string | não | User agent | | `visitorId` | string | não | ID do visitante | | `trafficSource` | string | não | Fonte de tráfego (padrão: `"direct"`) | | `utmSource` | string | não | Origem UTM | | `utmMedium` | string | não | Meio UTM | | `utmCampaign` | string | não | Campanha UTM | | `utmTerm` | string | não | Termo UTM | | `utmContent` | string | não | Conteúdo UTM | | `clickId` | string | não | ID de clique | | `sub1`–`sub8` | string | não | Sub IDs 1 a 8 | | `customData` | object | não | Dados customizados (ver abaixo) | ### customData Objeto plano com pares chave-valor. | Regra | Valor | | ---------------- | ----------------------- | | Máximo de chaves | 15 | | Tamanho máximo | 8 KB (JSON serializado) | | Violação | Resposta `400` | Valores aninhados são permitidos. Se omitido, armazena `{}`. ### Resposta | Campo | Tipo | Descrição | | --------------- | -------------- | -------------------- | | `id` | string | ID da requisição | | `timestamp` | string | Data/hora (ISO 8601) | | `host` | string | Host | | `path` | string | Caminho | | `event` | string | Nome do evento | | `visitorId` | string | ID do visitante | | `trafficSource` | string | Fonte de tráfego | | `utmSource` | string | Origem UTM | | `utmMedium` | string | Meio UTM | | `utmCampaign` | string | Campanha UTM | | `utmTerm` | string | Termo UTM | | `utmContent` | string | Conteúdo UTM | | `clickId` | string | ID de clique | | `sub1`–`sub8` | string | Sub IDs 1 a 8 | | `customData` | object \| null | Dados customizados | ### Exemplo ```bash theme={"dark"} curl -X POST 'https://dash-api.trackup.me/v1/requests' \ -H 'Content-Type: application/json' \ -H 'X-Api-Key: YOUR_API_KEY' \ -d '{ "event": "purchase", "host": "loja.example.com", "path": "/checkout/success", "visitorId": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee", "customData": { "orderId": "ord_123", "value": 299.90 } }' ``` *** ## Erros | Status | Causa | | ------ | ------------------------------------------------- | | `400` | Corpo inválido ou `customData` fora dos limites | | `401` | API Key ausente ou inválida | | `403` | API Key revogada ou expirada | | `404` | Projeto não encontrado | | `500` | Falha ao persistir o registro | | `502` | Falha na conversão de moeda (`POST /conversions`) |