Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Pedidos fora da plataforma iFood

Use esta documentação para criar pedidos fora da plataforma iFood e contratar logística Sob Demanda simultaneamente. Ideal para integradoras e sistemas que criam seus próprios pedidos.

Como funciona

O fluxo consiste em 5 etapas principais:

Verificar disponibilidade - Valide cobertura e obtenha cotação
Registrar pedido - Crie o pedido e aloque entregador
Gerenciar endereço - Confirme ou altere endereço de entrega
Cancelar pedido - Cancele conforme necessário
Monitorar confiança - Rastreie o nível de segurança da entrega

1. Verificar disponibilidade

Antes de criar o pedido, verifique se a entrega está disponível para o endereço fornecido. Este endpoint retorna a cotação com preço e tempo estimado.

Endpoint

GET /shipping/v1.0/merchants/{merchantId}/deliveryAvailabilities?latitude={lat}&longitude={lng}

Parâmetros

Parâmetro	Localização	Tipo	Obrigatório	Descrição
`merchantId`	path	uuid	Sim	ID do merchant (sua loja)
`latitude`	query	float	Sim	Latitude do endereço de entrega (ex: -23.55)
`longitude`	query	float	Sim	Longitude do endereço de entrega (ex: -46.63)

Exemplo de requisição

curl -X GET "https://merchant-api.ifood.com.br/shipping/v1.0/merchants/{merchantId}/deliveryAvailabilities?latitude=-23.5505&longitude=-46.6333" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Resposta `200 OK`

A cotação foi obtida com sucesso. Use o id como quoteId ao criar o pedido. A cotação é válida por ~24 horas.

Campos da resposta

Campo	Tipo	Descrição
`id`	uuid	ID da cotação (use como `quoteId` ao criar pedido)
`expirationAt`	datetime	Validade da cotação em UTC (~24h). Solicitar após é inválido.
`createdAt`	datetime	Data de criação da cotação em UTC
`distance`	integer	Distância de entrega em metros
`preparationTime`	integer	Tempo de preparo sugerido em segundos
`quote.grossValue`	decimal	Valor bruto da entrega em reais
`quote.discount`	decimal	Desconto aplicado em reais
`quote.raise`	decimal	Acréscimo aplicado em reais
`quote.netValue`	decimal	Valor líquido = grossValue - discount + raise
`deliveryTime.min`	integer	Tempo mínimo estimado de entrega em segundos
`deliveryTime.max`	integer	Tempo máximo estimado de entrega em segundos
`hasPaymentMethods`	boolean	Indica se há métodos de pagamento disponíveis
`paymentMethods[].id`	uuid	ID único do método de pagamento
`paymentMethods[].brand`	string	Bandeira do cartão (ex: Visa, Mastercard)
`paymentMethods[].liability`	string	Responsável pelo pagamento (ex: IFOOD)
`paymentMethods[].paymentType`	string	Tipo de pagamento (ex: OFFLINE para pagamento na entrega)
`paymentMethods[].method`	string	Método: CREDIT, DEBIT ou CASH

Exemplo de resposta

{
  "id": "57cd1046-2e06-446f-a2dd-18a518212c3c",
  "expirationAt": "2023-08-18T19:49:06Z",
  "createdAt": "2023-08-17T19:49:06Z",
  "distance": 3000,
  "preparationTime": 60,
  "quote": {
    "grossValue": 7.99,
    "discount": 0,
    "raise": 0,
    "netValue": 7.99
  },
  "deliveryTime": {
    "min": 1200,
    "max": 1800
  },
  "hasPaymentMethods": true,
  "paymentMethods": [
    {
      "id": "21c65a8c-f29e-463f-b0bd-240edeb593c4",
      "brand": "Visa",
      "liability": "IFOOD",
      "paymentType": "OFFLINE",
      "method": "CREDIT"
    },
    {
      "id": "93c1c7c7-61f1-4dd9-bb84-62a03254701d",
      "liability": "IFOOD",
      "paymentType": "OFFLINE",
      "method": "CASH"
    }
  ]
}

Neste exemplo: distância de 3km, preço de R$ 7,99, tempo estimado de 20-30 minutos, e métodos de pagamento disponíveis (Visa e dinheiro).

Erros `400 Bad Request`

A entrega não está disponível. Verifique o código de erro para entender o motivo.

Para soluções detalhadas de cada erro, consulte Boas práticas e troubleshooting.

Códigos de erro

Código	Descrição	Ação
`BadRequest`	Problema na requisição	Verifique formato de `latitude` e `longitude`
`BadRequestMerchant`	Sua loja está indisponível	Verifique status da loja no painel
`DeliveryDistanceTooHigh`	Endereço a mais de ~10km	Confirme coordenadas com cliente
`OffOpeningHours`	Fora do horário de operação	Tente novamente no horário comercial
`OriginNotFound`	Loja não encontrada	Registre sua loja nas áreas iFood
`ServiceAreaMismatch`	Endereço fora da cobertura	Confirme se a região tem entrega iFood
`HighDemand`	Logística saturada	Tente novamente em minutos
`MerchantStatusAvailability`	Sua conta tem pendências	Contate o suporte
`InvalidPaymentMethods`	Forma de pagamento não suportada	Use outro método
`NRELimitExceeded`	Limite de entregadores atingido	Aguarde conclusão de entregas
`UnavailableFleet`	Frota indisponível	Tente novamente mais tarde

Erro `500 Internal Server Error`

Erro temporário no servidor. Tente novamente em alguns segundos.O que fazer: Implemente retry com backoff exponencial. Após 3-5 tentativas sem sucesso, registre em log e notifique o suporte.

2. Registrar pedido

Registre um novo pedido e aloque automaticamente um entregador iFood para pedidos criados fora da plataforma.

Comportamento importante

Entenda como o sistema funciona:

Um entregador é alocado automaticamente após o registro bem-sucedido
Se a entrega não for viável, o pedido não será criado
Valide todos os dados antes de enviar para evitar rejeições
O registro é uma operação assíncrona; use o id retornado para rastreamento

Segurança na entrega: Código de confirmação

Por segurança, um código de confirmação é gerado automaticamente. O entregador solicitará este código ao cliente para validar a identidade.

Dois modos disponíveis

Modo 1: Com código (padrão - recomendado)

Envie customer.phone.type="CUSTOMER" com número válido
O código será os 4 últimos dígitos do telefone
Entregador solicitará o código antes de entregar
Mais seguro; recomendado para entregas de alto valor

Modo 2: Sem código (apenas com autorização)

Envie customer.phone.type="STORE"
Código não será solicitado
Apenas validação de presença
Use quando cliente não pode fornecer validação

Informar o cliente

Informe previamente ao cliente que o entregador solicitará validação (código ou confirmação). Falha ou recusa pode resultar em cancelamento sem reembolso.

Para integradoras sem página de rastreio iFood

Se sua plataforma não usa a página de rastreio do iFood, implemente:

Escute o evento DELIVERY_DROP_CODE_REQUESTED
Extraia o código de metadata.CODE do evento
Exiba ao cliente via SMS, email ou app
Comunique ao entregador para solicitar validação

Fluxo: Monitorar eventos → Extrair código → Notificar cliente → Entregador valida

Endpoint

POST /shipping/v1.0/merchants/{merchantId}/orders

Exemplo de requisição

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/merchants/{merchantId}/orders" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "João Silva",
      "phone": {
        "countryCode": "55",
        "areaCode": "11",
        "number": "999999999",
        "type": "CUSTOMER"
      }
    },
    "delivery": {
      "merchantFee": 5.99,
      "quoteId": "57cd1046-2e06-446f-a2dd-18a518212c3c",
      "deliveryAddress": {
        "postalCode": "01310100",
        "streetNumber": "100",
        "streetName": "Avenida Paulista",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "coordinates": {
          "latitude": -23.5505,
          "longitude": -46.6333
        }
      }
    },
    "items": [{
      "id": "item-1",
      "name": "Hambúrguer",
      "quantity": 1,
      "unitPrice": 25.00,
      "price": 25.00,
      "optionsPrice": 0,
      "totalPrice": 25.00
    }],
    "payments": {
      "methods": [{
        "method": "CREDIT",
        "type": "OFFLINE",
        "value": 30.99,
        "card": {
          "brand": "Visa"
        }
      }]
    }
  }'

Resposta - `202 Accepted`

Pedido criado com sucesso. Um entregador está sendo alocado.

{
  "id": "522e4d7e-0ce1-44f3-8cc7-73a9f190a5e8",
  "trackingUrl": "https://meupedido.ifood.com.br/522e4d7e-0ce1-44f3-8cc7-73a9f190a5e8"
}

Campos retornados:

id (uuid) - ID único do pedido criado (use para futuras operações)
trackingUrl (string) - URL de rastreamento compartilhável com cliente

Próximas ações:

Compartilhe a trackingUrl com o cliente para acompanhar entrega
Monitore eventos de entrega via polling com o id retornado
Implemente listeners para eventos como DELIVERY_DROP_CODE_REQUESTED, DELIVERY_IN_TRANSIT, DELIVERY_CONCLUDED

Campos do pedido

Campos obrigatórios marcados com *

Customer (Cliente)

Campo	Tipo	Descrição
`customer.name`*	string	Nome (máx. 50 caracteres)
`customer.phone.type`	string	CUSTOMER (padrão) ou STORE
`customer.phone.countryCode`*	string	Código do país (2 dígitos). Ex: 55
`customer.phone.areaCode`*	string	DDD (2 dígitos). Ex: 11
`customer.phone.number`*	string	Telefone (7-9 dígitos)

* Não obrigatório se customer.phone.type="STORE"

Delivery (Entrega)

Campo	Tipo	Descrição
`delivery.merchantFee`*	float	Taxa do parceiro
`delivery.preparationTime`	integer	Tempo de preparo (segundos)
`delivery.quoteId`	uuid	ID da cotação
`delivery.deliveryAddress.postalCode`*	string	CEP (8 dígitos)
`delivery.deliveryAddress.streetNumber`*	string	Número
`delivery.deliveryAddress.streetName`*	string	Logradouro (máx. 50 caracteres)
`delivery.deliveryAddress.complement`	string	Complemento (máx. 50 caracteres)
`delivery.deliveryAddress.reference`	string	Referência (máx. 70 caracteres)
`delivery.deliveryAddress.neighborhood`*	string	Bairro (máx. 50 caracteres)
`delivery.deliveryAddress.city`*	string	Cidade (2-50 caracteres)
`delivery.deliveryAddress.state`*	string	UF (2 letras). Ex: SP
`delivery.deliveryAddress.country`*	string	País (2 letras). Ex: BR
`delivery.deliveryAddress.coordinates.latitude`*	float	Latitude
`delivery.deliveryAddress.coordinates.longitude`*	float	Longitude

Items (Itens)

Campo	Tipo	Descrição
`items[].id`*	uuid	ID do item
`items[].name`*	string	Nome (máx. 50 caracteres)
`items[].externalCode`	string	Código externo
`items[].quantity`*	integer	Quantidade (> 0)
`items[].unitPrice`*	float	Preço unitário (≥ 0)
`items[].price`*	float	Preço total (quantity * unitPrice)
`items[].optionsPrice`*	float	Preço dos complementos (≥ 0)
`items[].totalPrice`*	float	Total (price + optionsPrice)

Payments (Pagamentos)

Pagamento Offline:

Campo	Tipo	Descrição
`payments.methods[].method`*	string	CREDIT, DEBIT ou CASH
`payments.methods[].type`*	string	OFFLINE
`payments.methods[].value`*	float	Valor
`payments.methods[].card.brand`*	string	Bandeira (se CREDIT/DEBIT)
`payments.methods[].cash.changeFor`*	float	Troco (se CASH)

Pagamento Online: Não enviar o objeto payments (processado pelo merchant)

Outros campos

Campo	Tipo	Descrição
`displayId`	string	ID amigável (máx. 4 caracteres). Ex: A4BC
`metadata`	object	Informações adicionais (máx. 20 caracteres)

Tempo de preparação

O parâmetro delivery.preparationTime (em segundos) controla quando o entregador será alocado. Isso é crítico para a experiência do cliente.

Por que o tempo de preparação importa

Um timing incorreto resulta em problemas operacionais sérios:

Cenário	Problema	Impacto
Muito curto	Entregador chega antes do pedido pronto	Cliente espera, entregador ocioso
Muito longo	Entregador aguarda sem propósito	Inchaço na fila, alocação ineficiente
Correto	Entregador e pedido prontos simultaneamente	Operação ótima, cliente satisfeito

Como usar

Opção 1: Alocação imediata (padrão)

{
  "delivery": {
    // Não enviar preparationTime ou enviar 0
  }
}

→ Entregador alocado imediatamenteOpção 2: Alocação retardada (recomendado)

{
  "delivery": {
    "preparationTime": 900  // 15 minutos em segundos
  }
}

→ Entregador alocado após 15 minutos

Melhores práticas

Use dados reais: Base o preparationTime no tempo médio de preparo do seu negócio
Consulte a cotação: O endpoint de disponibilidade retorna preparationTime sugerido - use como referência
Ajuste iterativamente: Monitore se entregadores chegam cedo/tarde e ajuste
Adicione margem: Considere picos - é melhor entregar um pouco atrasado do que perder pedidos

Exemplo prático

Dados do seu negócio:
- Tempo médio de preparo: 12 minutos
- Variação típica: ±2 minutos
- Margem de segurança: +3 minutos

Recomendação:
preparationTime = (12 + 3) * 60 = 900 segundos (15 minutos)

Integração com polling de eventos

Após criar o pedido com sucesso, implemente monitoramento de eventos:

Fonte: Polling de eventos
Filtro: Pedidos com salesChannel="POS" (use o id retornado)
Eventos críticos:
- DELIVERY_DROP_CODE_REQUESTED - Código de confirmação necessário
- DELIVERY_IN_TRANSIT - Entregador saiu para entregar
- DELIVERY_CONCLUDED - Entrega concluída
- DELIVERY_CANCELLED - Entrega cancelada
Rastreamento: Use o id do pedido em endpoint de tracking para obter localização

Erros `400 Bad Request`

Requisição inválida ou serviço indisponível.

Para soluções detalhadas de cada erro, consulte Boas práticas e troubleshooting.

Código	Descrição	Ação Recomendada
BadRequest	Dados inválidos na requisição	Verifique todos os campos obrigatórios (marcados com *)
BadRequestCustomer	Cliente indisponível ou inválido	Verifique nome, telefone do cliente
BadRequestMerchant	Sua loja está indisponível	Verifique status da loja no painel
DeliveryDistanceTooHigh	Endereço fora da cobertura	Confirme coordenadas com cliente
HighDemand	Logística saturada neste momento	Tente novamente em alguns minutos
MerchantEasyDeliveryDisabled	Serviço não habilitado para sua loja	Ative o serviço no painel iFood
OffOpeningHours	Fora do horário de operação	Aguarde o horário comercial
OriginNotFound	Loja não localizada na área logística	Registre sua loja nas áreas iFood
PaymentMethodNotFound	Método de pagamento não suportado	Use método disponível (CREDIT, DEBIT ou CASH)
PaymentTotalInvalid	Valor de pagamento ≠ total do pedido	Verifique soma dos itens + entrega
ServiceAreaMismatch	Endereço fora da área de serviço	Confirme cobertura iFood na região
NRELimitExceeded	Limite de entregadores simultâneos	Aguarde conclusão de entregas em andamento

Erro `500 Internal Server Error`

Erro temporário no servidor. Tente novamente em alguns segundos.O que fazer: Implemente retry com backoff exponencial. Após 3-5 tentativas sem sucesso, registre em log e notifique o suporte.

3. Confirmação/alteração de endereço

Gerencie mudanças de endereço após o pedido ser criado. O cliente pode confirmar o endereço ou solicitar uma alteração.

Dois fluxos disponíveis

Opção A: Com página de rastreio iFood (recomendado)

Cliente usa a página do iFood (trackingUrl) para confirmar/alterar endereço de forma segura.Requisitos:

Pedido NÃO pode ter customer.phone.type="STORE"
Telefone válido é obrigatório (recebe OTP por SMS)
Use URL retornada na criação do pedido

Fluxo: Cliente acessa URL → Recebe OTP via SMS → Valida endereço → ConfirmaVantagem: iFood gerencia segurança, OTP, validação

Opção B: Sem página de rastreio iFood (integração custom)

Sua plataforma implementa própria interface de confirmação/alteração usando os endpoints.Requisitos:

Você gerencia a interface do usuário
Responsabilidade sua validar e implementar segurança

Fluxo: Cliente confirma na sua app → Você chama endpoints → Monitora eventosNota: iFood não envia OTP. Você escolhe como validar (senha, OTP próprio, etc).

Segurança: Se usar OTP, implemente validação adequada. Endereços incorretos resultam em falhas de entrega.

3.1 Confirmar endereço original

Usado quando cliente confirma que o endereço fornecido está correto (sem mudanças).

POST /shipping/v1.0/orders/{orderId}/userConfirmAddress

Exemplo de requisição

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/userConfirmAddress" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Resposta - `202 Accepted`

Confirmação registrada com sucesso.Evento gerado: DELIVERY_ADDRESS_CHANGE_USER_CONFIRMEDMonitore este evento para ser informado quando cliente confirmar.

3.2 Solicitar alteração de endereço

Cliente pode solicitar mudança do endereço de entrega após criação do pedido (máximo 500m da coordenada original).

POST /shipping/v1.0/orders/{orderId}/deliveryAddressChangeRequest

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`streetNumber`	string	Não	Número (ex: 200)
`streetName`	string	Sim	Logradouro (ex: Rua das Flores)
`complement`	string	Não	Complemento (ex: Apto 42)
`neighborhood`	string	Sim	Bairro (ex: Centro)
`city`	string	Sim	Cidade (ex: São Paulo)
`state`	string	Sim	Estado (ex: SP, 2 letras)
`country`	string	Sim	País (ex: BR, 2 letras)
`reference`	string	Não	Referência (ex: Perto da estação)
`coordinates.latitude`	float	Sim	Latitude do novo endereço
`coordinates.longitude`	float	Sim	Longitude do novo endereço

Exemplo de requisição

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/deliveryAddressChangeRequest" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "streetNumber": "200",
    "streetName": "Rua das Flores",
    "complement": "Apto 42",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "reference": "Perto da estação",
    "coordinates": {
      "latitude": -23.5510,
      "longitude": -46.6340
    }
  }'

Resposta - `202 Accepted`

Solicitação de alteração registrada. Seu sistema deve responder em até 15 minutos.Evento gerado: DELIVERY_ADDRESS_CHANGE_REQUESTEDMonitore este evento para ser notificado da solicitação e oferecer opções ao cliente.

Restrições importantes

Restrição	Limite	Consequência
Distância máxima	500m da coordenada original	Alterações maiores são rejeitadas
Prazo para resposta	15 minutos	Após isso, rejeição automática
Mudança de região	Não permitido	Gera evento automático de negação

3.3 Aceitar alteração de endereço

Seu sistema aprova a mudança de endereço solicitada pelo cliente.

POST /shipping/v1.0/orders/{orderId}/acceptDeliveryAddressChange

Exemplo de requisição

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/acceptDeliveryAddressChange" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Resposta `200 OK`

Alteração aceita com sucesso.Evento gerado: DELIVERY_ADDRESS_CHANGE_ACCEPTEDNota especial: Se o novo endereço cair em outra região, iFood automaticamente nega com evento DELIVERY_ADDRESS_CHANGE_DENIED e metadata.action="region-mismatch".

3.4 Rejeitar alteração de endereço

Seu sistema rejeita a mudança de endereço solicitada (quando não viável, por exemplo).

POST /shipping/v1.0/orders/{orderId}/denyDeliveryAddressChange

Exemplo de requisição

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/denyDeliveryAddressChange" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Resposta - `202 Accepted`

Rejeição registrada com sucesso.Evento gerado: DELIVERY_ADDRESS_CHANGE_DENIED

Erros comuns em alteração de endereço

Código	Status	Descrição	Ação
BadRequest	400	Parâmetros inválidos	Verifique coordenadas, nome da rua, cidade
OrderNotFound	404	Pedido não encontrado ou expirado (>8h)	Pedido é válido por até 8 horas
ChangeAddressOperationConflict	409	Operação em conflito	Já existe outra alteração pendente
ChangeAddressOperationNotStarted	409	Nenhuma alteração pendente	Não há solicitação para aceitar/rejeitar
MaxDistanceHigherThanAllowed	400	Alteração > 500m da coordenada original	Solicitação fora do limite permitido
RegionMismatch	400	Novo endereço em região diferente	Endereço em cobertura iFood diferente

4. Cancelamento

Cancele pedidos criados fora da plataforma (salesChannel="POS"). O processo é em duas etapas: obter motivos válidos e enviar cancelamento.

4.1 Obter códigos de cancelamento disponíveis

Antes de cancelar, consulte os motivos válidos. Você não pode hardcoding motivos.

GET /shipping/v1.0/orders/{orderId}/cancellationReasons

Exemplo de requisição

curl -X GET "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/cancellationReasons" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Resposta `200 OK`

Lista de motivos válidos para this pedido específico.

[
  {
    "cancelCodeId": "817",
    "description": "O cliente cancelou o pedido"
  },
  {
    "cancelCodeId": "818",
    "description": "Impossível preparar o pedido"
  }
]

Campos:

cancelCodeId (string) - Código único do motivo (use no cancelamento)
description (string) - Descrição legível para exibir ao operador

Resposta - 204 No Content

Pedido não pode mais ser cancelado (já entregue, cancelado, etc). Nenhuma ação necessária.

4.2 Cancelar o pedido

Após obter os motivos válidos, envie o cancelamento com o código e razão.

POST /shipping/v1.0/orders/{orderId}/cancel

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`reason`	string	Sim	Texto explicativo do cancelamento (para logs)
`cancellationCode`	integer	Sim	Código obtido em 4.1 (ex: 817)

Exemplo de requisição

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/cancel" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Cliente solicitou cancelamento via chat",
    "cancellationCode": 817
  }'

Body:

{
  "reason": "Cliente solicitou cancelamento via chat",
  "cancellationCode": 817
}

Resposta - `202 Accepted`

Cancelamento registrado. Monitore eventos para confirmação.Sequência de eventos:

CANCELLATION_REQUESTED - Cancelamento solicitado
CANCELLED - Cancelamento confirmado com sucesso
CANCELLATION_REQUEST_FAILED - Falha no cancelamento (ex: entregador já saiu)

Monitore via polling para saber o resultado final.

5. Nível de confiança na entrega (Safe Delivery Score)

Sistema de scoring automático que calcula o nível de confiança de cada entrega baseado em fatores de validação do cliente e endereço.Use o score para: Tomar decisões operacionais (ex: pedir confirmação adicional para LOW, priorizar HIGH/VERY_HIGH).

Níveis de confiança

Nível	Descrição	Quando ocorre	Recomendação
LOW	Confiança baixa	Cliente inválido ou alteração negada	Solicitar confirmação extra do cliente
MODERATE	Confiança moderada	Telefone fixo (validação mais fraca)	Monitorar atentamente
HIGH	Confiança alta	Telefone móvel válido	Processamento padrão
VERY_HIGH	Confiança muito alta	Telefone válido + endereço confirmado	Priorizar, menos risco

Regras de cálculo

O score é calculado combinando os seguintes fatores:

Regra	Descrição	Impacto
customer_phone_valid	Telefone móvel válido (11+ dígitos, tipo CUSTOMER)	Aumenta confiança
customer_phone_is_fixed	Telefone fixo (8 dígitos)	Confiança intermediária
customer_address_confirmed	Cliente confirmou o endereço	Aumenta muito
customer_address_change_requested	Cliente solicitou mudança de endereço	Reduz (pode indicar erro inicial)
merchant_address_change_approved	Você aprovou a mudança	Melhora o score
merchant_address_change_denied	Você rejeitou a mudança	Reduz significativamente

Exemplos de scoring

Cenário 1: Sem validação
`customer_phone_valid`=false
→ Score: LOW (alto risco)

Cenário 2: Telefone fixo apenas
`customer_phone_is_fixed`=true
→ Score: MODERATE

Cenário 3: Telefone móvel válido
`customer_phone_valid`=true
→ Score: HIGH

Cenário 4: Telefone + Endereço confirmado
`customer_phone_valid`=true +
`customer_address_confirmed`=true
→ Score: VERY_HIGH (máxima confiança)

Cenário 5: Alteração aprovada
`customer_phone_valid`=true +
`merchant_address_change_approved`=true
→ Score: VERY_HIGH

Cenário 6: Alteração rejeitada
`customer_phone_valid`=true +
`customer_address_change_requested`=true +
`merchant_address_change_denied`=true
→ Score: LOW (desconfiança)

Consultar nível de confiança

GET /shipping/v1.0/orders/{orderId}/safeDelivery

Exemplo de requisição

curl -X GET "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/safeDelivery" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Resposta `200 OK`

Score calculado com detalhes das regras avaliadas.

{
  "rules": {
    "customer_address_change_requested": false,
    "customer_address_confirmed": true,
    "customer_phone_is_fixed": false,
    "customer_phone_valid": true,
    "merchant_address_change_approved": false,
    "merchant_address_change_denied": false
  },
  "score": "VERY_HIGH"
}

Interpretação:

Cliente tem telefone móvel válido ✓
Cliente confirmou o endereço ✓
Nenhuma alteração pendente ✓
Score = VERY_HIGH (máxima confiança)

Campos:

score (enum) - Nível: LOW, MODERATE, HIGH, VERY_HIGH
rules.* (boolean) - Cada regra verdadeira ou falsa

Resposta - 400 OrderWithoutSafeDelivery

Pedido não tem regras de confiança aplicáveis (criado antes do sistema).

Resposta - 404 OrderNotFound

Pedido não existe ou expirou (máximo 8 horas).

Dinâmica do score

O score não é estático - muda conforme as ações ocorrem:

Quando o score muda

Evento	Impacto	Novo Score
Cliente confirma endereço	Aumenta confiança	Pode subir para VERY_HIGH
Cliente solicita alteração	Reduz (erro inicial?)	Pode cair para MODERATE/LOW
Você aprova alteração	Aumenta confiança	Pode voltar para VERY_HIGH
Você rejeita alteração	Reduz muito	Cai para LOW
Tempo passa	Alguns dados expiram	Score pode cair ao longo do tempo

Melhor prática

Consulte o score próximo ao horário de entrega (não apenas na criação):

1. Pedido criado → Score HIGH
   ↓ (Cliente confirma endereço)
2. Antes de entregar → Score VERY_HIGH
   ↓ (Use para decisões críticas)
3. Aloque recursos ou aplique validações extras se LOW

Exemplo de uso operacional: