Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Shipping

Pedidos fora da plataforma iFood

Esta seção explica como integrar pedidos realizados fora da plataforma iFood (não possuem orderId pré-existente) ao serviço de entrega Sob Demanda.

Fluxo de integração

1. Verificar disponibilidade

Antes de registrar o pedido, consulte a disponibilidade de entrega para validar a cobertura e obter estimativas.

Por que verificar?

Validar área de cobertura
Identificar indisponibilidade temporária
Obter estimativa de tempo e custo
Evitar erros no registro

Embora opcional, esta verificação previne erros e permite melhor planejamento operacional.

Endpoint

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

Parâmetros obrigatórios:

merchantId (path) - ID do merchant
latitude (query) - Latitude do endereço de entrega
longitude (query) - Longitude do endereço de entrega

Resposta de sucesso - 200 OK

Campos da resposta

Campo	Tipo	Descrição
id	uuid	ID da cotação
expirationAt	datetime	Validade da cotação (UTC)
createdAt	datetime	Data de criação (UTC)
distance	integer	Distância em metros
preparationTime	integer	Tempo de preparo em segundos
quote.grossValue	decimal	Valor bruto
quote.discount	decimal	Desconto
quote.raise	decimal	Acréscimo
quote.netValue	decimal	Valor líquido
deliveryTime.min	integer	Tempo mínimo de entrega (segundos)
deliveryTime.max	integer	Tempo máximo de entrega (segundos)
hasPaymentMethods	boolean	Indica métodos de pagamento disponíveis
paymentMethods[].method	string	CREDIT, DEBIT ou CASH

Exemplo

{
  "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"
    }
  ]
}

Erros - 400 Bad Request

Códigos de erro

Código	Descrição
BadRequest	Problema na requisição. Verifique os dados
BadRequestMerchant	Merchant indisponível
DeliveryDistanceTooHigh	Endereço fora da área de cobertura
OffOpeningHours	Fora do horário de funcionamento
OriginNotFound	Loja fora da área logística
ServiceAreaMismatch	Endereço fora da área de cobertura
HighDemand	Logística temporariamente indisponível
MerchantStatusAvailability	Merchant com pendência
InvalidPaymentMethods	Forma de pagamento não aceita
NRELimitExceeded	Limite de entregadores atingido
UnavailableFleet	Frota indisponível

2. Registrar pedido

Registre o pedido para solicitar automaticamente um entregador parceiro.

Um entregador será alocado automaticamente após o registro
Se a entrega não for possível, o pedido não será registrado
Certifique-se de validar os dados antes de enviar

Código de confirmação de entrega

Por segurança, um código de confirmação (4 últimos dígitos do telefone) é gerado automaticamente.

Como funciona

Com código (padrão):

Envie customer.phone.type="CUSTOMER" com telefone válido
O entregador solicitará o código na entrega
Cliente deve ser informado previamente

Sem código:

Envie customer.phone.type="STORE"
Código não será solicitado

Informe o cliente que o entregador solicitará os 4 últimos dígitos do telefone. Falha na validação pode resultar em cancelamento.

Para parceiros sem página de rastreio iFood

Consuma o evento DELIVERY_DROP_CODE_REQUESTED com metadata.CODE para disponibilizar o código ao cliente.

Endpoint

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

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 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 preparo

Use delivery.preparationTime para atrasar a alocação do entregador.

Não enviado: Alocação imediata
Enviado: Alocação após o tempo especificado (em segundos)

Informe o tempo mais preciso possível. Tempos incorretos podem resultar em:

Atrasos na entrega
Experiência ruim para o cliente
Possível fechamento por acúmulo de entregadores

Resposta de sucesso - 202 Accepted

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

Integração com polling

Pedidos ficam disponíveis no polling de eventos
Identificados por salesChannel="POS"
Rastreamento disponível via endpoint de tracking

Erros - 400 Bad Request

Código	Descrição
BadRequest	Problema na requisição
BadRequestCustomer	Cliente indisponível
BadRequestMerchant	Merchant indisponível
DeliveryDistanceTooHigh	Fora da área de cobertura
HighDemand	Logística indisponível temporariamente
MerchantEasyDeliveryDisabled	Serviço não habilitado
OffOpeningHours	Fora do horário de funcionamento
OriginNotFound	Loja fora da área logística
PaymentMethodNotFound	Método de pagamento não encontrado
PaymentTotalInvalid	Valor do pagamento não corresponde ao total
ServiceAreaMismatch	Endereço fora da cobertura
NRELimitExceeded	Limite de entregadores atingido

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

Permite que o cliente confirme ou solicite alteração do endereço de entrega após a criação do pedido.

Fluxos disponíveis

Com página de rastreio iFood

Cliente usa a página do iFood para confirmar/alterar endereço.Requisitos:

Pedido NÃO pode ter customer.phone.type="STORE"
Telefone válido é obrigatório para OTP

Envie o telefone correto usado como WhatsApp para receber o código OTP de confirmação.

Sem página de rastreio iFood

Merchant implementa própria experiência usando os endpoints.Nota: iFood não enviará OTP. Validação é responsabilidade do merchant.

3.1 Confirmar endereço

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

Resposta: 202 Accepted
Evento: DELIVERY_ADDRESS_CHANGE_USER_CONFIRMED

3.2 Solicitar alteração

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

Parâmetros obrigatórios:

streetName, neighborhood, city, state, country
coordinates (latitude, longitude)

Prazo para respostaMerchant tem 15 minutos para aceitar/rejeitar. Após isso, rejeição automática.

Limite: Alteração máxima de 500m da coordenada originalEvento: DELIVERY_ADDRESS_CHANGE_REQUESTED

3.3 Aceitar alteração

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

Evento: DELIVERY_ADDRESS_CHANGE_ACCEPTEDErro RegionMismatch: Gera evento automático DELIVERY_ADDRESS_CHANGE_DENIED com metadata.action="region-mismatch"

3.4 Rejeitar alteração

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

Evento: DELIVERY_ADDRESS_CHANGE_DENIED

Erros comuns

Código	Status	Descrição
BadRequest	400	Parâmetros inválidos
OrderNotFound	404	Pedido não encontrado ou expirado (>8h)
ChangeAddressOperationConflict	409	Conflito com operação existente
ChangeAddressOperationNotStarted	409	Nenhuma alteração pendente
MaxDistanceHigherThanAllowed	400	Alteração > 500m
RegionMismatch	400	Novo endereço em região diferente

4. Cancelamento

Cancele pedidos com salesChannel="POS".

4.1 Obter códigos de cancelamento

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

Resposta 200 OK:

[{
  "cancelCodeId": "817",
  "description": "O cliente cancelou o pedido pelo restaurante"
}]

Resposta 204: Pedido não pode mais ser cancelado

4.2 Cancelar pedido

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

Body:

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

Resposta: 202 AcceptedEventos:

CANCELLATION_REQUESTED
CANCELLED (sucesso) ou CANCELLATION_REQUEST_FAILED (falha)

5. Nível de confiança na entrega

Sistema de scoring baseado em regras de validação.

Níveis disponíveis

Nível	Descrição
LOW	Confiança baixa
MODERATE	Confiança moderada
HIGH	Confiança alta
VERY_HIGH	Confiança muito alta

Regras de cálculo

Regra	Descrição
customer_phone_valid	Telefone válido (não STORE, >11 dígitos)
customer_phone_is_fixed	Telefone fixo (8 dígitos)
customer_address_confirmed	Endereço confirmado pelo cliente
customer_address_change_requested	Cliente solicitou alteração
merchant_address_change_approved	Merchant aprovou alteração
merchant_address_change_denied	Merchant negou alteração

Exemplos de scoring

customer_phone_valid:false → LOW
customer_phone_is_fixed:true → MODERATE
customer_phone_is_fixed:true + customer_address_confirmed:true → VERY_HIGH
customer_phone_valid:true → HIGH
customer_phone_valid:true + alteração aprovada → VERY_HIGH
customer_phone_valid:true + alteração negada → LOW

Consultar nível

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

Resposta 200 OK:

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

Erros:

400 OrderWithoutSafeDelivery: Pedido sem regras de confiança
404 OrderNotFound: Pedido não encontrado

O score pode mudar após a criação do pedido baseado nas ações do cliente e merchant.

Próximos passos

Esta página foi útil?

Avalie sua experiência no novo Developer portal: