Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Guía de implementación — Order API

Implemente Order API paso a paso, desde recibir pedidos hasta su resolución completa.Requisitos previos:

Comprenda los Fundamentos (tipos de pedido, categorías, SLA)
Tenga un token de autenticación válido
Elija su método de consumo de eventos (polling o webhook)

1. Recibir nuevos pedidos

Los pedidos llegan como eventos. Elija su método de consumo:

Polling (recomendado para comenzar)

Verifique cada 30 segundos:

curl -X GET "https://merchant-api.ifood.com.br/order/v1.0/orders:polling" \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta (200 OK):

{
  "events": [
    {
      "id": "evt_123",
      "code": "CONFIRMED",
      "fullCode": "ORDER_CONFIRMED",
      "orderId": "ord_456",
      "createdAt": "2024-04-25T18:00:00Z",
      "metadata": {
        "id": "ord_456",
        "status": "CONFIRMED",
        "category": "FOOD",
        "orderType": "DELIVERY",
        "items": [...]
      }
    }
  ]
}

Webhooks (escalable)

Configure su endpoint para recibir eventos directamente. iFood enviará POST con la misma estructura anterior.Implementación en JavaScript:

const express = require('express');
const app = express();

app.post('/webhooks/orders', express.json(), (req, res) => {
  const { events } = req.body;

  events.forEach(event => {
    if (event.code === 'CONFIRMED') {
      // Procesar nuevo pedido
      console.log(`Nuevo pedido: ${event.metadata.id}`);
    }
  });

  // Confirmar inmediatamente
  res.status(200).json({ acknowledged: true });
});

app.listen(3000);

Próximo paso: Después de recibir evento, confirme lectura con /acknowledgment.

2. Confirmar consumo de eventos

Después de procesar eventos, confirme que fueron consumidos:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders:acknowledgment" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "acknowledgedEventIds": ["evt_123", "evt_124"]
  }'

Respuesta (202 Accepted)Importante: Confirme solo eventos que procesó exitosamente. Eventos no confirmados volverán en siguiente consulta.

3. Obtener detalles del pedido

Detalles del pedido

Obtenga los detalles del pedido antes de confirmar o cancelar. Use GET /orders/{id} para verificar artículos, disponibilidad y dirección de entrega.Solicitud:

curl -X GET "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Retorna 200 con todos los detalles del pedido (artículos, pago, dirección, etc.). Retorna 404 para IDs inválidos, pedidos no disponibles o antiguos.

Pedido aún no disponibleEl evento PLACED puede llegar antes de los detalles. Si recibe 404, implemente reintentos con exponential backoff hasta 10 minutos. No haga reintentos infinitos para evitar bloqueos.

Pedidos antiguosLa API mantiene detalles por solo 7 días. Evite consultar repetidamente pedidos antiguos para no sufrir rate limiting.

Detalles de un pedido

Consulte todos los campos disponibles

4. Imprimir recibo

Antes de confirmar, imprima recibo para cocina:Use la estructura del pedido obtenida en paso anterior. Incluya:

ID del pedido (displayId)
Artículos con instrucciones especiales
Modo de entrega (dirección/recogida)
CPF/CNPJ del cliente (si es obligatorio)

Plantilla recomendada: Ver ejemplo

5. Confirmar pedido

Confirme la recepción en 8 minutos. Vea plazo de confirmación para detalles.

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/confirm" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Respuesta (202 Accepted)API retorna inmediatamente. Siguiente consulta muestra resultado:

# Siguiente polling retornará:
{
  "events": [
    {
      "code": "CONFIRMED",  // Éxito
      "orderId": "ord_456"
    }
  ]
}

# O en caso de fallo:
{
  "events": [
    {
      "code": "CANCELLATION_REQUEST_FAILED",  // Rechazo
      "orderId": "ord_456",
      "metadata": {
        "reason": "Inventario insuficiente"
      }
    }
  ]
}

Errores comunes:

Confirmación después de 8 minutos → Pedido ya cancelado
Confirmación duplicada → Ignorado (idempotente)
Token expirado → 401 Unauthorized

Mejor práctica: Almacene orderId y timestamp de confirmación para auditoría.

6. Preparar pedido

Preparar pedido

Los pedidos de alimentos pasan por etapas específicas de preparación. Vea el diagrama a continuación:

Confirmar pedido

Use POST /orders/{id}/confirm para confirmar el pedido.Solicitud:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/confirm" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Retorna 202 Accepted.

Iniciar preparación

Use POST /orders/{id}/startPreparation para iniciar la preparación.Solicitud:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/startPreparation" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Retorna 202 Accepted.

Pedido listo para entrega

Después de preparar, notifique usando:Para entrega:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/dispatch" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Para retirada:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/readyToPickup" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Ambos retornan 202 Accepted.

7. Separar pedido

8. Notificar pedido listo

Notifique cuando la preparación esté completa.

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/readyToPickup" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Requerido para: Pedidos TAKEOUT y DINE_IN. Opcional para DELIVERY con conductor iFood.Para entrega propia, use /dispatch en su lugar.Respuesta (202 Accepted)

9. Despachar entrega propia

Para entrega gestionada por la tienda:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/dispatch" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "deliveredBy": "MERCHANT" }'

Respuesta (202 Accepted)Sistema marca automáticamente como CONCLUDED después de entrega.

10. Rastrear entrega (iFood)

Para pedidos entregados por iFood, rastreé en tiempo real:Requisito previo: Reciba evento ASSIGN_DRIVER (conductor asignado)

curl -X GET "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/tracking" \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta:

{
  "latitude": -23.5505,
  "longitude": -46.6333,
  "expectedDelivery": "2024-04-25T18:30:00Z",
  "pickupEtaStart": 120,
  "deliveryEtaEnd": 600,
  "trackDate": "2024-04-25T18:15:00Z"
}

Limitaciones:

Una solicitud cada 30 segundos (respete rate limiting)
Puede retornar 404 antes de disponibilidad
Solo durante entrega activa

11. Cancelación de pedido

Verificar motivos válidos

curl -X GET "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/cancellationReasons" \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta:

{
  "reasons": [
    { "code": "501", "description": "Error en el sistema" },
    { "code": "502", "description": "Pedido duplicado" },
    { "code": "503", "description": "Artículo no disponible" }
    // ... más códigos
  ]
}

Solicitar cancelación

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/requestCancellation" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "503"
  }'

Respuesta (202 Accepted)Resultado llega en siguiente consulta:

{
  "events": [
    {
      "code": "CANCELLED",  // Éxito
      "orderId": "ord_456"
    }
  ]
}

Restricciones:

Cancelamientos excesivos incurren en sanciones
Más allá de cierto umbral, tienda se cierra temporalmente
Algunos períodos tienen límites de cancelamientos

Flujo con diagrama:

12. Validar recogida

Si está habilitado, conductor proporciona código de recogida:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/validatePickupCode" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

Validación: Compare con pickupCode en detalles del pedido.Respuesta (200 OK):

{ "valid": true }

13. Confirmar entrega

Entrega iFood

Automático — conductor confirma vía app.

Entrega propia

Comparta enlace con conductor:

https://confirmacao-entrega-propria.ifood.com.br/

Imprima el localizador (phone.localizer) en recibo como referencia.

Validar entrega

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/verifyDeliveryCode" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "654321"
  }'

Respuesta (200 OK):

{ "valid": true }

Después de validación, sistema marca automáticamente como CONCLUDED.

14. Procesar modificaciones de pedido

Cliente elimina/añade artículos después de confirmación:

{
  "events": [
    {
      "code": "ORDER_PATCHED",
      "orderId": "ord_456",
      "metadata": {
        "changeType": "DELETE_ITEMS",
        "items": [
          {
            "id": "item_789",
            "name": "Hamburguesa",
            "quantity": 1
          }
        ]
      }
    }
  ]
}

Acciones necesarias:

Actualizar recibo de cocina (eliminar artículo)
Actualizar sistema de facturación
Confirmar lectura del evento

15. Procesar disputas post-entrega

¿Cliente disputa después de entrega? Responda en negociación:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/dispute_123/accept" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "CUSTOMER_SATISFACTION",
    "detailReason": "Reembolso por cortesía"
  }'

Opciones de respuesta:

/accept — Concordar con cancelamiento
/reject — Desacuerdo con propuesta
/alternative — Ofrecer reembolso o tiempo adicional

Crítico: Tiene hasta expiresAt para responder. Sin respuesta = acción automática (reembolso).Aprenda más: Guía Plataforma de Negociación

16. Conclusión automática

iFood marca automáticamente como CONCLUDED después:

Tipo	Inmediato	Programado
Restaurante + iFood	Entrega o 6h	6h después scheduling.to
Restaurante + Propio	4h	4h después scheduling.to
Supermercado/Farmacia	13h	13h después scheduling.to

Todos incluyen deliveryTimeInSeconds (configuración tienda).Recibirá evento CONCLUDED:

{
  "code": "CONCLUDED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T19:00:00Z"
}

Lectura siguiente

Estructura de datos — Campos completos del pedido
Referencia rápida — Referencia de endpoints
Todos los eventos — Catálogo de eventos
Negociación — Guía Plataforma de Negociación
¿Listo para prod? — Criterios de homologación

¿Esta página fue útil?

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