Appearance
APIs e integración
Este documento es el corazón del trabajo dev. Es un borrador inicial del contrato entre Nilo y nosotros, derivado del PR/FAQ. Debe alinearse formalmente con Nilo (pendiente #2).
APIs que probablemente exponemos a Nilo
Endpoints HTTP (REST/JSON) que el agente conversacional Nilo invoca para resolver las HU. Nombres y paths son propuestas, no contractuales.
| # | Capacidad de negocio | Endpoint propuesto | HU | Notas |
|---|---|---|---|---|
| 1 | Identificar cliente por BSUID o teléfono | GET /v1/customers?bsuid={bsuid} o ?phone={e164} (al menos uno) | HU-07 | Devuelve N códigos SAP / sucursales asociadas. BSUID es el identificador estable post-junio 2026 (formato {ISO 3166}.{id}); teléfono se acepta como fallback y para usuarios sin username adoptado. Permite que un mismo BSUID/teléfono gestione múltiples puntos de venta. Ver 04-cumplimiento.md § Privacidad de identificadores. |
| 2 | Catálogo de productos | GET /v1/catalog | HU-01 | Filtros por familia, paginación, ETag para caché del agente. |
| 3 | Disponibilidad de stock | GET /v1/products/{sku}/availability?warehouse={id} | HU-01, HU-08 | Lee de SAP SD vía BTP. Caché corta (segundos) con invalidación por evento. |
| 4 | Precio por graduación (Tier) | GET /v1/products/{sku}/price?customerCode={c} | HU-01 | Precio SIEMPRE desde SAP MDM. Nunca hardcoded. Pilar ALCOA Exacto. |
| 5 | Validar límite de crédito | POST /v1/credit/validate | HU-03 | Body: {customerCode, amount} → {approved, remaining, reason}. Síncrono a SAP. |
| 6 | Crear orden de venta | POST /v1/orders | HU-03 | Endpoint más crítico. Idempotente por header Idempotency-Key. SLA <60 s a SAP (P95). |
| 7 | Estatus de orden y ETA | GET /v1/orders/{id}/status | HU-02 | Proxy a DispatchTrack; devuelve ETA + último punto GPS del vehículo + URL de mapa. |
| 8 | Cancelar / modificar orden (probable) | PATCH /v1/orders/{id} | — | A definir con negocio: ventanas de tiempo, autorización. |
| 9 | Recomendaciones por cliente | GET /v1/recommendations?customerCode={c} | HU-09 | Algoritmo basado en historial SAP + prioridades de portafolio. Open: ¿lo aloja Nilo o nosotros? |
| 10 | Base de conocimiento producto | GET /v1/knowledge/{sku} | HU-10 | Ficha técnica curada (Tuboplus, bombas). Es la fuente del RAG de Nilo → exige 0% inexactitudes. |
| 11 | Crear Business Partner (RFC genérico) | POST /v1/business-partners | HU-04 | Para clientes no fiscales: dispara creación automática en SAP. Detalle en 04-cumplimiento.md. |
| 12 | BNPL / aplicación de crédito | POST /v1/credit/apply | Refined Backlog §1 | Pendiente: ¿qué partner financiero? |
| 13 | Eventos: notificación de entrega al cliente | POST /v1/notifications/delivery (callback) | HU-02 | Si preferimos modelo push: nosotros llamamos al agente Nilo cuando cambia el estatus. |
Convenciones generales propuestas
- Versionado en path:
/v1/,/v2/— facilita evolución sin romper a Nilo. - Identificadores: ISO 8601 UTC para timestamps; E.164 para teléfonos;
{ISO 3166 alpha-2}.{id}para BSUID de WhatsApp; ISO 4217 para moneda. - Errores: estructura RFC 7807 (
application/problem+json) —type,title,status,detail,instance. - Trazabilidad: cada request lleva
X-Request-Id(propaga a SAP) y, donde aplique,X-Customer-Code/X-Gps-Lat/Lng.
APIs que nosotros consumimos
SAP (vía BTP Integration Suite)
| Capacidad | Mecanismo | Uso |
|---|---|---|
| Crear orden de venta | iFlow JSON → IDoc ORDERS05 / BAPI BAPI_SALESORDER_CREATEFROMDAT2 | HU-03 |
| Leer maestro de productos / precios | iFlow → BAPI MDM | Caché del catálogo |
| Validar crédito | BAPI BAPI_CUSTOMER_CHECKCREDITLIMIT | HU-03 |
| Crear Business Partner | BAPI BAPI_BUPA_CREATE_FROM_DATA | HU-04 |
| Post Goods Issue | BAPI BAPI_GOODSMVT_CREATE (mov tipo 601) | HU-06 |
Los nombres exactos de BAPI/IDoc son referenciales — los confirmamos al hacer el primer iFlow con el equipo SAP.
DispatchTrack
| Capacidad | Mecanismo | Uso |
|---|---|---|
| Crear envío | POST /shipments (API REST) o IDoc SHPORD según conector | HU-05 |
| Tracking de vehículo | GET /shipments/{id}/tracking | HU-02 |
| Recibir POD | Webhook entrante en POST /v1/internal/webhooks/dispatchtrack/pod | HU-06 |
Nilo (probable, sentido inverso)
Posibles webhooks o llamadas que Nilo nos hace y que Nilo expone para que nosotros publiquemos eventos. Confirmar:
- Webhook nuestro hacia Nilo: cambio de estatus del pedido → para que el agente avise al cliente.
- Webhook Nilo hacia nosotros: identificación del cliente al inicio de la conversación (BSUID requerido; teléfono opcional, viene solo cuando el usuario no haya adoptado username o esté dentro de la ventana de 30 días / Contact Book), cierre de carrito, intención de compra.
Requisitos no funcionales (NFRs)
| NFR | Valor objetivo | Por qué |
|---|---|---|
Latencia POST /v1/orders | <60 s P95 desde request hasta confirmación SAP | ALCOA Contemporáneo + HU-03 |
| Disponibilidad | 99.5% mínimo para endpoints críticos | El asesor no debe abandonar la herramienta |
| Idempotencia | Obligatoria en todos los POST que escriben | Red flaky y retries del agente |
| Auth | OAuth 2.0 client credentials o mTLS — TBD | Pendiente con Nilo |
| Rate limiting | Por client_id, configurable | Proteger SAP de tormentas |
| Audit log | Cada llamada de escritura: who, what, when, GPS, request body cifrado | ALCOA Atribuible |
| Retención de logs | 5 años | Cumplimiento |
| Observabilidad | Tracing distribuido (OpenTelemetry) que cruce Cloud Functions ↔ Cloud Run ↔ BTP | Diagnóstico de SLA <60 s |
| Offline mode | El cliente Nilo lo maneja del lado WhatsApp; nuestro lado debe tolerar bursts de sincronización cuando un asesor sube señal | Texcoco, señal baja |
Idempotencia (detalle)
Cada POST /v1/orders debe llevar Idempotency-Key (UUID). Si llega un duplicado:
- Si la primera ya completó → devolver el mismo resultado (200/201, no 409).
- Si la primera está en curso → encolar / responder 409 con
Retry-After. - Si la primera falló → procesar como nueva.
Mecanismo: tabla idempotency_keys con TTL 24 h, posiblemente en Cloud SQL o Firestore.
Manejo de errores conocidos
| Caso | Status | Comportamiento |
|---|---|---|
| Límite de crédito excedido | 422 + alerta al asesor (HU-03) | El agente Nilo debe explicar al cliente |
| Stock agotado | 409 con alternativas sugeridas | El agente puede ofrecer producto similar |
| Cliente sin RFC y no fiscal | 200 — se crea BP automáticamente | Transparente |
| Timeout en BTP | 504 + log para War Room | Reintento controlado |
| Precio MDM no disponible | 503 (degradación) | Nunca caer a precio hardcoded |
Contratos pendientes
Lo que falta para cerrar el contrato real con Nilo:
- OpenAPI 3.x de nuestros endpoints — primer entregable concreto sugerido.
- Eventos Nilo → nosotros: schema de los webhooks que recibimos.
- Eventos nosotros → Nilo: si existe modelo push.
- Acuerdo de SLAs cruzados (qué pide Nilo de nosotros, qué pedimos de Nilo).
- Modelo de autenticación (mTLS vs OAuth vs API Key con rotación).
Estos son los primeros temas para llevar a la reunión técnica con Nilo. Lista completa en 06-pendientes.md.