Recaudo Docs

Tienda

Ventas de otros sistemas

Si tus ventas se cierran en otro sistema (tu CRM, tu punto de venta o tu ERP), mándalas aquí. Recaudo encuentra al cliente, liga la venta al anuncio que lo trajo y le dice a Meta cuánto vendiste, para que la campaña busque a más gente que compra y no solo a la que escribe.

Registrar una venta

POST /v1/sales

Llámalo cuando se cierra la venta. Si la mandas otra vez con el mismo external_id, se actualiza; no se duplica.

Campo Descripción
external_id * Id de la venta en tu sistema. Es único por negocio y es lo que evita contarla dos veces.
amount * Monto total de la venta, con decimales.
currency Moneda ISO 4217. Si no viene, la de tu negocio.
sold_at Fecha y hora de la venta en ISO 8601. Si no viene, ahora.
status completed (por defecto) o cancelled para anular una venta que ya mandaste.
description Qué se vendió, en texto libre.
customer Quién compró: id, external_id, email, phone y name. Con teléfono o correo basta.
conversation_id La conversación de Recaudo, si tu sistema la conoce. Gana sobre la búsqueda por cliente.
ad_id El id del anuncio de Meta, si tu sistema lo conoce.
metadata Datos extra de tu sistema. Se devuelven tal cual.
Petición
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"
    }
  }'
Respuesta
{
  "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: se busca por id de Recaudo, luego external_id, correo y teléfono (últimos 10 dígitos). Si no existe y trae teléfono o correo, se crea. matched_by dice por cuál dato se encontró.
  • Anuncio: gana el último anuncio que trajo al cliente en los 90 días anteriores a la venta. Si no llegó por un anuncio, attribution.ad_id viene vacío y la venta se guarda igual.
  • Reintentos: si tu llamada falla a medias o no sabes si llegó, mándala otra vez con el mismo external_id. Responde 201 la primera vez y 200 las siguientes.
  • Cancelaciones: manda la misma venta con status cancelled. Deja de contar en los reportes de anuncios.
  • Meta: la venta se manda como Purchase con su monto al píxel y, si el cliente llegó por un anuncio de WhatsApp, al dataset de esa línea. Se manda una sola vez por venta.
  • Dónde se ve: en Pedidos (origen "Otro sistema") y en Anuncios de Meta, donde cuenta para ventas, costo por venta y lo cobrado de cada anuncio y campaña.

Consultar una venta

GET /v1/sales/{external_id}

Devuelve la venta por el id de tu sistema, con el cliente y el anuncio y la campaña a los que se atribuyó.

¿Te sirvió esta página? Gracias por avisarnos.
Esc