Inicio
Qué es @cartamatic/pos-sdk, qué resuelve y cómo se debe consumir en Cartamatic.
@cartamatic/pos-sdk es el SDK TypeScript privado, server-side y neutral por proveedor para integraciones POS de Cartamatic.
Su objetivo es que las aplicaciones Cartamatic consuman una fachada propia y estable, mientras el SDK encapsula autenticación, URLs, query params, validación runtime, normalización y acceso crudo controlado por proveedor.
Alcance Actual
| Proveedor | Estado | Notas |
|---|---|---|
| Toteat | Base implementada | Endpoints de lectura/escritura, webhooks, pruebas mockeadas e integración real opt-in. |
| Fudo | Planificado | Primero debe curarse contexto de provider en Cartamatic/pos-skills. |
Mapa De Repositorios
| Repo | Propósito | Quién lo usa |
|---|---|---|
Cartamatic/pos-sdk | Implementación del SDK y fuente canónica de API pública. | Apps Cartamatic y CI de release. |
Cartamatic/pos-sdk-docs | Documentación humana curada. | Equipo Cartamatic. |
Cartamatic/pos-sdk-skill | Skill generada para agentes que consumen el SDK. | Agentes en repos de apps. |
Cartamatic/pos-skills | Contexto privado de implementación por provider. | Agentes que mantienen adapters. |
Regla Principal
El SDK es solo backend.
Úsalo en route handlers, server actions, jobs, servicios internos y tests. No lo importes en client components, bundles públicos ni código que pueda ejecutarse en el browser.
Versionado
El SDK está pre-1.0.0. La API se estabiliza a medida que validamos payloads reales y consumo de aplicaciones Cartamatic.
| Rango | Uso esperado |
|---|---|
0.2.x | Base Toteat mockeada, webhooks, fixtures documentales y capturas locales. |
0.3.x | Primeras fixtures reales sanitizadas y esquemas más estrictos. |
0.4.x | Integración inicial en dashboards Cartamatic. |
1.0.0 | API estable validada contra provider real y consumidores productivos. |
Qué Debes Leer Primero
Instalación, para configurar GitHub Packages y dependencias.Uso server-side, para ver el patrón correcto de consumo.Multi-restaurante, si trabajas en dashboards multi-tenant.Referencia API, para revisar todas las funciones, métodos, tipos y errores expuestos por el SDK.Toteat, para entender endpoints, límites, retries y estado de cobertura.
Reglas Críticas
| Regla | Motivo |
|---|---|
No usar NEXT_PUBLIC_* para credenciales POS. | Las credenciales quedarían expuestas al browser. |
| No crear un singleton global para todos los restaurantes. | Cada request debe resolver su conexión POS autorizada. |
| No loggear URLs Toteat sin redacción. | Toteat envía credenciales por query string. |
No usar raw.request() como camino normal. | Pierdes la fachada normalizada y validada del SDK. |
| No reintentar escrituras automáticamente. | Puede duplicar órdenes, despachos o movimientos de compra. |