Loja
Vendas de outros sistemas
Se as suas vendas fecham em outro sistema (seu CRM, ponto de venda ou ERP), envie-as aqui. O Recaudo encontra o cliente, liga a venda ao anúncio que o trouxe e diz à Meta quanto você vendeu, para a campanha buscar mais gente que compra e não só quem escreve.
Registrar uma venda
POST
/v1/sales
Chame quando a venda fechar. Se enviar de novo com o mesmo external_id, ela é atualizada; nunca duplica.
| Campo | Descrição |
|---|---|
| external_id * | Id da venda no seu sistema. Único por negócio; é o que evita contá-la duas vezes. |
| amount * | Valor total da venda, com decimais. |
| currency | Moeda ISO 4217. Por padrão, a do seu negócio. |
| sold_at | Data e hora da venda em ISO 8601. Por padrão, agora. |
| status | completed (padrão) ou cancelled para anular uma venda já enviada. |
| description | O que foi vendido, texto livre. |
| customer | Quem comprou: id, external_id, email, phone e name. Telefone ou e-mail basta. |
| conversation_id | A conversa do Recaudo, se o seu sistema souber. Tem prioridade sobre a busca por cliente. |
| ad_id | O id do anúncio da Meta, se o seu sistema souber. |
| metadata | Dados extras do seu sistema. Voltam como foram enviados. |
Requisição
curl -X POST "https://recaudo.app/api/v1/sales" \
-H "Authorization: Bearer sk_live_tu_secret_key" \
-H "Content-Type: application/json" \
-d '{
"external_id": "CRM-1001",
"amount": 33012.00,
"currency": "MXN",
"sold_at": "2026-11-20T12:30:00-06:00",
"description": "Plan anual",
"customer": {
"phone": "+52 55 1234 5678",
"email": "cliente@ejemplo.com",
"name": "Ana López"
}
}'
Resposta
{
"object": "sale",
"id": "9a7c1e2b-4d3f-4a1b-9c8d-7e6f5a4b3c2d",
"external_id": "CRM-1001",
"order_number": "ORD-2026-000184",
"amount": 33012.0,
"currency": "MXN",
"status": "completed",
"sold_at": "2026-11-20T12:30:00-06:00",
"description": "Plan anual",
"customer": {
"id": "5b1f0c3e-2a4d-4e6f-8b9a-0c1d2e3f4a5b",
"name": "Ana López",
"matched_by": "phone"
},
"attribution": {
"conversation_id": "0d9e8f7a-6b5c-4d3e-2f1a-0b9c8d7e6f5a",
"ad_id": "120251597851470124",
"ad_name": "video_plan_anual",
"campaign_id": "120250996966730124",
"campaign_name": "Mensajes WhatsApp noviembre"
},
"metadata": null,
"created_at": "2026-11-20T18:30:02+00:00",
"updated_at": "2026-11-20T18:30:02+00:00"
}
- Cliente: buscado pelo id do Recaudo, depois external_id, e-mail e telefone (últimos 10 dígitos). Se não existir e vier telefone ou e-mail, é criado. matched_by diz por qual dado foi encontrado.
- Anúncio: vale o último anúncio que trouxe o cliente nos 90 dias anteriores à venda. Se não veio de um anúncio, attribution.ad_id vem vazio e a venda é salva mesmo assim.
- Novas tentativas: se a chamada falhar no meio ou você não souber se chegou, envie de novo com o mesmo external_id. Responde 201 na primeira vez e 200 nas seguintes.
- Cancelamentos: envie a mesma venda com status cancelled. Ela deixa de contar nos relatórios de anúncios.
- Meta: a venda é enviada como Purchase com o valor ao pixel e, se o cliente veio de um anúncio de WhatsApp, ao dataset dessa linha. É enviada uma vez por venda.
- Onde aparece: em Pedidos (origem "Outro sistema") e em Anúncios da Meta, onde conta para vendas, custo por venda e receita de cada anúncio e campanha.
Consultar uma venda
GET
/v1/sales/{external_id}
Retorna a venda pelo id do seu sistema, com o cliente e o anúncio e a campanha aos quais foi atribuída.
Esta página ajudou?
Obrigado por avisar.