Docs · Referência da API

/v1/conversions

Um único endpoint cobre todos os tipos de conversão. Autenticado por Bearer com a site key do seu workspace. Idempotente em (workspace_id, external_id).

Autenticação

Todas as requisições carregam um token Bearer no cabeçalho Authorization. O token é a site key do seu workspace, com o prefixo dcs_sk_. Encontre-a em Configurações → Chaves da API.

Authorization: Bearer dcs_sk_live_…

As site keys têm escopo de workspace. Faça a rotação na mesma página de configurações; as chaves antigas deixam de autenticar em até 60 segundos.

Endpoint

POST https://api.decisa.ai/v1/conversions
Content-Type: application/json
Authorization: Bearer dcs_sk_live_…

Corpo da requisição

{
  "type": "signup",
  "external_id": "user-1234",
  "visitor_id": "v_abc123...",
  "customer_email": "[email protected]",
  "value_cents": 0,
  "currency": "USD",
  "occurred_at": "2026-05-25T18:14:22Z",
  "metadata": {
    "plan": "pro",
    "trial": false
  }
}

Campo	Tipo	Descrição
type	string · obrigatório	Um de: signup, trial_start, subscription_start, sale, lead, app_install, custom.
external_id	string · obrigatório	Seu ID único para o registro. Usado para deduplicação.
visitor_id	string · recomendado	Valor do cookie first-party dcs_vid. Sem ele, a conversão não pode ser associada a um clique.
customer_email	string · opcional	Hasheado com SHA256 antes do armazenamento. Usado para o envio via CAPI.
value_cents	integer · opcional	Receita em unidades menores. Obrigatório para tipos que carregam receita.
currency	string · opcional	ISO 4217. Padrão é a moeda do workspace.
occurred_at	ISO 8601 · opcional	O timestamp do servidor é usado se omitido.
metadata	object · opcional	Formato livre. Não usado para atribuição; exibido nos painéis.

Resposta de sucesso (201)

{
  "data": {
    "id": "conv_01HZX...",
    "type": "signup",
    "external_id": "user-1234",
    "attributed": true,
    "attribution_model": "last-click",
    "attribution_model_version": "1.0.0",
    "matched_click_id": "clk_01HZX...",
    "matched_campaign_id": null,
    "occurred_at": "2026-05-25T18:14:22Z"
  },
  "meta": null,
  "error": null
}

attributed: false significa que aceitamos a conversão, mas não encontramos um clique qualificável. A linha continua consultável no painel em Não atribuídas.

Códigos de erro

Campo	Tipo	Descrição
401	unauthorized	Site key ausente ou inválida.
403	workspace_disabled	O workspace está pausado por questões de cobrança ou conformidade.
422	invalid_payload	A validação do esquema falhou. Veja `error.fields` para detalhes.
429	rate_limited	Taxa de ingestão do workspace excedida. Tente novamente com backoff.
500	server_error	Transitório. Seguro repetir — o endpoint é idempotente.

Idempotência e novas tentativas

O endpoint é idempotente em (workspace_id, external_id). Reenviar o mesmo payload retorna a linha de conversão original com HTTP 200 (não 201). Use à vontade — novas tentativas de webhook da Stripe, Shopify e Kiwify nunca criam duplicatas.

Limites de taxa

Plano gratuito: 60 requisições / minuto. Planos pagos: 600 / minuto. Picos de até 2× a taxa sustentada são absorvidos sem 429s. Limites maiores disponíveis sob solicitação.