## 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 Conversa Labs 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

| Campo | Obligatorio | Qué es |
|---|---|---|
| `gateway` | Sí | Identifica el origen del pedido (ej.: `mi_checkout`, `hotmart`). |
| `contact_id` / `email` / `phone_number` | Sí (uno de ellos) | Referencia para encontrar o crear el contacto. Envía también `name` para nombrar uno nuevo. |
| `external_id` | No, pero recomendado | El identificador del pedido en tu sistema. Es lo que hace idempotente el reenvío. |
| `status` | No | Uno entre `pending`, `partially_paid`, `paid`, `overdue`, `failed`, `canceled`, `refunded`. |
| `amount` y `currency` | No | Importe total en unidades mayores (`149.9` = 149,90) y la moneda en ISO-4217. |
| `ordered_at` y `paid_at` | No | Fechas ISO-8601 con zona horaria. Sin ellas se usa el momento de recepción. |
| `line_items` | No | Ítems con `name`, `quantity`, `unit_price` y, cuando exista, `catalog_product_id`, `catalog_variant_id`, `discount` y `metadata`. |
| `title`, `crm_item_id`, `affiliate_id`, `metadata`, `raw` | No | Complementos. El afiliado solo se acredita si pertenece a esta cuenta y está activo. |

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

## 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](/hc/ajuda/articles/catalog-commerce-reconciliacao-de-vendas-es)
- [Ciclo de vida del comercio](/hc/ajuda/articles/catalog-commerce-commerce-lifecycle-es)