Recaudo Docs

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.
Esc