> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ararahq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Atribuição de conversão

> Reporte vendas do seu backend para Arara e ligue cada conversão à última mensagem enviada ao cliente. Alimenta a métrica de conversão do teste A/B e o valor recuperado da recuperação de receita.

Segundo passo depois dos [Smart Links](/smart-links): o clique já é registrado automaticamente, e para saber se o cliente **comprou** o seu backend reporta a conversão para a Arara, que liga a venda à última mensagem enviada àquele telefone.

<Note>
  Não existe pixel JavaScript nem integração nativa com Shopify, WooCommerce ou Stripe para conversão. A atribuição é feita por chamada server-side, com o telefone como chave.
</Note>

## Como a atribuição funciona

1. Você envia `phone`, `order_id` e `value` para o endpoint de conversão da sua organização.
2. A Arara procura a última mensagem enviada a esse telefone nos **últimos 7 dias**.
3. Se encontrar, a conversão fica ligada a essa mensagem.
4. A conversão atribuída alimenta a métrica `CONVERTED` do [teste A/B de campanha](/marketing) e o valor recuperado em `GET /v1/recovery/stats`.

## Endpoint de conversão

Cada organização tem um endpoint próprio, com código no formato `ara_cnv_...`. Ele nasce ativo.

<Warning>
  Hoje `GET /v1/conversions/endpoint` só aceita a sessão do dashboard: chamado com chave `ara_live_`, responde `403`. Enquanto isso não muda, peça o código do seu endpoint ao suporte.
</Warning>

| Endpoint (sessão do dashboard) | Função |
| - | - |
| `GET /v1/conversions/endpoint` | `{ code, hmacSecret, active, url }` |
| `POST /v1/conversions/endpoint/regenerate` | Gera novo código |
| `GET /v1/conversions/ingests?page=0&size=20` | Conversões recebidas `{ content, totalPages, totalElements }` |

## Reportando uma conversão

Quando o pedido for confirmado no seu backend:

```bash theme={null}
curl -X POST https://api.ararahq.com/l/ara_cnv_xxx \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511999999999",
    "order_id": "ORDER_12345",
    "value": 199.90
  }'
```

```javascript theme={null}
await fetch(`https://api.ararahq.com/l/${conversionCode}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phone: order.customerPhone,   // E.164
    order_id: order.id,
    value: order.total,           // em reais, ex.: 199.90
  }),
});
```

| Campo | Descrição |
| - | - |
| `phone` | Telefone do cliente. É a chave de atribuição |
| `order_id` | Id do pedido (`orderId` também é aceito). Um `order_id` já recebido não gera nova conversão |
| `value` | Valor da venda, em reais |

O header opcional `X-Arara-Event` define o tipo registrado (default `conversion`).

A resposta é `202`:

```json theme={null}
{
  "ingestId": "ara_civ_...",
  "attributedCampaignId": null,
  "attributedMessageId": "ara_msg_..."
}
```

`attributedMessageId` vem `null` quando não houve mensagem para esse telefone nos últimos 7 dias.

<Warning>
  **Mande sempre `order_id`.** Gateways reenviam webhook. Sem `order_id`, cada reenvio vira uma conversão nova.
</Warning>

<Note>
  Use `https://api.ararahq.com/l/{code}`. O `url` devolvido pelo endpoint aponta para `ararahq.com/l/{code}`, que só aceita `GET`.
</Note>

## A partir do webhook do seu gateway

Shopify (`orders/paid`), Stripe (`checkout.session.completed`), WooCommerce e AbacatePay avisam quando o pedido é pago. No handler desse webhook, faça o `POST` acima com o telefone, o id e o valor do pedido.

## Validando

| Sintoma | Causa provável |
| - | - |
| `attributedMessageId` nulo | Nenhuma mensagem para esse telefone nos últimos 7 dias, ou telefone em formato diferente do usado no envio. Use E.164 (`+5511999999999`) |
| Conversão não aparece de novo | O `order_id` já tinha sido recebido |
| Valor recuperado zerado na recuperação de receita | A conversão não foi atribuída a uma mensagem de recuperação |
| `403 RECOVERY_ENDPOINT_INACTIVE` | Endpoint de conversão desativado |

## Dados registrados

* Clique: IP, user agent, referer e país (quando disponível).
* Conversão: telefone, `order_id`, valor e o corpo recebido.

Declare na sua política de privacidade que usa a Arara para medir resultado das mensagens. Ver [Compliance](/concepts/compliance).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Recuperação de receita" icon="rotate-right" href="/recovery">
    Mensagens automáticas a partir de eventos.
  </Card>

  <Card title="Campanhas de marketing" icon="bullhorn" href="/marketing">
    Teste A/B com a métrica CONVERTED.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.