Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Shipping

Pedidos fuera de la plataforma iFood

Esta sección explica cómo integrar pedidos realizados fuera de la plataforma iFood (no poseen orderId preexistente) al servicio de entrega Bajo Demanda.

Flujo de integración

1. Verificar disponibilidad

Antes de registrar el pedido, consulte la disponibilidad de entrega para validar la cobertura y obtener estimaciones.

¿Por qué verificar?

Validar área de cobertura
Identificar indisponibilidad temporal
Obtener estimación de tiempo y costo
Evitar errores en el registro

Aunque opcional, esta verificación previene errores y permite una mejor planificación operacional.

Endpoint

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

Parámetros obligatorios:

merchantId (path) - ID del merchant
latitude (query) - Latitud de la dirección de entrega
longitude (query) - Longitud de la dirección de entrega

Respuesta exitosa - 200 OK

Campos de la respuesta

Campo	Tipo	Descripción
id	uuid	ID de la cotización
expirationAt	datetime	Validez de la cotización (UTC)
createdAt	datetime	Fecha de creación (UTC)
distance	integer	Distancia en metros
preparationTime	integer	Tiempo de preparación en segundos
quote.grossValue	decimal	Valor bruto
quote.discount	decimal	Descuento
quote.raise	decimal	Incremento
quote.netValue	decimal	Valor neto
deliveryTime.min	integer	Tiempo mínimo de entrega (segundos)
deliveryTime.max	integer	Tiempo máximo de entrega (segundos)
hasPaymentMethods	boolean	Indica métodos de pago disponibles
paymentMethods[].method	string	CREDIT, DEBIT o CASH

Ejemplo

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

Errores - 400 Bad Request

Códigos de error

Código	Descripción
BadRequest	Problema en la solicitud. Verifique los datos
BadRequestMerchant	Merchant no disponible
DeliveryDistanceTooHigh	Dirección fuera del área de cobertura
OffOpeningHours	Fuera del horario de funcionamiento
OriginNotFound	Tienda fuera del área logística
ServiceAreaMismatch	Dirección fuera del área de cobertura
HighDemand	Logística temporalmente no disponible
MerchantStatusAvailability	Merchant con pendencia
InvalidPaymentMethods	Forma de pago no aceptada
NRELimitExceeded	Límite de repartidores alcanzado
UnavailableFleet	Flota no disponible

2. Registrar pedido

Registre el pedido para solicitar automáticamente un repartidor socio.

Un repartidor será asignado automáticamente después del registro
Si la entrega no es posible, el pedido no será registrado
Asegúrese de validar los datos antes de enviar

Código de confirmación de entrega

Por seguridad, se genera automáticamente un código de confirmación (4 últimos dígitos del teléfono).

Cómo funciona

Con código (por defecto):

Envíe customer.phone.type="CUSTOMER" con teléfono válido
El repartidor solicitará el código en la entrega
El cliente debe ser informado previamente

Sin código:

Envíe customer.phone.type="STORE"
No se solicitará código

Informe al cliente que el repartidor solicitará los 4 últimos dígitos del teléfono. La falla en la validación puede resultar en cancelación.

Para socios sin página de rastreo iFood

Consuma el evento DELIVERY_DROP_CODE_REQUESTED con metadata.CODE para poner el código a disposición del cliente.

Endpoint

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

Campos del pedido

Campos obligatorios marcados con *

Customer (Cliente)

Campo	Tipo	Descripción
customer.name*	string	Nombre (máx. 50 caracteres)
customer.phone.type	string	CUSTOMER (por defecto) o STORE
customer.phone.countryCode*	string	Código del país (2 dígitos). Ej: 55
customer.phone.areaCode*	string	Código de área (2 dígitos). Ej: 11
customer.phone.number*	string	Teléfono (7-9 dígitos)

* No obligatorio si customer.phone.type="STORE"

Delivery (Entrega)

Campo	Tipo	Descripción
delivery.merchantFee*	float	Tarifa del socio
delivery.preparationTime	integer	Tiempo de preparación (segundos)
delivery.quoteId	uuid	ID de la cotización
delivery.deliveryAddress.postalCode*	string	Código postal (8 dígitos)
delivery.deliveryAddress.streetNumber*	string	Número
delivery.deliveryAddress.streetName*	string	Calle (máx. 50 caracteres)
delivery.deliveryAddress.complement	string	Complemento (máx. 50 caracteres)
delivery.deliveryAddress.reference	string	Referencia (máx. 70 caracteres)
delivery.deliveryAddress.neighborhood*	string	Barrio (máx. 50 caracteres)
delivery.deliveryAddress.city*	string	Ciudad (2-50 caracteres)
delivery.deliveryAddress.state*	string	Estado (2 letras). Ej: SP
delivery.deliveryAddress.country*	string	País (2 letras). Ej: BR
delivery.deliveryAddress.coordinates.latitude*	float	Latitud
delivery.deliveryAddress.coordinates.longitude*	float	Longitud

Items (Artículos)

Campo	Tipo	Descripción
items[].id*	uuid	ID del artículo
items[].name*	string	Nombre (máx. 50 caracteres)
items[].externalCode	string	Código externo
items[].quantity*	integer	Cantidad (> 0)
items[].unitPrice*	float	Precio unitario (≥ 0)
items[].price*	float	Precio total (quantity * unitPrice)
items[].optionsPrice*	float	Precio de los complementos (≥ 0)
items[].totalPrice*	float	Total (price + optionsPrice)

Payments (Pagos)

Pago Offline:

Campo	Tipo	Descripción
payments.methods[].method*	string	CREDIT, DEBIT o CASH
payments.methods[].type*	string	OFFLINE
payments.methods[].value*	float	Valor
payments.methods[].card.brand*	string	Marca (si CREDIT/DEBIT)
payments.methods[].cash.changeFor*	float	Cambio (si CASH)

Pago Online: No enviar objeto payments (procesado por el merchant)

Otros campos

Campo	Tipo	Descripción
displayId	string	ID amigable (máx. 4 caracteres). Ej: A4BC
metadata	object	Información adicional (máx. 20 caracteres)

Tiempo de preparación

Use delivery.preparationTime para retrasar la asignación del repartidor.

No enviado: Asignación inmediata
Enviado: Asignación después del tiempo especificado (en segundos)

Informe el tiempo más preciso posible. Tiempos incorrectos pueden resultar en:

Retrasos en la entrega
Mala experiencia para el cliente
Posible cierre por acumulación de repartidores

Respuesta exitosa - 202 Accepted

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

Integración con polling

Los pedidos están disponibles en el polling de eventos
Identificados por salesChannel="POS"
Rastreo disponible vía endpoint de tracking

Errores - 400 Bad Request

Código	Descripción
BadRequest	Problema en la solicitud
BadRequestCustomer	Cliente no disponible
BadRequestMerchant	Merchant no disponible
DeliveryDistanceTooHigh	Fuera del área de cobertura
HighDemand	Logística no disponible temporalmente
MerchantEasyDeliveryDisabled	Servicio no habilitado
OffOpeningHours	Fuera del horario de funcionamiento
OriginNotFound	Tienda fuera del área logística
PaymentMethodNotFound	Método de pago no encontrado
PaymentTotalInvalid	Valor del pago no corresponde al total
ServiceAreaMismatch	Dirección fuera de la cobertura
NRELimitExceeded	Límite de repartidores alcanzado

3. Confirmación/alteración de dirección

Permite que el cliente confirme o solicite alteración de la dirección de entrega después de la creación del pedido.

Flujos disponibles

Con página de rastreo iFood

El cliente usa la página de iFood para confirmar/alterar la dirección.Requisitos:

El pedido NO puede tener customer.phone.type="STORE"
Teléfono válido es obligatorio para OTP

Envíe el teléfono correcto usado como WhatsApp para recibir el código OTP de confirmación.

Sin página de rastreo iFood

El merchant implementa su propia experiencia usando los endpoints.Nota: iFood no enviará OTP. La validación es responsabilidad del merchant.

3.1 Confirmar dirección

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

Respuesta: 202 Accepted
Evento: DELIVERY_ADDRESS_CHANGE_USER_CONFIRMED

3.2 Solicitar alteración

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

Parámetros obligatorios:

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

Plazo para respuestaEl merchant tiene 15 minutos para aceptar/rechazar. Después de eso, rechazo automático.

Límite: Alteración máxima de 500m de la coordenada originalEvento: DELIVERY_ADDRESS_CHANGE_REQUESTED

3.3 Aceptar alteración

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

Evento: DELIVERY_ADDRESS_CHANGE_ACCEPTEDError RegionMismatch: Genera evento automático DELIVERY_ADDRESS_CHANGE_DENIED con metadata.action="region-mismatch"

3.4 Rechazar alteración

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

Evento: DELIVERY_ADDRESS_CHANGE_DENIED

Errores comunes

Código	Status	Descripción
BadRequest	400	Parámetros inválidos
OrderNotFound	404	Pedido no encontrado o expirado (>8h)
ChangeAddressOperationConflict	409	Conflicto con operación existente
ChangeAddressOperationNotStarted	409	Ninguna alteración pendiente
MaxDistanceHigherThanAllowed	400	Alteración > 500m
RegionMismatch	400	Nueva dirección en región diferente

4. Cancelación

Cancele pedidos con salesChannel="POS".

4.1 Obtener códigos de cancelación

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

Respuesta 200 OK:

[{
  "cancelCodeId": "817",
  "description": "El cliente canceló el pedido por el restaurante"
}]

Respuesta 204: El pedido ya no puede ser cancelado

4.2 Cancelar pedido

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

Body:

{
  "reason": "Cliente solicitó cancelación",
  "cancellationCode": "817"
}

Respuesta: 202 AcceptedEventos:

CANCELLATION_REQUESTED
CANCELLED (éxito) o CANCELLATION_REQUEST_FAILED (falla)

5. Nivel de confianza en la entrega

Sistema de scoring basado en reglas de validación.

Niveles disponibles

Nivel	Descripción
LOW	Confianza baja
MODERATE	Confianza moderada
HIGH	Confianza alta
VERY_HIGH	Confianza muy alta

Reglas de cálculo

Regla	Descripción
customer_phone_valid	Teléfono válido (no STORE, >11 dígitos)
customer_phone_is_fixed	Teléfono fijo (8 dígitos)
customer_address_confirmed	Dirección confirmada por el cliente
customer_address_change_requested	Cliente solicitó alteración
merchant_address_change_approved	Merchant aprobó alteración
merchant_address_change_denied	Merchant rechazó alteración

Ejemplos 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 + alteración aprobada → VERY_HIGH
customer_phone_valid:true + alteración rechazada → LOW

Consultar nivel

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

Respuesta 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"
}

Errores:

400 OrderWithoutSafeDelivery: Pedido sin reglas de confianza
404 OrderNotFound: Pedido no encontrado

El score puede cambiar después de la creación del pedido basándose en las acciones del cliente y merchant.

Próximos pasos

¿Esta página fue útil?

Evalúa tu experiencia en el nuevo portal de desarrolladores: