Passar para o conteúdo principal

[Entrada de Pedidos - GCW] Guia de Referência de Payload de Eventos de Postback

T
Escrito por Toby Dawson
Atualizado há mais de 2 semanas

Este guia oferece uma referência completa de todos os campos de dados disponíveis no payload para diferentes eventos de gatilho de postback no GelatoConnect. Entender esses payloads é essencial pra criar templates eficazes que extraem as informações de que você precisa.

Introdução

Quando um evento de Postback é acionado no GelatoConnect, um payload em JSON com dados específicos do evento é enviado para o endpoint configurado ou usado em notificações por e-mail. Este documento detalha a estrutura e o conteúdo desses payloads para cada tipo de evento, ajudando você a entender quais dados estão disponíveis ao criar seus modelos.

Sumário

Status do pacote atualizado

Este payload é recebido quando o status de um pacote muda dentro do sistema.

{  "customer": {    \"id\": \"ea004496-8a31-42b7-b38a-77791152dbc7\",    \"name\": \"Cliente de Teste\",    "referenceId": "test-customer"  },  "order": {    "id": "ceebe91a-42e1-41ae-afdf-64569384f9bc",    "referenceId": "Pedido-teste",    "metadata": {      \"isRush\": \"False\"    }  },"  "package": {    "id": "reference_package_id",    "itens": [      {        "id": "1614240f-3d24-4d44-b632-b1bd91b1981c",        "quantity": 1,        \"referenceId\": \"product_18_reference_id\",        "metadata": {          \"item-type\": \"product\",          "sku": "product_18_reference_id"        }      }    ],    "status": "enviado",    "peso": 9  },  "shipment": {    \"fulfillmentLocation\": {      "country": "US",      "stateProvince": "Wyoming"    },    \"method\": {      \"id\": \"shipping_method_id\",      "name": "Nome do método de envio"    },    "tracking": {      "code": "rastreamento_pedido_br",      "url": "http://tracking.com/order_us"    }  }}

Campos de dados principais

  • customer: Contém informações do cliente, incluindo ID, nome e ID de referência

  • order: Informações básicas do pedido e quaisquer metadados personalizados

  • package: Detalhes sobre o pacote, incluindo o status, o peso e os itens

  • shipment: Detalhes do envio, incluindo local, método e informações de rastreamento

Pedido atrasado

Este payload é recebido quando os pedidos são identificados como atrasados além das datas previstas de envio.

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

Campos de Dados Principais

  • currentDate: Data e hora atuais do sistema quando o atraso foi detectado

  • customerId: ID do cliente associado aos pedidos atrasados

  • orders: Array de pedidos atrasados, cada um contendo:

    • orderId: ID interno do pedido do GelatoConnect

    • orderReferenceId: Seu ID de referência para o pedido

    • expectedDispatchDate: A data de envio prevista que não foi cumprida

Pedido cancelado

Este payload é recebido quando um pedido é cancelado.

{  "created": "2018-08-03T07:26:52+00:00",  \"orderId\": \"a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9\",  "orderReferenceId": "J123X456",  \"customerReferenceId\": \"b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0\",  \"fulfillmentStatus\": \"cancelado\",  "channel": "api",  \"comment\": \"Pedido cancelado com sucesso\",  "itens": [    {      "itemReferenceId": "123",      "fulfillmentStatus": "cancelado",      "metadata": {        "item-type": "produto",        "sku": "123"      }    }  ],  "metadata": {    "isRush": "Falso"  }}

Campos de dados principais

  • created: Data e hora em que o cancelamento foi realizado

  • orderId: ID do pedido interno do GelatoConnect

  • orderReferenceId: Seu ID de referência para o pedido

  • customerReferenceId: ID de referência para o cliente

  • fulfillmentStatus: Status atual (\"cancelado\")

  • comment: Informações sobre por que ou como o pedido foi cancelado

  • items: Lista de itens do pedido, cada um com seu próprio status e metadados

  • metadata: Metadados personalizados no nível do pedido

Pedido entregue

Este payload é recebido quando um pedido foi entregue ao destinatário.

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

Campos de dados principais

  • created: Data e hora em que a entrega foi realizada

  • fulfillmentStatus: Status atual (\"entregue\")

  • orderReferenceId: Seu ID de referência para o pedido

  • items: Lista de itens do pedido, cada um contendo:

    • Atendimento de Pedidos: Informações detalhadas sobre a entrega, incluindo:

      • trackingCode e trackingUrl: Informações de rastreamento

      • shipmentMethodName: Nome da transportadora

      • deliveryDate: Quando o item foi entregue

      • recipientName: Quem recebeu o pacote

      • recipientSignature: URL para uma imagem da assinatura (se disponível)

Pedido Falhou

Este payload é recebido quando um pedido falha na validação ou no processamento.

{  "created": "2018-08-03T07:26:52+00:00",  "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9",  "orderReferenceId": "J123X456",  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",  "fulfillmentStatus": "falhou",  "channel": "api",  "comment": "Falha no envio do pedido",  "itens": [    {      "itemReferenceId": 123,      "fulfillmentStatus": "falhou",      "metadata": {        "item-type": "produto",        \"sku\": \"123\"      }    }  ],  "metadata": {    \"isRush\": \"False\"  }}

Campos de Dados Principais

  • created: Timestamp de quando a falha ocorreu

  • orderId: ID interno do pedido do GelatoConnect

  • orderReferenceId: Seu ID de referência para o pedido

  • fulfillmentStatus: Status atual (\"failed\")

  • comment: Informações sobre o motivo da falha do pedido

  • items: Array de itens no pedido, cada um com seu próprio status e metadados

Pedido em trânsito

Este payload é recebido quando um pedido está em trânsito para o destinatário.

{  \"created\": \"2018-09-17T10:26:52+00:00\",  "fulfillmentStatus": "em_transito",  "orderReferenceId": "J123X456",  \"customerReferenceId\": \"b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0\",  "channel": "api",  "comment": "Pedido em trânsito",  "itens": [    {      "itemReferenceId": "123",      "fulfillmentStatus": "em trânsito",      "atendimentosDePedidos": [        {          "trackingCode": "code567",          "trackingUrl": "http://example.com/tracking?code=code567",          "shipmentMethodName": "DHL Express Doméstico BR",          \"shipmentMethodUid\": \"dhl_express_domestic_br\",          "fulfillmentCountry": "BR",          "fulfillmentStateProvince": "SP"        }      ]    }  ]}

Campos de Dados Principais

  • created: Data e hora em que o status do pedido mudou para em trânsito

  • fulfillmentStatus: Status atual ("em trânsito")

  • orderReferenceId: Seu ID de referência para o pedido

  • items: Lista de itens do pedido, cada um contendo:

    • fulfillments: Informações de envio, incluindo:

      • trackingCode e trackingUrl: Informações de rastreamento

      • shipmentMethodName: Nome da transportadora

      • fulfillmentCountry e fulfillmentStateProvince: informações de origem

Pedido produzido

Este payload é recebido quando um pedido foi impresso/produzido, mas ainda não foi enviado.

{  \"created\": \"2018-08-03T07:26:52+00:00\",  \"orderId\": \"a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9\",  \"orderReferenceId\": \"J123X456\",  \"customerReferenceId\": \"b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0\",  \"fulfillmentStatus\": \"impresso\",  \"channel\": \"api\",  "comment": "Pedido impresso com sucesso",  \"items\": [    {      \"itemReferenceId\": \"123\",      \"fulfillmentStatus\": \"impresso\",      \"metadata\": {        "item-type": "produto",        "sku": "123"      }    }  ],  \"metadata\": {    \"isRush\": \"False\"  }}

Campos de Dados Principais

  • created: Data e hora em que o pedido foi gerado

  • orderId: ID de pedido interno do GelatoConnect

  • orderReferenceId: Seu ID de referência para o pedido

  • fulfillmentStatus: Status atual ("impresso")

  • comment: Informações sobre a produção

  • items: Lista de itens do pedido, cada um com seu próprio status e metadados

Pedido Recebido

Este payload é recebido quando um pedido é recebido e validado com sucesso no sistema.

{  "created": "2018-08-03T07:26:52+00:00",  \"orderId\": \"a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9\",  "orderReferenceId": "ASD4124123",  "customerReferenceId": "b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0",  \"fulfillmentStatus\": \"aprovado\",  "channel": "api",  \"comment\": \"Pedido processado com sucesso\",  \"items\": [    {      "itemReferenceId": "123",      "fulfillmentStatus": "aprovado",      "metadata": {        "item-type": "produto",        "sku": "123"      }    }  ],  "metadata": {    "isRush": "Falso"  }}

Campos de dados principais

  • created: Timestamp de quando o pedido foi recebido

  • orderId: ID interno do pedido do GelatoConnect

  • orderReferenceId: Seu ID de referência para o pedido

  • fulfillmentStatus: Status atual (\"aprovado\")

  • comentário: Informações sobre a validação

  • items: Lista de itens do pedido, cada um com seu próprio status e metadados

Pedido devolvido

Este payload é recebido quando um pedido foi devolvido ao remetente.

{  "created": "2018-08-03T07:26:52+00:00",  \"fulfillmentStatus\": \"devolvido\",  "orderReferenceId": "ASD4124123",  \"customerReferenceId\": \"b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0\",  \"channel\": \"api\",  "comment": "Pedido devolvido com sucesso",  "itens": [    {      \"itemReferenceId\": \"123\",      "fulfillmentStatus": "devolvido",      "atendimentosDePedidos": [        {          \"trackingCode\": \"code123\",          "trackingUrl": "http://example.com/tracking?code=code123",          "shipmentMethodName": "DHL Express Doméstico 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": "produto",        "sku": "123"      }    }  ],  "metadata": {    "isRush": "Falso"  }}

Campos de Dados Principais

  • created: Data e hora em que a devolução foi processada

  • fulfillmentStatus: Status atual ("devolvido")

  • orderReferenceId: Seu ID de referência para o pedido

  • items: Array de itens no pedido, cada um contendo:

    • fulfillments: Retorna informações sobre o envio, incluindo:

      • trackingCode e trackingUrl: Informações de rastreamento

      • shipmentMethodName: Nome da transportadora

      • fulfillmentCountry e fulfillmentStateProvince: informações de origem

Encomenda enviada

Este payload é recebido quando um pedido foi enviado ao destinatário.

{  "created": "2018-08-03T07:26:52+00:00",  \"fulfillmentStatus\": \"enviado\",  \"orderReferenceId\": \"ASD4124123\",  \"customerReferenceId\": \"b9v0e9ce-2bdd-4a9e-9f8d-0009df0e35d0\",  "channel": "api",  \"comment\": \"Pedido enviado com sucesso\",  "itens": [    {      \"itemReferenceId\": \"123\",      "fulfillmentStatus": "enviado",      "atendimentosDePedidos": [        {          "trackingCode": "code123",          \"trackingUrl\": \"http://example.com/tracking?code=code123\",          \"shipmentMethodName\": \"DHL Express Domestic 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\": \"product\",        \"sku\": \"123\"      }    }  ],  \"metadata\": {    \"isRush\": \"False\"  }}

Campos de dados principais

  • created: Data e hora em que o pedido foi enviado

  • fulfillmentStatus: Status atual (\"enviado\")

  • orderReferenceId: Seu ID de referência para o pedido

  • items: Lista de itens do pedido, cada um contendo:

    • fulfillments: Informações de envio, incluindo:

      • trackingCode e trackingUrl: Informações de rastreamento

      • shipmentMethodName: Nome da transportadora

      • fulfillmentCountry e fulfillmentStateProvince: Informações de origem

Trabalhando com metadados

Muitos dos payloads de eventos incluem metadados tanto no nível do pedido quanto no nível do item. Esses metadados contêm pares de chave e valor personalizados que você pode definir ao enviar pedidos, e que depois são incluídos nos eventos de postback.

Exemplos de uso de metadados:

  1. Metadados no nível do pedido: metadata.isRush com valor \"False\"

  2. Metadados em nível de item: items[0].metadata.item-type com valor \"product\"

  3. Metadados no nível do item: items[0].metadata.sku com valor \"123\"

Esses metadados podem ser usados para incluir informações adicionais que não fazem parte dos campos padrão, como sinalizadores de prioridade, SKUs, categorias ou quaisquer outros dados que ajudem no processamento do seu pedido.

Usando Esses Payloads em Modelos

Ao criar modelos para postbacks, você pode referenciar qualquer campo nesses payloads usando a linguagem de modelagem Jinja2. Por exemplo:

  • Para acessar o ID de referência do pedido: ##{{ orderReferenceId }}

  • Para acessar um código de rastreamento: ##{{ items[0].fulfillments[0].trackingCode }}

  • Para acessar metadados personalizados: ##{{ metadata.isRush }}

Para saber mais sobre como criar modelos, consulte Como criar modelos para recebimento de pedidos e Exemplos de uso do Template Mapper.

Para mais informações sobre como configurar postbacks, consulte Como configurar postbacks.

Artigos relacionados
[Entrada de Pedidos - GCW] Como configurar postbacks?
[Entrada de Pedidos - GCW] Documentação da API de Gerenciamento de Pedidos
[Entrada de Pedidos - GCW] Exemplos de Mapeador de Modelos
[Entrada de Pedidos - GCW] Trabalhando com Endpoints da API de Pedidos
[Entrada de Pedidos - GCW] Noções Básicas da API GelatoConnect
Respondeu à sua pergunta?