Homologación del módulo Order

Valide que su integración Order API cumple con los requisitos de producción. Cuando las tiendas fallan en recibir o confirmar pedidos, los clientes experimentan cancelaciones.Todas las aplicaciones deben cumplir con estos criterios funcionales y no-funcionales antes de ir en vivo.

Requisitos previos

Registro de cuenta Profesional (CNPJ) — las cuentas Personal/Estudiante (CPF) no pueden completar homologación
Aplicación lista para pruebas (app completa, no solo llamadas a API)
Datos de tienda de prueba (ID de tienda, nombre de tienda)
Conexión a internet estable

Criterios de homologación

Tu aplicación debe cumplir con estos requisitos funcionales y no funcionales para integrar el módulo Order.

Requisitos funcionales

Todas las aplicaciones deben soportar:

Consumo de eventos vía polling o webhook
- Para polling: Solicita el endpoint /polling cada 30 segundos para permanecer disponible en la plataforma
  - Usa el header x-polling-merchants para filtrar eventos por comerciante
  - Filtra eventos por tipo y grupo según sea necesario
- Para webhook: Responde exitosamente a las solicitudes de webhook (verificado por auditoría interna)
- Envía /acknowledgment para todos los eventos recibidos con estado 200
Confirmación y envío de pedidos
- Recibe y confirma pedidos delivery inmediatos (orderType = DELIVERY, orderTiming = IMMEDIATE)
- Recibe y confirma pedidos delivery programados (orderType = DELIVERY, orderTiming = SCHEDULED)
  - Muestra la fecha y hora programadas
- Recibe y confirma pedidos para recoger (orderType = TAKEOUT)
Cancelación de pedidos
- Consulta el endpoint /cancellationReasons para obtener códigos/razones disponibles para el momento del pedido
- Muestra los motivos de cancelación disponibles en el sistema PDV
- Acepta cancelaciones de cliente o iFood
Manejo de pagos
- Recibe y muestra detalles de pago con tarjeta (marca de tarjeta)
- Recibe y muestra pago en efectivo con monto de cambio en pantalla y/o recibo
Manejo de promociones
- Recibe cupones de descuento y muestra el monto y responsabilidad del subsidio (iFood/Tienda)
Visualización de información del pedido
- Muestra observaciones de artículos en pantalla y/o recibo (ejemplo: "Quitar cebolla")
- Muestra CPF/CNPJ en pantalla si es requerido o completa automáticamente en documento fiscal
- Muestra código de recolección en pantalla y/o recibo
Prevención de duplicados
- Descarta eventos duplicados si se reciben más de una vez durante polling
Sincronización de pedidos
- Actualiza el estado del pedido cuando es alterado por otras aplicaciones (ej: Order Manager)
Negociación de pedidos
- Recibe y procesa eventos de Plataforma de Negociación de Pedidos

Requisitos específicos por categoría

Alimentos & Restaurantes

Además de los requisitos funcionales anteriores:

Muestra observaciones de entrega en recibo (del campo delivery.observations)
Sigue el modelo de recibo sugerido en la documentación

Supermercados, Farmacias & Otras Categorías

Además de los requisitos funcionales anteriores:

Importa pedidos vía endpoint virtual-bag en estado SPE
Limita solicitudes de acknowledgment a 2000 event IDs por solicitud (divide en múltiples solicitudes si es necesario)
Envía acknowledgment después de procesar eventos (no inmediatamente), para evitar pérdida de datos

Requisitos no funcionales

Todas las aplicaciones deben:

Renovar tokens solo cuando estén a punto de expirar o inmediatamente después de la expiración
Respetar las políticas de rate limit de cada endpoint

Requisitos deseables

Recomendados pero no obligatorios:

Seguir modelo de recibo sugerido
Mostrar observaciones de entrega en recibo

Prueba y validación

Usa el Web Order Manager para:

Confirmar y cancelar pedidos de prueba
Validar que tu aplicación actualiza el estado cuando es alterado por otro sistema
Probar sincronización entre aplicaciones