Endpoint de ingesta de pedidos

Visión general

El registro de Pedidos acepta ventas ocurridas fuera de la plataforma. Recibes una URL de ingesta propia de la cuenta y envías cada pedido por POST — desde tu propio checkout, un ERP, una automatización o cualquier pasarela que ConversaLabs aún no integre de forma nativa.

La URL lleva un token opaco que identifica la cuenta. No hay otro encabezado de autenticación: quien tenga la URL puede registrar pedidos en tu cuenta, así que trátala como una contraseña.

Requisitos previos

• El módulo Pedidos debe estar habilitado en la cuenta. Con él apagado, la URL responde 404.
• Perfil de administrador (o permiso de gestión del CRM) para abrir y rotar el token.

Paso a paso

1. Abre Pedidos y haz clic en Endpoint de ingesta.
2. Copia la URL de ingesta. El campo Token aparece enmascarado — usa el ojo para mostrarlo y el botón contiguo para copiar solo el token.
3. Pega la URL en tu sistema de origen y envía el pedido como en el ejemplo.
4. Confirma que el pedido aparece en la lista. Reenviar el mismo external_id actualiza el pedido en lugar de crear otro.

curl -X POST 'https://TU-INSTALACION/public/api/v1/orders/ingest/TU-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "gateway": "mi_checkout",
    "external_id": "PED-10231",
    "email": "cliente@example.com",
    "title": "Plan Pro anual",
    "amount": 149.9,
    "currency": "USD",
    "status": "paid",
    "ordered_at": "2026-08-11T10:00:00-03:00",
    "line_items": [
      { "name": "Plan Pro anual", "quantity": 1, "unit_price": 149.9 }
    ]
  }'

Campos del cuerpo

Respuestas

• 201 — {"status": "ok"}. Pedido registrado o actualizado.
• 422 — invalid_payload (falta gateway), contact_reference_required (falta la referencia de contacto), invalid_order_status (estado fuera de la lista) o contact_unresolvable (no se pudo encontrar ni crear el contacto).
• 404 — token ausente, ya rotado, o módulo de Pedidos desactivado en la cuenta.

Configuración y opciones

• Configura el origen, secreto y mapeo solo para los campos que el integrador realmente envía.

Casos de uso

• Recibir pedidos de una tienda externa y enviarlos al catálogo y a los flujos de atención.

Consejos, límites y buenas prácticas

• Envía siempre external_id. Sin él, un reenvío de tu pasarela se convierte en un pedido duplicado.
• El endpoint tiene límite de tasa por token. En cargas grandes, envía en serie y espera de forma progresiva ante un 429.
• Rotar el token invalida la URL anterior de inmediato. Hazlo solo con la integración lista para recibir la nueva URL — y actualízala enseguida.
• Los importes van en unidades mayores, con punto decimal. No envíes céntimos como entero.

Solución de problemas

• Todo responde 404: la URL fue rotada o el módulo Pedidos está desactivado en la cuenta.
• 422 contact_reference_required: el cuerpo no llevó contact_id, email ni phone_number.
• El mismo pedido aparece dos veces: se envió sin external_id, o con un valor distinto en cada intento.
• El afiliado no recibió comisión: el affiliate_id no pertenece a esta cuenta o está inactivo.

Ver también

• Central de reconciliación de ventas
• Ciclo de vida del comercio