API y agentes de TuTiendita
Este documento resume cómo un agente de IA o integrador puede descubrir catálogos, crear órdenes y sincronizar el estado de un comercio habilitado con TuTiendita Online.
1. Descubrimiento y contexto
- Cada tienda expone un endpoint público `https://{subdominio}.tutiendita.online/api/catalog`. Incluye metadatos de idioma, moneda, zonas de servicio y métodos activos (pickup, delivery).
- El catálogo retorna productos estructurados (SKU, nombre bilingüe, descripción, precio, inventario, etiquetas dietarias) y reglas de sustitución sugeridas por el comerciante.
2. Autenticación y permisos
- Para crear órdenes se usa OAuth 2.1 client credentials. Solicita credenciales al comercio o a Chimera Labs. Las credenciales se limitan por tienda y nivel de permisos.
- Incluye el token Bearer en `Authorization`. Cada solicitud debe indicar el `agent_id` para rastreo.
3. Creación de órdenes
- POST `/api/orders` acepta lista de SKU + cantidad, tipo de fulfillment (pickup/delivery), datos de contacto y método de pago preferido.
- El backend valida stock y reglas de sustitución. Si requiere confirmación humana, el agente recibirá un estado `pending_confirmation` y un webhook cuando el comerciante lo apruebe.
4. Webhooks y seguimiento
- Configura un webhook para recibir eventos `order.accepted`, `order.ready`, `order.completed` y `order.cancelled`.
- Los webhooks se firman con HMAC-SHA256 usando la clave provista en el panel del comerciante.
5. Buenas prácticas
- Respeta ventanas de servicio del comercio y límites de velocidad (máx. 60 requests por minuto por tienda).
- Incluye instrucciones claras para clientes finales: tiempos de retiro, documento requerido y políticas de sustitución.
- Para soporte de agentes, escribe a agents@tutiendita.online.