Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Critérios de homologação

Antes de solicitar homologação, certifique-se de que sua integração atende todos os critérios funcionais e não-funcionais descritos nesta página.

Pré-requisitos

Sua aplicação deve estar completamente desenvolvida e testada antes da submissão
A avaliação abrange toda a aplicação, não apenas chamadas de API
Apenas contas Profissionais (CNPJ) são aceitas
Contas Pessoais ou Estudante (CPF) serão rejeitadas

Quem deve usar esta documentação

Integradoras exclusivas do módulo Shipping:Use este documento para validar sua implementação antes de solicitar homologação.Integradoras com múltiplos módulos:Se sua integração utiliza também o módulo Orders, consulte os critérios de homologação de Orders em adição aos critérios abaixo.Integradoras já homologadas:Recomendamos validar sua integração contra estes critérios para garantir conformidade contínua e identificar oportunidades de melhoria.

Requisitos funcionais

Sua integração deve implementar os seguintes recursos para ser homologada.

Gestão de eventos

Implemente um sistema robusto de consumo de eventos do iFood:

Requisito	Detalhes
Polling de eventos	Consultar o endpoint /polling a cada 30 segundos. Intervalos menores podem resultar em rate limiting; intervalos maiores podem causar perda de eventos.
Reconhecimento	Enviar /acknowledgment imediatamente após processar cada evento. Não reconhecer eventos pode causar reprocessamento.
Deduplicação	Implementar lógica para identificar e descartar eventos duplicados recebidos durante polling. Use o `eventId` como identificador único.

O sistema de eventos é o principal canal de comunicação entre plataformas. Falhas nessa integração resultam em pedidos inconsistentes.

Gestão de pedidos Sob Demanda

Sua integração deve processar pedidos Sob Demanda imediatos com os seguintes parâmetros:

orderType=DELIVERY
orderTiming=IMMEDIATE
salesChannel=POS

Confirmação de pedidos

Receber solicitações de confirmação para pedidos delivery imediatos
Confirmar dentro do sistema da integradora
Validar dados de entrega antes de confirmar

Cancelamento de pedidos

Você deve implementar as seguintes etapas:

Consumir motivos de cancelamento via /cancellationReasons
Exibir lista dinâmica de motivos no sistema do PDV
Permitir seleção do usuário antes de processar cancelamento
Enviar motivo selecionado na requisição de cancelamento

Não faça hardcoding de motivos de cancelamento. Consuma dinamicamente os códigos retornados pela API.

Sincronização de status

Sua integração deve reagir aos seguintes eventos de mudança de status:

Pedidos cancelados pelo cliente (usuário iFood app)
Pedidos cancelados pelo iFood (restrições operacionais)
Pedidos confirmados/cancelados por terceiros (ex: Gestor de Pedidos, Dashboard iFood)

Atualize o status da integradora para manter consistência com a plataforma.

Gestão de endereços

Implemente a capacidade de:

Aceitar solicitações de alteração de endereço (quando viável)
Rejeitar solicitações (quando não puder atender)
Respeitar prazos definidos pelo iFood para resposta

A mudança de endereço é crítica. Responda rapidamente.

Código de coleta

Implemente validação do código de coleta em duas etapas:

Verificar presença do pickupCode no pedido
Validar confirmação do entregador antes de marcar como retirado

O código de coleta é essencial para a segurança da entrega.

Requisitos não funcionais

Esses requisitos garantem que sua integração seja confiável, segura e operacional em produção.

Autenticação e segurança

Renovação de tokens:

Renove tokens antes do vencimento (recomendado: 5 minutos antes)
Implemente refresh automático
Evite renovações desnecessárias

Rate limiting:

Respeite os limites de requisições em cada endpoint
Implemente fila de requisições para picos
Monitore 429 Too Many Requests e aplique backoff

Confiabilidade

Tratamento de erros:

Implemente retry com backoff exponencial para falhas transientes
Use multiplicador de 2x com jitter (ex: 1s, 2s, 4s, 8s)
Máximo de 3-5 tentativas
Registre todas as tentativas em logs

Idempotência:

Usar idempotency-key em operações que alteram estado (cancelamentos, confirmações)
Implementar deduplicação no lado cliente

Observabilidade e monitoramento

Logging:

Registre em log todas as operações críticas
Inclua orderId, eventId, timestamp e status
Mantenha logs por mínimo 30 dias

Alertas:

Configure alertas para:
- Falhas consecutivas de polling (> 5)
- Atraso anormal de endpoints (> 30s)
- Taxa de erro acima do threshold (> 5%)
- Falta de renovação de token

Monitoramento:

Rastreie taxa de sucesso de operações críticas
Monitore latência de end-to-end
Meça tempo de resposta do polling

Requisitos recomendados

Esses recursos melhoram a experiência do usuário e não são obrigatórios:

Impressão de comanda

Imprima todas as informações do pedido seguindo o modelo em layout de comanda:

Identificador do pedido (order ID)
Dados de entrega (endereço, contato)
Itens do pedido e quantidades
Horário de entrega
Observações especiais

Reduz erros operacionais e melhora comunicação com entregadores.

Observações de entrega

Exiba e processe o campo delivery.observations em dois pontos:

Tela do sistema: Mostrar em destaque ao receber o pedido
Comanda impressa: Incluir como seção separada

Instruções de acesso, restrições de horário, contato para problemas. Garante que instruções críticas chegam ao entregador.

Processo de homologação

Etapa 1: Preparação

Valide:

Aplicação completamente desenvolvida
Conta Profissional (CNPJ)
Ambiente de testes configurado com credenciais válidas
Base de código em controle de versão

Etapa 2: Validação interna

Execute a bateria completa de testes:

Eventos: Polling a cada 30s e acknowledgment correto
Pedidos: Confirmação, cancelamento e sincronização
Endereços: Aceitação/rejeição de mudanças
Códigos de coleta: Validação com confirmação do entregador
Erros: Retry com backoff; logging completo
Cenários extremos: Duplicatas, timeouts, rate limiting

Etapa 3: Submissão

Prepare a documentação para submissão:

Descreva sua solução e como atende cada critério
Forneça exemplos de logs de operações críticas
Compartilhe métricas de confiabilidade
Indique qualquer desvio com justificativa

Etapa 4: Revisão e feedback

O time de homologação irá:

Revisar código e arquitetura
Executar testes de integração
Fornecer feedback em até 5 dias úteis
Solicitar correções ou melhorias

Etapa 5: Aprovação

Após a aprovação, você receberá:

Confirmação formal de homologação
Credenciais de produção
Documentação de go-live

Próximos passos

Para começar:

Após aprovação:

Migre credenciais de teste para produção
Configure monitoramento em produção
Teste roll-out com pequeno volume antes de escalar

Esta página foi útil?

Avalie sua experiência no novo Developer portal: