Ir al contenido principal

[Recepción de pedidos - GCW] Guía de referencia para la carga útil de eventos postback

T
Escrito por Toby Dawson
Actualizado hace más de 3 semanas

Esta guía es tu mapa para conocer todos los campos de datos disponibles en el payload de los diferentes eventos de activación de postback en GelatoConnect. Entender estos payloads te ayudará a crear plantillas efectivas que saquen justo la información que necesitas.

Introducción

Cuando se activa un evento de postback en GelatoConnect, se envía un paquete JSON con datos específicos del evento a tu endpoint configurado o se utiliza en notificaciones por correo electrónico. Este documento explica la estructura y el contenido de estos paquetes para cada tipo de evento, para que sepas qué datos tienes disponibles al crear tus plantillas.

Índice

Estado del paquete actualizado

Recibes esta notificación cuando el estado de un paquete cambia en el sistema.

{ "customer": { "id": "ea004496-8a31-42b7-b38a-77791152dbc7", "name": "Test Csutomer", "referenceId": "test-customer" }, "order": { "id": "ceebe91a-42e1-41ae-afdf-64569384f9bc", "referenceId": "Pedido de prueba", "metadata": { "isRush": "Falso" } }, "package": { "id": "reference_package_id", "items": [ { "id": "1614240f-3d24-4d44-b632-b1bd91b1981c", "quantity": 1, "referenceId": "product_18_reference_id", "metadata": { "item-type": "producto", "sku": "product_18_reference_id" } } ], "status": "enviado", "weight": 9 }, "shipment": { "fulfillmentLocation": { "country": "US", "stateProvince": "Wyoming" }, "method": { "id": "shipping_method_id", "name": "Nombre del método de envío" }, "tracking": { "code": "seguimiento_pedido_us", "url": "http://tracking.com/order_us" } }}

Campos de datos clave

  • customer: Incluye la información del cliente, como el ID, el nombre y el ID de referencia

  • order: Información básica del pedido y cualquier dato personalizado

  • package: Detalles sobre el paquete, como su estado, peso y artículos incluidos

  • shipment: Detalles del envío, como la ubicación, el método y la información de seguimiento

Pedido retrasado

Recibimos este mensaje cuando los pedidos se retrasan más allá de la fecha prevista de envío.

{ "currentDate": "29/11/2024 15:55:12", "customerId": "9290728b-8534-4227-a191-8036eed9f060", "orders": [ { "orderId": "0743ce64d7_test_order_6", "orderReferenceId": "G-231211113145", "expectedDispatchDate": "30/09/2024" }, { "orderId": "0743ce64d7_test_order_128", "orderReferenceId": "G-231211113145", "expectedDispatchDate": "13/11/2024" } ]}

Campos de datos clave

  • currentDate: Fecha y hora actual del sistema en el momento en que se detectó el retraso

  • customerId: ID del cliente asociado a los pedidos retrasados

  • orders: Lista de pedidos retrasados, cada uno incluye:

    • orderId: ID de pedido interno de GelatoConnect

    • orderReferenceId: Tu identificador de referencia para el pedido

    • expectedDispatchDate: La fecha de envío prevista que no se cumplió

Pedido cancelado

Este mensaje se recibe cuando se cancela un pedido.

{ "created": "03/08/2018 07:26:52", "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "J123X456", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "fulfillmentStatus": "cancelado", "channel": "api", "comment": "Pedido cancelado con éxito", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "cancelado", "metadata": { "item-type": "producto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campos de datos clave

  • created: Fecha y hora en la que se realizó la cancelación

  • orderId: ID de pedido interno de GelatoConnect

  • orderReferenceId: Tu identificador de referencia para el pedido

  • customerReferenceId: Identificador de referencia para el cliente

  • fulfillmentStatus: Estado actual ("cancelado")

  • comment: Información sobre el motivo o la forma en que se canceló el pedido

  • items: Lista de artículos en el pedido, cada uno con su propio estado y detalles

  • metadata: Metadatos personalizados a nivel de pedido

Pedido entregado

Recibes este mensaje cuando el pedido ha llegado a su destinatario.

{ "created": "03/08/2018 07:26:52", "fulfillmentStatus": "entregado", "orderReferenceId": "ASD4124123", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "channel": "api", "comment": "", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "entregado", "procesamientos": [ { "trackingCode": "code123", "trackingUrl": "http://example.com/tracking?code=code123", "shipmentMethodName": "DHL Express Nacional BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP", "deliveryDate": "05/08/2018 12:15", "recipientName": "John Doe", "recipientSignature": "signature_image_url" }, { "trackingCode": "code234", "trackingUrl": "http://example.com/tracking?code=code234", "shipmentMethodName": "DHL Express Nacional BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP", "deliveryDate": "05/08/2018 12:30", "recipientName": "Jane Smith", "recipientSignature": "signature_image_url_2" } ], "metadata": { "item-type": "producto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campos de datos clave

  • created: Fecha y hora en la que se realizó la entrega

  • fulfillmentStatus: Estado actual ("entregado")

  • orderReferenceId: Tu identificador de referencia para el pedido

  • items: Lista de artículos en el pedido, cada uno incluye:

    • procesamientos: Información detallada sobre la entrega, incluyendo:

      • trackingCode y trackingUrl: Información de seguimiento

      • shipmentMethodName: Nombre de la empresa de transporte

      • deliveryDate: Fecha en la que se entregó el artículo

      • recipientName: Quién recibió el paquete

      • recipientSignature: URL de la imagen de la firma (si está disponible)

El pedido no se ha completado

Este paquete se recibe cuando un pedido no pasa la validación o el procesamiento.

{ "created": "03/08/2018 07:26:52", "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "J123X456", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "fulfillmentStatus": "fallido", "channel": "api", "comment": "No se pudo enviar el pedido", "items": [ { "itemReferenceId": 123, "fulfillmentStatus": "fallido", "metadata": { "item-type": "producto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campos de datos clave

  • created: Fecha y hora en la que ocurrió el fallo

  • orderId: ID de pedido interno de GelatoConnect

  • orderReferenceId: Tu identificador de referencia para el pedido

  • fulfillmentStatus: Estado actual ("fallido")

  • comment: Información sobre el motivo por el que el pedido no se procesó correctamente

  • items: Lista de artículos del pedido, cada uno con su propio estado y metadatos

Pedido en camino

Recibes este mensaje cuando un pedido está de camino al destinatario.

{ "created": "17/09/2018 10:26:52", "fulfillmentStatus": "en tránsito", "orderReferenceId": "J123X456", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "channel": "api", "comment": "Pedido en tránsito", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "en camino", "procesamientos": [ { "trackingCode": "code567", "trackingUrl": "http://example.com/tracking?code=code567", "shipmentMethodName": "DHL Express Nacional BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" } ] } ]}

Campos de datos clave

  • created: Momento en que el estado del pedido cambió a "en tránsito"

  • fulfillmentStatus: Estado actual ("en tránsito")

  • orderReferenceId: Tu identificador de referencia para el pedido

  • items: Lista de artículos en el pedido, cada uno incluye:

    • procesamientos: Información de envío, incluyendo:

      • trackingCode y trackingUrl: Información de seguimiento

      • shipmentMethodName: Nombre de la empresa de transporte

      • fulfillmentCountry y fulfillmentStateProvince: Información sobre el lugar de origen

Pedido listo

Recibes este mensaje cuando un pedido ya se ha impreso o producido, pero todavía no se ha enviado.

{ "created": "03/08/2018 07:26:52", "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "J123X456", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "fulfillmentStatus": "impreso", "channel": "api", "comment": "Pedido impreso con éxito", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "impreso", "metadata": { "item-type": "producto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campos de datos clave

  • created: Fecha y hora en la que se generó el pedido

  • orderId: ID de pedido interno de GelatoConnect

  • orderReferenceId: Tu identificador de referencia para el pedido

  • fulfillmentStatus: Estado actual ("impreso")

  • comment: Información sobre la producción

  • items: Lista de artículos en el pedido, cada uno con su propio estado y metadatos

Pedido recibido

Este paquete se recibe cuando un pedido ha sido aceptado y validado correctamente en el sistema.

{ "created": "03/08/2018 07:26:52", "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "ASD4124123", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "fulfillmentStatus": "aprobado", "channel": "api", "comment": "Pedido realizado con éxito", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "aprobado", "metadata": { "item-type": "producto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campos de datos clave

  • created: Fecha y hora en la que se recibió el pedido

  • orderId: ID de pedido interno de GelatoConnect

  • orderReferenceId: Tu identificador de referencia para el pedido

  • fulfillmentStatus: Estado actual ("aprobado")

  • comentario: Información sobre la validación

  • items: Lista de artículos del pedido, cada uno con su propio estado y metadatos

Pedido devuelto

Este mensaje se recibe cuando un pedido ha sido devuelto al remitente.

{ "created": "03/08/2018 09:26:52", "fulfillmentStatus": "devuelto", "orderReferenceId": "ASD4124123", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "channel": "api", "comment": "Pedido devuelto con éxito", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "devuelto", "fulfillments": [ { "trackingCode": "code123", "trackingUrl": "http://example.com/tracking?code=code123", "shipmentMethodName": "DHL Express Nacional BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" }, { "trackingCode": "code234", "trackingUrl": "http://example.com/tracking?code=code234", "shipmentMethodName": "DHL Express Domestic BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" } ], "metadata": { "item-type": "producto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campos de datos clave

  • created: Fecha y hora en la que se gestionó la devolución

  • fulfillmentStatus: Estado actual ("devuelto")

  • orderReferenceId: Tu identificador de referencia para el pedido

  • items: Lista de artículos en el pedido, cada uno contiene:

    • procesamientos: Devuelve la información del envío, incluyendo:

      • trackingCode y trackingUrl: Información de seguimiento

      • shipmentMethodName: Nombre de la empresa de transporte

      • fulfillmentCountry y fulfillmentStateProvince: Información sobre el origen

Orden enviada

Este mensaje se recibe cuando un pedido ha sido enviado al destinatario.

{ "created": "03/08/2018 07:26:52", "fulfillmentStatus": "enviado", "orderReferenceId": "ASD4124123", "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0", "channel": "api", "comment": "Pedido enviado con éxito", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "enviado", "procesamientos": [ { "trackingCode": "code123", "trackingUrl": "http://example.com/tracking?code=code123", "shipmentMethodName": "DHL Express Nacional BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" }, { "trackingCode": "code234", "trackingUrl": "http://example.com/tracking?code=code234", "shipmentMethodName": "DHL Express Nacional BR", "shipmentMethodUid": "dhl_express_domestic_br", "fulfillmentCountry": "BR", "fulfillmentStateProvince": "SP" } ], "metadata": { "item-type": "producto", "sku": "123" } } ], "metadata": { "isRush": "Falso" }}

Campos de datos clave

  • created: Fecha y hora en la que se envió el pedido

  • fulfillmentStatus: Estado actual ("enviado")

  • orderReferenceId: Tu identificador de referencia para el pedido

  • items: Lista de artículos en el pedido, cada uno incluye:

    • procesamientos: Información de envío, incluyendo:

      • trackingCode y trackingUrl: Información de seguimiento

      • shipmentMethodName: Nombre de la empresa de transporte

      • fulfillmentCountry y fulfillmentStateProvince: Información de origen

Trabajar con metadatos

Muchos de los datos enviados en los eventos incluyen metadatos tanto a nivel de pedido como de artículo. Estos metadatos contienen pares clave-valor personalizados que puedes definir al enviar los pedidos y que luego se incluyen en los eventos de confirmación.

Ejemplos de uso de metadatos:

  1. Metadatos a nivel de pedido: metadata.isRush con valor "False"

  2. Metadatos a nivel de artículo: items[0].metadata.item-type con valor "product"

  3. Metadatos a nivel de artículo: items[0].metadata.sku con valor "123"

Estos metadatos pueden usarse para añadir información extra que no forma parte de los campos estándar, como indicadores de prioridad, SKU, categorías o cualquier otro dato que te ayude a gestionar tus pedidos.

Cómo usar estos datos en tus plantillas

Al crear plantillas para postbacks, puedes usar cualquier campo de estos datos utilizando el lenguaje de plantillas Jinja2. Por ejemplo:

  • Para acceder al ID de referencia del pedido: ####{{ orderReferenceId }}

  • Para acceder a un código de seguimiento: ####{{ items[0].fulfillments[0].trackingCode }}

  • Para acceder a los metadatos personalizados: ####{{ metadata.isRush }}

Para más información sobre cómo crear plantillas, consulta Cómo crear plantillas para la recepción de pedidos y Ejemplos de Template Mapper.

Para más información sobre cómo configurar los postbacks, consulta Cómo configurar los postbacks.

Artículos relacionados
[Recepción de pedidos - GCW] ¿Cómo configurar los postbacks?
[Recepción de pedidos - GCW] Documentación de la API de gestión de pedidos
[Recepción de pedidos - GCW] Ejemplos de mapeo de plantillas
[Recepción de pedidos - GCW] Trabajando con los puntos finales de la API de pedidos
[Recepción de pedidos - GCW] Conceptos básicos de la API de GelatoConnect
¿Ha quedado contestada tu pregunta?