Webhooks

Dispara ao criar um pedido de entrega local (Delivery / Pickup / P2P) por qualquer caminho: formulário web, API REST/GraphQL, sincronização com plataforma de e-commerce, regras automáticas, linhas importadas, etc. Exclui pedidos label-service e outros tipos que não são de entrega. Ignorado no fluxo em lote quando o mesmo destinatário também tem order_create_async_postback_url configurado. Configure via order_create_webhook_url.

Dispara a cada transição de status — coletado, em trânsito, entregue, exceção, cancelado. Configure via order_status_change_webhook_url.

Dispara a cada evento do ciclo de vida do rastreamento (informações enviadas, início da entrega, entrega bem-sucedida, não entregue, etc.). Configure via tracking_event_webhook_url. Os eventos de entrega e de coleta também trazem o comprovante de entrega: proof_files e proof_files_detail (file_id, type, url, full_url, URL de download assinada). Fotos enviadas após o evento chegam como pod.files_updated. Cada arquivo também traz o contexto do seu evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); em arquivos antigos sem evento registrado são null.

Dispara uma vez após o processamento de uma importação em lote. O payload contém o array de resultados por linha. Configure via order_create_async_postback_url.

Disparado quando uma foto de entrega ou assinatura é adicionada, substituída ou removida (action: added / updated / removed) — um envio por arquivo, sem mais polling de anexos. Ativado configurando pod_files_webhook_url. Cada arquivo também traz o contexto do seu evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); em arquivos antigos sem evento registrado são null.

Disparado quando um pedido é excluído permanentemente, para que seu sistema possa espelhar a remoção. Ativado configurando order_deleted_webhook_url.

Disparado quando uma tentativa de cancelamento é rejeitada (por exemplo, o pedido já está em rota de entrega), para que sua operação possa monitorar cancelamentos com falha sem consultar a API. Ativado configurando order_cancel_failed_webhook_url.

Disparado quando um lugar do quadro de rotas muda de titular ou o quadro muda de estado — o campo action indica o que aconteceu (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Apenas ao nível da empresa. Assinatura via route_board_webhook_url.

Portas Abertas — Dispara no momento em que as portas dos cacifos se abrem para uma tentativa de entrega — quer o estafeta tenha usado o ecrã do cacifo com o código de acesso quer a API de abertura remota — incluindo reaberturas por reatribuição. O bloco opening lista cada compartimento aberto com o grid_id, o número de porta de hardware compartment_number e o pickup_locker_number (número sequencial de exibição contado de cima para baixo por coluna e depois da esquerda para a direita). Cada compartimento traz ainda pickup_locker_code — a etiqueta "{shelf_code}-{pickup_locker_number}" para onde o destinatário é encaminhado; null quando o compartimento não tem número de recolha. O payload inclui também pickup_code — o código de recolha do destinatário, atribuído no momento em que as portas se abrem; permanece o mesmo código depois de o estafeta confirmar o depósito e só passa a poder ser usado para recolha após essa confirmação.

Entregue no cacifo — Disparado quando um depósito é confirmado e os pacotes estão no armário. O payload inclui o código de retirada do destinatário. Cada compartimento traz ainda pickup_locker_code — a etiqueta "{shelf_code}-{pickup_locker_number}" para onde o destinatário é encaminhado; null quando o compartimento não tem número de recolha. Para portas abertas através da API de abertura remota, a plataforma liquida o depósito assim que o armário comunica que todas as portas abertas foram fechadas, pelo que este evento dispara sem chamada a confirm; confirmed_by indica a via de liquidação: courier_terminal, partner_api, door_close, timeout_door_closed ou console.

Recolhido — Disparado quando o destinatário retirou os pacotes depositados.

Falha na entrega — Disparado quando uma entrega falha; códigos de falha por pacote são incluídos.

Expirado — Disparado quando um código de entrega não utilizado ou um depósito não retirado ultrapassa o prazo de validade.

Cancelado — Disparado quando uma entrega é cancelada antes da conclusão.

Reabertura de correção — Disparado quando os compartimentos ocupados são reabertos dentro da janela de correção para corrigir uma colocação errada — pela tela do armário ou via API. O bloco correction lista os compartimentos reabertos. Cada compartimento traz ainda pickup_locker_code — a etiqueta "{shelf_code}-{pickup_locker_number}" para onde o destinatário é encaminhado; null quando o compartimento não tem número de recolha.

partner_locker_delivery.event_type_code_rotated — Dispara quando o parceiro renova o código de entrega ou o código de recolha de uma entrega. O bloco rotation indica que código foi substituído, quando e se a notificação ao destinatário foi reenviada — o novo código nunca viaja num webhook; é revelado apenas na resposta direta da API de renovação.

Atribuição Criada — Disparado quando um pedido é atribuído ao fornecedor — por regra automática ou manualmente. O payload contém o número da atribuição, os identificadores do pedido e os números de rastreamento dos pacotes.

Pacotes Entregues em Mãos — Disparado quando o armazém entregou fisicamente todos os pacotes da atribuição ao fornecedor.

Atribuição Cancelada — Disparado quando a plataforma retira uma atribuição do fornecedor. O campo reason distingue cancelled (a atribuição foi cancelada na transportadora), fallback_to_self_delivery (a plataforma retomou o pedido para entrega própria) e reassigned (o pedido foi movido para outro fornecedor).

Entrega parcial — É acionado quando parte de um envio foi entregue enquanto outros volumes continuam em curso. O array packages traz o resultado de cada volume e legs lista as encomendas externas registadas na transportadora — uma por volume quando a transportadora não aceita envios com vários volumes.

Um motorista foi atribuído ao pedido (manualmente, pelo planeamento de rotas ou pela atribuição automática). data.source = auto_assign quando foi o orquestrador a fazê-lo.

O pedido perdeu o seu motorista (transferência, revogação, recusa, tempo esgotado). data.previous_driver_id indica quem o tinha.

O motorista aceitou na app um pedido atribuído automaticamente (turno de motoristas com aceitação obrigatória).

O motorista recusou um pedido atribuído; data.reason contém o motivo opcional em texto livre.

O motorista iniciou a recolha (estado Coleta iniciada / Saiu para coleta).

A encomenda foi recolhida (estado Já coletado).

A encomenda está a caminho do destinatário (estado Entrega iniciada / Saiu para entrega).

A entrega foi bem-sucedida (estado Bem-sucedido).

A tentativa de entrega falhou (Reentregar mais tarde, Precisa reagendar, Rejeitado pelo destinatário).

O pedido foi cancelado.

A equipa (ou um motorista, quando permitido) marcou o pedido como pronto para recolha (Opções de despacho → pronto para recolha).

Um motorista entrou ou saiu de turno na app (opção de turno de motoristas).

Uma posição do motorista vinda da app ou do rastreador, limitada por motorista através de driver_location_min_interval_sec (60 s por defeito). Enviada apenas para driver_location_webhook_url.

Uma encomenda foi colocada na máquina e aguarda a pessoa seguinte (destinatário, estafeta ou operador, ver data.device_order.next_actor). due_at é o prazo de levantamento.

A encomenda foi retirada pela pessoa que esperava — o destinatário, o estafeta ou o pessoal que esvazia uma caixa de depósito inteligente.

O pessoal retirou a encomenda da máquina. removal_reason indica o motivo: overdue_return, handover, relay, anomaly ou recovery.

A encomenda ultrapassou o seu due_at sem ser levantada. Continua na máquina e o código continua a funcionar; overdue_at é preenchido e next_actor passa a operator.

Foi aberto um problema sobre o tratamento (por exemplo door_left_open, deposit_unverified, item_missing, overdue). data.exception contém id, type, severity e status.

Uma pessoa fechou um problema sobre o tratamento. data.exception.status é resolved ou dismissed e resolution_action indica o que foi feito.