Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Como funciona

Entenda a arquitetura e os fluxos de operação do módulo Shipping antes de integrar os endpoints.

Fluxo geral de entrega

Independente do tipo de pedido, todas as entregas passam por estas etapas:

1. Verificar disponibilidade

Antes de qualquer operação, consulte se a entrega é viável. Valide:

Cobertura geográfica: O endereço está na área de serviço
Disponibilidade de frota: Há entregadores disponíveis
Horário: A operação está em funcionamento
Custo: Obtenha a cotação e prazos

Os endpoints retornam um quoteId válido por ~24 horas.

2. Solicitar ou criar entrega

Com a cotação validada, aloque um entregador:

Pedidos iFood: Use apenas o orderId
Pedidos externos: Crie o pedido e aloque simultaneamente

A alocação ocorre em background. Use o quoteId como referência.

3. Acompanhar em tempo real

Após a alocação, você pode:

Rastrear localização: Latitude/longitude do entregador
Monitorar eventos: Status de coleta, em trânsito, entregue
Gerenciar mudanças: Alterações de endereço, cancelamentos

4. Confirmar entrega

O ciclo termina quando:

Entregador marca como entregue
Sistema iFood valida a conclusão
Você recebe o evento DELIVERY_CONCLUDED

Diferenças entre os dois fluxos

Fluxo A: Pedidos feitos na plataforma iFood

Use este fluxo quando você tem um pedido iFood já criado com orderId e precisa apenas adicionar logística iFood.

Características:

Operação simples: apenas 2 endpoints principais
Entrada mínima: apenas orderId
Resposta imediata: 202 Accepted
Sem gerenciar dados de cliente ou endereço

Melhor para: Backup rápido, picos de demanda, integração simples

Fluxo B: Pedidos feitos fora da plataforma iFood

Use este fluxo para criar um novo pedido e contratar logística iFood simultaneamente.

Características:

Operação completa: criação + logística em uma única requisição
Entrada complexa: cliente, endereço, itens, pagamento
Processamento em background
Suporta gerenciamento de endereço e cancelamento
Inclui segurança: código de confirmação e safe delivery score

Melhor para: Sob Demanda, integradores, marketplace, vendas multi-canal

Conceitos importantes

Cotação (Quote)

Uma cotação é válida por ~24 horas e contém:

id (quoteId): Identificador para usar na próxima etapa
quote.netValue: Preço final da entrega
deliveryTime.min/max: Tempo estimado em segundos
distance: Distância em metros
expirationAt: Até quando a cotação é válida

Sempre use a cotação mais recente obtida. Cotações antigas serão rejeitadas.

Operações assíncronas

A alocação de entregador é assíncrona. Isso significa:

A API retorna 202 Accepted imediatamente
O processamento ocorre em background
Você descobre o resultado através de eventos
Implemente polling para monitorar o status

Não assuma sucesso apenas pela resposta 202 Accepted.

Eventos de entrega

O sistema notifica você através de eventos:

Evento	Significado
`REQUEST_DRIVER`	Requisição registrada (apenas log)
`REQUEST_DRIVER_SUCCESS`	Entregador alocado com sucesso
`REQUEST_DRIVER_FAILED`	Falha na alocação
`DELIVERY_IN_TRANSIT`	Entregador saiu para entregar
`DELIVERY_CONCLUDED`	Entrega completada
`DELIVERY_CANCELLED`	Entrega cancelada

Implemente polling a cada 30 segundos para monitorar esses eventos de entrega.

Rastreamento (Tracking)

O rastreamento fica disponível apenas após ASSIGN_DRIVER ou REQUEST_DRIVER_SUCCESS. Os campos incluem:

latitude e longitude: Coordenadas atuais
expectedDelivery: Previsão de entrega
deliveryEtaEnd: Segundos até entrega
trackDate: Timestamp da consulta

Os campos podem retornar null enquanto o entregador está sendo atribuído.

Código de confirmação (apenas Sob Demanda)

Para pedidos criados fora da plataforma:

Código gerado automaticamente (últimos 4 dígitos do telefone)
O entregador solicita ao cliente antes de entregar
Aumenta a segurança contra fraude
Monitore o evento DELIVERY_DROP_CODE_REQUESTED

Nível de confiança (Safe Delivery Score)

O sistema avalia automaticamente o risco de cada entrega:

Nível	Descrição
`LOW`	Solicite validação extra
`MODERATE`	Monitore durante o processo
`HIGH`	Processamento padrão
`VERY_HIGH`	Priorize

O score muda conforme as ações ocorrem, como confirmação de endereço ou alterações.

Fluxo de decisão

Antes de começar, responda:

Tenho um orderId do iFood?
- Sim → Use Fluxo A (Pedidos feitos na plataforma)
- Não → Use Fluxo B (Pedidos feitos fora da plataforma)
Preciso gerenciar alterações de endereço?
- Sim → Use Fluxo B
- Não → Use Fluxo A ou B
Preciso de código de confirmação?
- Sim → Use Fluxo B
- Não → Use Fluxo A
Preciso sincronizar múltiplos canais de venda?
- Sim → Use Fluxo B
- Não → Use Fluxo A