Conversiones
Cada venta que tu sistema cierra, reportada una vez. La venta queda registrada en Ventas con la pieza, el grupo, la campaña, el mercado y la oferta que la trajeron, cuando el clic lo permite, y se envía a tus propias cuentas de Google Ads (conversiones sin conexión por gclid, gbraid o wbraid) y de Meta (Conversions API, por fbclid, fbc o fbp). El correo y el teléfono, cuando los envías, se normalizan y se guardan solo como SHA-256.
Reportar una venta#
/api/v1/conversions
Bearer
Registra una venta de una de tus ofertas.
order_id
es la llave de idempotencia de tu organización: reportar el mismo pedido otra vez responde la venta ya registrada (
duplicate: true
) y no la cuenta dos veces. Con
test: true
validamos el cuerpo y resolvemos la atribución sin registrar nada ni enviarlo a las redes.
Content-Type: application/json
offer
string
requerido
La oferta vendida: su
id
o la clave externa que le diste en Ventas → Ofertas.
amount
string
requerido
El valor de la venta, como texto decimal (
"49.00"
) o número. Cero o más.
currency
string
requerido
Código ISO 4217 de la moneda (
USD
,
PEN
).
occurred_at
string
requerido
Cuándo se cerró la venta, en ISO 8601 con zona (
2026-09-25T14:03:00-05:00
). No puede estar en el futuro.
order_id
string
requerido
Tu número de pedido, hasta 128 caracteres. Único por organización.
gclid
string
El clic de Google Ads que trajo al comprador.
gbraid
string
El clic de Google Ads en apps de iOS.
wbraid
string
El clic de Google Ads en la web de iOS.
fbclid
string
El clic de Meta que trajo al comprador.
fbc
string
La cookie
_fbc
del navegador del comprador.
fbp
string
La cookie
_fbp
del navegador del comprador.
dcid
string
El parámetro
dcid
que Datil agrega a cada URL de destino: la campaña que compró el clic.
dcrid
string
El parámetro
dcrid
de la URL de destino: la pieza que produjo el clic.
email
string
El correo del comprador, tal cual o como SHA-256 hexadecimal del correo en minúsculas y sin espacios. Lo guardamos solo como SHA-256.
phone
string
El teléfono del comprador con código de país (
+51987654321
), o su SHA-256 hexadecimal. Lo guardamos solo como SHA-256.
utm_source
string
La fuente de la visita que terminó en la venta.
utm_medium
string
El medio de la visita.
utm_campaign
string
La campaña de la visita.
utm_content
string
El contenido de la visita.
utm_term
string
El término de la visita.
client_user_agent
string
El navegador del comprador; mejora la coincidencia en Meta.
client_ip_address
string
La dirección IP del comprador; mejora la coincidencia en Meta.
test
boolean
true
valida y resuelve la atribución sin registrar ni enviar la venta.
Devuelve
·
201
con la venta registrada ·
200
con la venta ya registrada del mismo
order_id
(
duplicate: true
) o con el resultado de una prueba (
test: true
) ·
401
sin llave válida ·
403
con una llave sin acceso a Ventas o una organización sin Ventas ·
422 validation_failed
con
errors
para cada regla:
missing_field:…
,
invalid_format:amount
,
invalid_format:currency
,
invalid_format:occurred_at
,
invalid_format:email
,
invalid_format:gclid
·
422 unknown_offer
para una oferta que tu organización no tiene ·
429
al superar el límite de solicitudes.
curl -X POST https://edge.datil.com/api/v1/conversions \
-H "Authorization: Bearer $DATIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"offer": "plan-pro",
"amount": "49.00",
"currency": "USD",
"occurred_at": "2026-09-25T14:03:00-05:00",
"order_id": "PED-2026-0042",
"gclid": "Cj0KCQjw8--2BhCHARIsAF_w1gw",
"fbc": "fb.1.1727287380000.IwAR2F4-dbP0l7Mn",
"email": "ana@example.com",
"utm_source": "google",
"utm_campaign": "plan-pro-ec"
}'{
"id": "7b0f6a52-3c1e-4d7e-9a57-0c1f5c2e9b10",
"object": "conversion",
"test": false,
"duplicate": false,
"order_id": "PED-2026-0042",
"offer": {
"id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
"external_key": "plan-pro"
},
"amount": "49.00",
"currency": "USD",
"occurred_at": "2026-09-25T19:03:00Z",
"event": "paid_first_invoice",
"attribution": {
"click_id": "0e9d8c7b-6a5f-4e3d-2c1b-0a9f8e7d6c5b",
"piece_id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"ad_group_id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"campaign_id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e",
"market_id": "4c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e8f",
"offering_id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
"channel": "google_search"
},
"forwarding": {
"google": "pending",
"meta": "pending"
},
"created_at": "2026-09-25T19:03:02Z"
}Consultar una venta#
/api/v1/conversions/:id
Bearer
Una venta de tu organización: la atribución que resolvió y en qué estado está con cada red (
forwarding
).
id
string
requerido
El
id
de la venta que devolvió el reporte.
Devuelve
·
200
con la venta ·
404 not_found
para una venta que no es de tu organización ·
401
sin llave válida.
curl "https://edge.datil.com/api/v1/conversions/7b0f6a52-3c1e-4d7e-9a57-0c1f5c2e9b10" \
-H "Authorization: Bearer $DATIL_API_KEY"{
"id": "7b0f6a52-3c1e-4d7e-9a57-0c1f5c2e9b10",
"object": "conversion",
"test": false,
"duplicate": false,
"order_id": "PED-2026-0042",
"offer": {
"id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
"external_key": "plan-pro"
},
"amount": "49.00",
"currency": "USD",
"occurred_at": "2026-09-25T19:03:00Z",
"event": "paid_first_invoice",
"attribution": {
"click_id": "0e9d8c7b-6a5f-4e3d-2c1b-0a9f8e7d6c5b",
"piece_id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"ad_group_id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"campaign_id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e",
"market_id": "4c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e8f",
"offering_id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
"channel": "google_search"
},
"forwarding": {
"google": "pending",
"meta": "pending"
},
"created_at": "2026-09-25T19:03:02Z"
}La atribución#
La cadena que la venta resolvió, de la pieza a la oferta. Cada clave es nula cuando el clic no la nombra o nombra filas de otra organización.
click_id
string
El clic registrado que trajo al comprador.
piece_id
string
La pieza (anuncio) que produjo el clic.
ad_group_id
string
El grupo de la pieza.
campaign_id
string
La campaña que compró el clic.
market_id
string
El mercado de la campaña.
offering_id
string
La oferta vendida.
channel
string
El canal de la visita, cuando se conoce.
El envío a las redes#
Dónde está la venta con cada red, en
forwarding.google
y
forwarding.meta
. La venta solo se envía a las cuentas que tu organización conectó en Ventas → Cuentas; nunca a otras.
pending
string
En cola o esperando un reintento.
uploaded
string
La red la aceptó.
held
string
Retenida por la configuración: sin cuenta conectada, sin píxel o sin acción de conversión. Sale sola cuando la configuración existe.
skipped
string
No lleva nada con qué la red pueda coincidir.
failed
string
La red la rechazó después de los reintentos.
none
string
La venta no lleva identificadores de esa red.
test
string
Una prueba: no se envía.