Pular para o conteúdo principal

Serviços de Criação de Delivery Jobs

Esta página explica como criar delivery jobs com a Fleet API e como confirmar se os jobs enviados foram efetivamente criados.

Acrónimos e Termos​

  • API: Application Programming Interface.
  • ERP: Enterprise Resource Planning.
  • HTTP: Hypertext Transfer Protocol.

Que Endpoint Devo Utilizar?​

Use este mapeamento de acordo com o volume de criação e o tipo de confirmação necessário:

1) Bulk Upload Delivery Jobs​

O que significa​

Permite enviar múltiplos jobs num único pedido, ideal quando é necessário integrar grandes volumes a partir de ERP ou sistemas de despacho.

Confirmação e notificações​

O serviço de bulk upload suporta o campo webhooks_url. Após o processamento, a Cartrack envia um callback de webhook para que o seu sistema confirme o resultado e reconcilie o que foi criado. Para configuração de webhook, validação de assinatura e orientações de segurança, consulte Webhooks.

Objetivo​

  • Melhor opção para importações de entregas agendadas ou de grande volume.
  • Fornece às equipas operacionais um fluxo de confirmação fiável, em vez de assumir que todos os jobs foram criados.
  • Ajuda a identificar rapidamente cenários de criação parcial.

Considerações para Programadores​

  • Trate este pedido como um fluxo assíncrono.
  • Use os callbacks de webhook como fonte de verdade para o estado final de processamento.
  • Compare os jobs submetidos com os resultados recebidos e aplique retry/escalation para jobs não criados.

2) Create a Delivery Job​

O que significa​

Permite criar um delivery job por pedido com feedback imediato da API.

Confirmação e erros​

Se o job não puder ser criado, a API devolve um código HTTP diferente de 200, acompanhado por uma mensagem de erro apropriada.

Objetivo​

  • Mais adequado para fluxos interativos onde o utilizador cria jobs individualmente.
  • Falhas ficam visíveis de imediato e podem ser apresentadas às equipas de suporte ou despacho.

Considerações para Programadores​

  • Valide o HTTP status de cada pedido.
  • Trate todas as respostas não 200 como falhas explícitas de criação.
  • Registe e devolva a mensagem de erro da API para acelerar a resolução operacional.

Padrão de Integração Recomendado​

  1. Mantenha uma referência do lado cliente para cada job submetido (ERP/dispatch).
  2. Use bulk upload com webhooks_url para importações em alto volume.
  3. Acompanhe os callbacks e reconcilie jobs esperados vs jobs criados.
  4. Trate todas as respostas não 200 de criação unitária como falhas.
  5. Faça retry ou escalone jobs falhados conforme o seu fluxo interno.