Crea y registra pedidos con la API

Un pedido en Hellotext tiene dos partes complementarias:

El objeto del pedido guarda la representación comercial: referencia, origen, productos, cantidades, precios, modalidad de entrega y otros datos del pedido.
Un evento del pedido conecta ese pedido con un perfil del cliente en un momento real de su ciclo, como creación, confirmación, envío, entrega o cancelación.

Crear solamente el objeto del pedido no registra una compra para un cliente. Crea o encuentra el pedido, conserva su ID de Hellotext y luego envía el evento del ciclo con ese pedido y el perfil correcto del cliente.

Usa la referencia de la API para consultar el contrato completo. Esta guía explica el flujo de integración recomendado.

Antes de comenzar

Prepara:

Un token privado de autorización para la API guardado únicamente en tu backend.
El ID en Hellotext del perfil del cliente asociado con el pedido.
Identificadores estables de productos o variantes ya sincronizados con Hellotext.
Una reference estable para el pedido en tu sistema.
Un mismo source, como custom_store, para todos los pedidos de la integración.
Las fechas originales de los eventos, los montos y los códigos de moneda ISO 4217.

Si todavía no sincronizaste los productos, comienza con Sincroniza productos y entiende la disponibilidad de inventario.

1. Crea el objeto del pedido

Crea el pedido después de que tu backend lo haya aceptado. Incluye la representación final de los artículos conocida en ese momento:

curl --request POST \
  --url https://api.hellotext.com/v1/attribution/orders \
  --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Pedido #1001",
    "reference": "ORDER-1001",
    "source": "custom_store",
    "delivery": "deliver",
    "payment_method": "Visa",
    "sales_channel": "Website",
    "items": [
      {
        "product": "PRODUCT_ID",
        "quantity": 2,
        "price": {
          "amount": 44.95,
          "currency": "USD"
        }
      }
    ],
    "metadata": {
      "warehouse": "main"
    }
  }'

Cada artículo requiere el identificador de un producto o variante. La API acepta su ID de Hellotext, referencia o SKU. Cuando omites el precio del artículo, Hellotext usa el precio actual del producto; incluye el precio cuando el pedido deba conservar el monto cobrado en el checkout.

Hellotext calcula el total del pedido a partir de sus artículos cuando un flujo de tracking compatible no envía el total. Guarda el id devuelto para el pedido en tu sistema como hellotext_order_id.

Consulta Crear un pedido para ver todos los campos compatibles.

2. Registra el primer evento real del ciclo

Después de crear el pedido, conéctalo con el perfil del cliente usando el primer estado que tu backend pueda confirmar:

curl --request POST \
  --url https://api.hellotext.com/v1/attribution/events \
  --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "order.placed",
    "profile": "PROFILE_ID",
    "object": "ORDER_ID",
    "amount": 89.90,
    "currency": "USD",
    "tracked_at": 1786104000
  }'

Usa tracked_at cuando el evento haya ocurrido antes de enviar la request. Debe representar la fecha del evento en el sistema de origen, no la fecha del reintento.

Una request válida responde con:

{
  "status": "received"
}

Esto significa que el evento fue aceptado para su procesamiento. Puede demorar un poco en aparecer en el perfil del cliente y en los reportes.

3. Envía cada estado posterior cuando ocurra

Reutiliza el mismo ID del pedido y perfil del cliente para cada transición confirmada:

order.confirmed cuando el negocio confirma el pedido.
order.shipped cuando el pedido sale para su entrega.
order.delivered cuando se confirma la entrega.
order.cancelled cuando el pedido se cancela.

Por ejemplo:

curl --request POST \
  --url https://api.hellotext.com/v1/attribution/events \
  --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "order.shipped",
    "profile": "PROFILE_ID",
    "object": "ORDER_ID",
    "tracked_at": 1786190400
  }'

No envíes todos los estados al crear el pedido. No deduzcas el envío o la entrega solamente por el tiempo transcurrido. Cada evento debe provenir de una transición que tu sistema pueda verificar.

Consulta Registrar eventos de pedidos para ver las acciones y parámetros compatibles actualmente.

4. Corrige los datos del pedido por separado de su ciclo

Actualizar el objeto de un pedido modifica sus atributos almacenados; no crea un evento del ciclo.

Usa PATCH /v1/attribution/orders/:id para corregir campos como modalidad de entrega, método de pago, canal de venta, metadata o propiedades personalizadas. Usa los endpoints de artículos del pedido cuando necesites corregir productos, cantidades o precios cobrados.

Envía un evento nuevo únicamente cuando haya ocurrido un cambio real del ciclo. Por ejemplo, corregir el método de pago no justifica volver a enviar order.confirmed.

Consulta Actualizar un pedido y la referencia de artículos de pedidos.

5. Importa pedidos históricos sin hacerlos parecer recientes

Los pedidos históricos ayudan a Hellotext a entender actividad previa de clientes y productos. Para cada pedido importado:

Crea el pedido con su referencia, origen, productos, cantidades y precios cobrados originales.
Registra únicamente el estado del ciclo que tus datos históricos puedan verificar.
Establece tracked_at con la fecha original del evento.
Conserva el monto y la moneda originales.

No uses la fecha de importación como tracked_at. De lo contrario, compras antiguas pueden parecer comportamiento actual y afectar segmentos, decisiones de playbooks y reportes.

6. Evita pedidos y eventos duplicados

La API no expone un parámetro general de idempotencia. Tu integración debe conservar su propio estado de entrega.

Mantén source y reference estables durante toda la vida del pedido.
Guarda el ID de Hellotext devuelto por la primera creación exitosa.
Asigna un ID interno estable a cada transición del ciclo en el sistema de origen.
Marca ese evento de origen como entregado únicamente después de que Hellotext responda con status: received.
No envíes el mismo evento de pedido desde Hellotext.js y desde tu backend.
Si vence el tiempo de una request de creación, reconcilia el pedido antes de enviar otro POST; la request original podría haberse completado.

Para las acciones preestablecidas del ciclo de un pedido, Hellotext guarda un evento por cada combinación de pedido y acción. Por ejemplo, volver a enviar order.shipped para el mismo pedido no agrega otro evento de envío.

Esta regla no es idempotencia general de la API. Otros tipos de eventos todavía pueden duplicarse y una acción diferente del ciclo para el mismo pedido sigue siendo otro evento. Tu integración debe evitar envíos duplicados y conservar un registro confiable del origen.

7. Verifica un pedido de principio a fin

Antes de importar todo el historial de pedidos:

Crea un perfil de cliente de prueba fácil de reconocer.
Crea o recupera sus productos y variantes.
Crea un pedido y guarda el ID devuelto.
Envía un evento real del pedido.
Confirma que el evento aparezca en el perfil correcto del cliente.
Confirma productos, cantidades, monto, moneda y fecha original.
Envía un estado posterior y verifica que se reutilice el mismo pedido.

Si la request falla o el evento no aparece, usa Soluciona una integración propia.

Guías relacionadas

¿No encontraste tu respuesta?

Contáctanos