PUNI Integration Hub · GRIDO

Una integración simple.
GRIDO vende. PUNI mueve.

Un sandbox diseñado para conectar PediGrido / SmartPedidos con PUNI sin replicar catálogo, stock ni pagos. Una API pequeña, estados claros y control operativo completo por zona.

LOGISTICS_ONLYGRIDO conserva el negocio. PUNI ejecuta la logística.
SIMPLE SKUSKU + cantidad. Sin sincronizar catálogo ni stock.
4 hitosASSIGNED · ACCEPTED · PICKED_UP · DELIVERED
API-firstIdempotencia, HMAC, retries y control por zona.
Arquitectura

Lo mínimo necesario. Nada más.

GRIDO permanece como fuente de verdad comercial. PUNI funciona como infraestructura logística detrás de la experiencia digital.

🍦

GRIDO controla

Cliente, sucursal, productos, sabores, promociones, stock, precios, pago, facturación y aceptación comercial.

🛵

PUNI controla

Cobertura, tarifa de envío, capacidad, asignación, retiro, traslado, entrega, evidencia y eventos logísticos.

01

Pedido GRIDO

Pedido comercial confirmado en el ecosistema GRIDO.

02

Quote PUNI

Cobertura, distancia y precio logístico.

03

Create Order

Un envío único por externalOrderId.

04

Operación

Asignación, retiro y entrega por PUNI.

05

Webhook

GRIDO recibe cada hito logístico.

Estados

Un lenguaje logístico común.

Cuatro estados principales para mapear la operación de forma predecible en PediGrido / SmartPedidos.

ASSIGNEDACCEPTEDPICKED_UPDELIVEREDCANCELLEDINCIDENT
Importante: ACCEPTED en PUNI significa que el repartidor aceptó realizar el envío. No reemplaza la aceptación comercial del local.
API

Contrato claro y reusable.

Una superficie pequeña de endpoints cubre sucursales, tarifas, cotización, pedidos, estados, cancelación y webhooks.

Endpoints principales

GET/capabilitiesContrato disponible
GET/branchesSucursales
POST/branchesAlta / actualización
GET/branches/:id/rates1/2/3 km + excedente
POST/quotesCotización
POST/ordersCrear envío
GET/orders/by-external-id/:idReconciliación
POST/webhooks/testCertificación HMAC
Simple SKU
{
  "items": [
    {
      "sku": "GRIDO-12345",
      "quantity": 2,
      "name": "Producto GRIDO"
    }
  ]
}
Create order
{
  "branchId": "<uuid-puni>",
  "externalOrderId": "GRIDO-ORD-987654",
  "recipientName": "Cliente",
  "recipientPhone": "+5493510000000",
  "dropoffAddress": "Av. Ejemplo 123",
  "dropoffLatitude": -31.42,
  "dropoffLongitude": -64.18,
  "items": [
    { "sku": "GRIDO-12345", "quantity": 2 }
  ]
}
Pricing

Tarifas fáciles de consumir.

PUNI conserva la propiedad del tarifario. GRIDO sólo consulta el esquema vigente para la sucursal habilitada.

tramo1 kmfee vigente por zona
tramo2 kmfee vigente por zona
tramo3 kmfee vigente por zona
excedente+ kmpor km iniciado
Los importes se devuelven dinámicamente por API según la sucursal, la zona y la política tarifaria vigente de PUNI.
Control operativo

Autonomía para GRIDO. Llaves en PUNI.

GRIDO puede automatizar la integración; PUNI conserva dónde opera, cuánto cobra y cuánta capacidad habilita.

Control por sucursal y zona

✓
Sucursal nueva no se autoactiva
✓
Cambio de domicilio requiere nueva aprobación
✓
Kill-switch por partner + zona
✓
Límite de pedidos concurrentes
✓
Tarifa específica por partner/zona

Seguridad

✓
Idempotencia
Un externalOrderId no genera dos repartidores.
✓
HMAC SHA-256
Webhooks firmados.
✓
SSRF protection
Bloqueo de localhost e IPs privadas.
✓
Retries persistidos
Reintentos ante timeout/falla.
Certificación

Validado antes de la certificación conjunta.

El sandbox fue validado internamente con infraestructura aislada, tenant GRIDO propio y pruebas E2E.

Validado internamente ✅

✓
LOGISTICS_ONLY + Simple SKU
✓
Alta pendiente + aprobación PUNI
✓
Rates + quote PARTNER_ZONE
✓
Kill-switch partner/zona
✓
Doble POST → un solo pedido
✓
Cancelación y reconciliación

Próxima etapa conjunta

•
Webhook GRIDO
Confirmar endpoint HTTPS receptor y certificar firma HMAC.
•
Sucursales piloto
Definir ciudad, locales y volumen inicial de certificación.
•
Tracking
Validación conjunta dentro del flujo de PediGrido.
Para activar el piloto

Qué necesitamos de GRIDO.

Pocas definiciones para que la integración sea autónoma desde el primer día.

01 · IDs estables

ID único de pedido y sucursal.

02 · Trigger logístico

Evento exacto que dispara el envío PUNI.

03 · Webhook HTTPS

Endpoint que recibirá nuestros estados.

04 · Piloto

Ciudad, sucursales y volumen estimado.

05 · Evidencia

OTP recomendado, nombre, foto o firma.

06 · SLA

Asignación, retiro, entrega e incidentes.

Siguiente paso

Certificamos juntos. Después escalamos.

Empezamos con una ciudad y pocas sucursales. Cuando operación, estados y capacidad quedan validados, PUNI habilita nuevas zonas sin cambiar el contrato técnico.

PUNI Integration Hub · GRIDO