Subscrições a webhooks

AnteriorAtualização de estados SiguientePolling Contínuo

Última actualización hace 9 meses

Subscrições a webhooks

Processo

Este método envolve assinar um endpoint seu ao nosso webhook, para que sempre que houver uma mudança de estado dentro da plataforma, nós chamaremos esse endpoint para informá-lo da mudança. Dentro desse endpoint, você precisará interpretar o payload enviado por nós e atualizar o estado dentro do seu sistema.

Configuração

Para este ponto, você deve ter sua tabela pronta com os estados equivalentes do Shippify em sua plataforma. Se ainda não a tiver, acesse este link para elaborá-la. Para cada estado que precisar atualizar em sua plataforma, você terá que criar um webhook diferente seguindo os passos fornecidos:

Em sua conta do Shippify, vá para o menu à esquerda, escolha a seção de Automatizações, procure por "Enviar Webhook" no menu lateral esquerdo ou entre diretamente por este link e clique no botão "CRIAR AUTOMATIZAÇÃO +".

Escolha as regras para a execução da sua automação. Você precisa selecionar o escopo no qual a automação funcionará, o evento que ativará a automação e condições adicionais, se necessário.

Para o nosso caso, a entidade que vamos escolher é uma entrega e o evento é o estado para o qual você deseja enviar a atualização. No caso de você ter definido um motivo de problema de entrega ou uma etiqueta adicional em sua tabela, você deve adicionar esses dados como condições.

Nesta etapa, você precisa adicionar as informações do endpoint onde as notificações serão recebidas e configurar se deseja enviar dados adicionais.

Define os parâmetros necessários para sua Automatização de Webhook.

Parâmetro

Descrição

Obrigatório

Webhook

URL para a qual o payload do evento será enviado.

Método HTTP

Método de solicitação HTTP para enviar o payload.

Prova de entrega

Em caso de o evento ter imagens anexadas, escolha se deseja adicioná-las no seu payload como imagens. (Array[]).

HTTP Headers

Headers personalizados para a solicitação HTTP.

Assinatura do destinatário

Anexa a assinatura do destinatário como uma imagem PNG com fundo transparente. Ele é adicionado ao payload como 'signature'. (String)

Formato Base64

As imagens da prova de entrega ou assinatura são enviadas no formato base64. (Se não for marcado, então é uma URL).

URL de rastreamento

Inclui URL privada de rastreamento da entrega. Você a encontrará no payload como trackingUrl. (String)

Depois de configurar, clique em criar. Opcionalmente, você pode adicionar um nome. A partir desse momento, sempre que os eventos e condições forem atendidos, nós chamaremos seu endpoint notificando o evento.

Payload

O payload enviado para o webhook é extenso e contém muitas informações. Abaixo, mostraremos o significado de cada propriedade.

{
    "id": "t-xyz-123",
    "routeId": null,
    "networkId": 25,
    "networkName": "Default-company test",
    "jobId": null,
    "blocked": false,
    "cityId": 2,
    "cityName": "Guayaquil",
    "cityLang": "es",
    "companyId": 1,
    "companyName": "company test",
    "companyPlanType": "postpaid",
    "companyParentId": 1,
    "companyMode": 1,
    "shipperId": null,
    "shipperMobile": null,
    "type": "slot",
    "vehicleCapacity": 3,
    "vehicleId": null,
    "price": 0,
    "insurance": 0,
    "scheduledStartPickingDate": "2024-01-08T17:27:20.000Z",
    "scheduledEndPickingDate": "2024-01-08T17:57:20.000Z",
    "effectivePickupDate": "2024-01-08T16:33:44.000Z",
    "arrivalPickupDate": null,
    "scheduledStartDeliveryDate": "2024-01-08T18:12:20.000Z",
    "scheduledEndDeliveryDate": "2024-01-08T18:42:20.000Z",
    "effectiveDeliveryDate": "2024-01-08T17:27:07.000Z",
    "arrivalDeliveryDate": null,
    "creationDate": "2024-01-08T16:27:21.000Z",
    "pickupDueDate": null,
    "deliveryDueDate": null,
    "pickingPlace":{
      "lat": -2.1594806,
      "lng": -79.895742599,
      "originalAddress": "torres del norte, av. 9, guayaquil 090512, ecuador",
      "address": "torres del norte, av. 9, guayaquil 090512, ecuador"
    },
    "droppingPlace":{
      "lat": -2.1693477,
      "lng": -79.8985397,
      "originalAddress": "san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador",
      "address": "san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador"
    },
    "recipientInfo":{
      "name": "Test recipient",
      "email": "testrecip@test.com"
    },
    "senderInfo":{
      "name": "Test sender",
      "email": "testsender@test.com"
    },
    "senderInfoDecoded": {
        "name": "Test sender",
        "email": "testsender@test.com"
    },
    "receiverInfoDecoded": {
        "name": "Test recipient",
        "email": "testrecip@test.com"
    },
    "state": 7,
    "tags": ["delicado"],
    "items": [
        {
            "id": "Caja-12",
            "uuid": "bb3ef06e-647d-412b-92d1-293de6f5ce76",
            "name": "caixa",
            "size": "S",
            "price": 0,
            "weight": 0,
            "pickedUp": true,
            "delivered": true,
            "sid": "t-shippify2-40254_3",
            "scanned": false,
            "qty": 62
        }
    ],
    "referenceId": "test1234",
    "notes": "{\"comment\":\"test\"}",
    "attempts": 0,
    "countryCode": "EC",
    "countryName": "ECUADOR",
    "currencyCode": "USD",
    "formulaId": "1234",
    "cash": 0,
    "distance": 305.6000061035156,
    "distanceRoute": 0,
    "distanceCharged": 0,
    "totalPackagePrice": 0,
    "eventEntity": "delivery",
    "eventDate": "2024-01-08T17:27:08+00:00",
    "lastEventParams": {
        "author": {
            "type": "client",
            "id": 2534,
            "name": "Denny K. Saas",
            "email": "denny2@shippify.co"
        },
        "method": "UPDATE_ROUTE_STATUS",
        "timestamp": 1704734827
    },
    "colleted": 0,
    "paid": 0,
    "statusUpdateDate": null,
    "partial": 0,
    "notesJson": {
        "reason": "ADDRESS NOT FOUND, NEED CHANGE",
        "reasonId": 11,
        "comment": "test"
    },
    "itemsNumber": 62,
    "itemsWeight": 0,
    "itemsPrice": 0,
    "references": [],
    "incidences": [],
    "cityDepartment": null,
    "metadata": {
        "previousStatus": "processing"
    },
    "previousStatus": "processing",
    "dbId": 948182094,
    "eventType": "DELIVERY_COMPLETED",
    "eventAuthor": {
        "type": "client",
        "id": 2534,
        "name": "Denny K. Saas",
        "email": "denny2@shippify.co"
    },
    "eventCreatedAt": "2024-01-08 17:27:07",
    "eventDescription": "Delivery was completed (previous status was processing)",
    "eventParams": "{\"method\":\"UPDATE_ROUTE_STATUS\"}",
    "status": "completed",
    "eventId": 1704734828038,
    "images": ["https://cdn.dev.shippify.co/delivery-files/77030821377477563003dde3ce5.jpg"],
    "signature": "https://cdn.dev.shippify.co/delivery-files/16839098636794LPh1Zd7S5Goc9BvmQyG7BpT6asb.png",
    "trackingUrl": "https://api.shippify.co/track/t-xyz-123?token={token}"

}

Propiedad

Detalle

Identificador de la entrega

routeId

Identificador de la ruta

networkId

Identificador de la red de conductores

networkName

Nombre de la red de conductores

cityId

Identificador de la ciudad de recolección

cityName

Nombre de la ciudad de recolección

cityLang

Idioma de la ciudad de recolección

jobId

Identificador del proceso actual, null si no tiene proceso

blocked

Indica si la tarea esta bloqueada

companyId

Identificador de la compañía de la entrega

companyName

Nombre de la compañía de la entrega

companyPlanType

Plan de la compañía de la entrega (pre o post pago)

companyParentId

Identificador de la compañía padre de la entrega

companyMode

Tipo de compañía: 1 basica, 2 saas

shipperId

Identificador del conductor que realiza la entrega

shipperMobile

Número telefónico del conductor que realiza la entrega

type

Tipo de la entrega: flex, express o regular

vehicleCapacity

Capacidad del vehiculo 1-5 bicicleta-camion

vehicleId

Identificador del vehiculo

price

Precio de la entrega

insurance

Seguro de la entrega

scheduledStartPickingDate

Fecha estimada de inicio de recolección

scheduledEndPickingDate

Fecha estimada de final de recolección

effectivePickupDate

Fecha real de recolección

arrivalPickupDate

Fecha cuando el conductor llega al punto de recolección

scheduledStartDeliveryDate

Fecha estimada de inicio de etrega

scheduledEndDeliveryDate

Fecha estimada de final de entrega

effectiveDeliveryDate

Fecha real de entrega

arrivalDeliveryDate

Fecha cuando el conductor llega al punto de entrega

creationDate

Fecha de creación de la entrega

pickupDueDate

Fecha máxima de recolección

deliveryDueDate

Fecha máxima de entrega

pickingPlace

Información de recolección

pickingPlace.lat

Latitud del punto de recolección

pickingPlace.lng

Longitud del punto de recolección

pickingPlace.originalAddress

Dirección de recolección enviada por integración

pickingPlace.address

Dirección de recolección corregida por google

droppingPlace

Información de entrega

droppingPlace.lat

Latitud del punto de entrega

droppingPlace.lng

Longitud del punto de entrega

droppingPlace.originalAddress

Dirección de entrega enviada por integración

droppingPlace.address

Dirección de entrega corregida por google

recipientInfo

Información de la persona que va a recibir la entrega

senderInfo

Información de la persona que va a enviar la entrega

state

Código del estado de la entrega

Como testar o webhook?

Altere o status conforme apropriado para a automação, neste caso, alteraremos o status para Concluído porque é assim que configuramos nossa automação de teste.

Dentro da automação, você pode ver as execuções com falha e bem-sucedidas da automação junto com o identificador da entrega associada. Neste caso, temos uma execução bem-sucedida para a entrega t-pruaas-5104.

Assinantes de erros

Depois que o webhook for configurado com sucesso, as assinaturas de erro podem ser ativadas. Aqui você pode registrar um ou mais e-mails nos quais os alertas serão enviados sempre que uma notificação falhar ao ser enviada ou o endpoint responder com um erro.

Configuração personalizada

Exemplo de request

Bom dia,

Desejo atualizar os pedidos na minha plataforma através de um webhook com payload personalizado.

* Email da minha empresa na Shippify: iliana@shippify.co
* Tabela com os estados equivalentes no Shippify e os payloads personalizados: Documento anexo

Desde já agradeço,

Atenciosamente,
Iliana Bolaños