Webhook

O que são Webhooks?

Webhooks são notificações automáticas enviadas pela plataforma AllPost para a sua aplicação sempre que um evento relevante ocorre. Em vez de sua aplicação consultar repetidamente a API para verificar atualizações, a AllPost envia uma requisição HTTP POST diretamente para a URL configurada no seu sistema.

Como funciona

• Todas as requisições de webhook são enviadas com o método POST, com o conteúdo no corpo (body) no formato JSON e headers: Content-Type: application/json; charset=UTF-8.
• A plataforma espera que sua aplicação responda com o código HTTP 2XX (200, 201, etc) em no máximo 10 segundos. Códigos de redirecionamento (3XX) não serão seguidos e serão considerados como falha.
• São realizadas 5 tentativas de envio caso seu sistema esteja fora do ar ou responda com um código HTTP diferente de 200 ou 201.
• Como o webhook possui várias funcionalidades, você deve retornar código HTTP 200 para as funcionalidades não implementadas, evitando que o sistema fique realizando reenvio de eventos.

Configuração

Para cadastrar a URL do seu webhook, utilize o endpoint de cadastro via API:

POST api/v1/webhook/novo

O cadastro da URL também pode ser realizado diretamente no portal de desenvolvedor. A URL configurada receberá todas as notificações de eventos da loja associada.

Formato da URL de destino:

https://{seu_dominio}/{uri_opcional}

Tipos de Eventos

Rastreio de ocorrências do pedido

Enviado quando há atualização de status no rastreio do pedido.

• "idOcoren": 1 e 2 — "situacao": "entregue"
• "idOcoren": 99 — "situacao": "criado"
• "idOcoren": 99 — "situacao": "postado"
• "idOcoren": 99 — "situacao": "em transito"
• "idOcoren": 99 — "situacao": "saiu para entrega"
• "idOcoren": 3 até 92 — "situacao": "ocorrencia" — "mensagem": "mensagem da ocorrência"

Rastreio de eventos do pedido

Enviado para eventos intermediários de rastreio (chegada em unidade, etc).

Alteração nos prazos adicionais

Enviado quando há alteração nos prazos de filial ou método de envio.

Desinstalação de aplicativo

Enviado quando uma aplicação é desinstalada da loja.

Manutenção de método de envio

Enviado quando um método de envio é criado, alterado ou removido.

Exemplos de Payload

Rastreio de ocorrências do pedido

{
    "tipo": "Rastreio",
    "dados": {
        "idPedido": "",
        "numeroPedido": "",
        "pedidoAuxiliar": "",
        "idCotacao": "",
        "canal": "",
        "plataforma": "",
        "transportadora": "",
        "metodoEnvio": "",
        "idOcoren": 99,
        "situacao": "saiu para entrega",
        "mensagem": "Transportadora saiu para entregar o produto",
        "infAdicional": "Saida para entrega na cidade de NOVO SANTO ANTONIO",
        "data": "2022-08-11 09:53:00"
    }
}

Rastreio de eventos do pedido

{
    "tipo": "RastreioEventos",
    "dados": {
        "idPedido": "",
        "numeroPedido": "",
        "pedidoAuxiliar": "",
        "idCotacao": "",
        "canal": "",
        "plataforma": "",
        "transportadora": "",
        "metodoEnvio": "",
        "idOcoren": 99,
        "situacao": "evento",
        "mensagem": "CHEGADA EM UNIDADE",
        "infAdicional": "Chegada na unidade ALTO BOA VISTA",
        "data": "2022-08-11 09:53:00"
    }
}

Alteração nos prazos adicionais

{
    "tipo": "prazoAdicional",
    "dados": {
        "maior": {
            "prazoFilial": 2,
            "prazoMetodo": 0,
            "perAdicionalDesconto": 12
        },
        "menor": {
            "prazoFilial": 1,
            "prazoMetodo": 0,
            "perAdicionalDesconto": 12
        },
        "data": "2022-08-11 09:53:00"
    }
}

Desinstalação de aplicativo

{
    "tipo": "Aplicativo",
    "dados": {
        "codigo": "",
        "situacao": "delete",
        "mensagem": "A aplicação foi desinstalada",
        "idApp": 0,
        "nomeApp": "",
        "data": "2022-08-11 09:53:00"
    }
}

Manutenção de método de envio

{
    "tipo": "metodoEnvio",
    "dados": {
        "codigo": "",
        "situacao": "novo|altera|delete",
        "idTransportadora": 0,
        "idMetodoEnvio": 0,
        "nomeTransportadora": "",
        "nomeMetodoEnvio": "",
        "data": "2022-08-11 09:53:00"
    }
}

Resposta esperada

Sucesso (HTTP 200 ou 201)

{
    "retorno": "sucesso",
    "obs": ""
}

Erro (HTTP 400 até 599)

{
    "retorno": "sua mensagem de erro"
}

Logs de Webhook

Acompanhe os logs dos webhooks no painel administrativo. Acesse o sistema AllPost com sua conta de desenvolvedor, selecione a loja no topo da página e navegue até Menu > Log > Webhook. Você pode analisar e forçar o reenvio de webhooks com falha de comunicação.