Conceptos

Modelo mental del SDK: fachada neutral, provider adapters, capacidades y modelos normalizados.

El SDK separa tres niveles:

App server-side

Código Cartamatic que resuelve autorización, credenciales y workflows de producto.

Fachada POS neutral

Contrato estable PosClient que no filtra detalles de Toteat a la app.

Adapter de provider

Implementación específica que traduce métodos normalizados a la API externa.

Fachada neutral

Las apps deben consumir PosClient, no endpoints Toteat directamente.

El cliente expone namespaces de negocio:

Namespace	Responsabilidad
`catalog`	Productos y menú.
`tables`	Mesas y configuración de salón.
`shifts`	Estado de turnos.
`orders`	Órdenes externas, estado, cancelaciones y despacho.
`sales`	Ventas, recaudación y reportes por garzón.
`fiscal`	Documentos fiscales.
`inventory`	Estado y movimientos de inventario.
`accounting`	Movimientos contables.
`purchases`	Movimientos de compra.
`raw`	Escape hatch temporal para provider.

Capabilities

Usa pos.capabilities para condicionar workflows.

Evita checks por provider

No distribuyas checks como if (provider === "toteat") por la app. Esa lógica debe quedar encapsulada en el SDK o en un punto acotado.

if (pos.capabilities.sales.getSales) {
  const sales = await pos.sales.getSales({
    startDate: "2026-07-01",
    endDate: "2026-07-15"
  });
}

Modelos normalizados

Los modelos normalizados son conservadores. Muchos campos son null porque aún faltan fixtures reales sanitizadas para confirmar payloads completos.

Ejemplo: PosProduct.

type PosProduct = {
  provider: "toteat";
  providerProductId: string | null;
  name: string | null;
  available: boolean | null;
  price: number | null;
  raw: unknown;
};

raw existe para auditoría y debugging. No lo uses para reemplazar el modelo normalizado en código de producto.

raw no es contrato de producto

raw puede cambiar con el provider. Si un campo se vuelve necesario para producto, promuévelo a modelo normalizado del SDK.

Acceso raw

raw.request() permite pedir paths específicos del provider mientras se implementa o depura una integración.

const payload = await pos.raw.request("products");

Rango de fechas

Los endpoints Toteat de reportes usan fechas públicas YYYY-MM-DD.

El adapter convierte esas fechas al formato wire de Toteat (YYYYMMDD) cuando corresponde.

Los endpoints con rango máximo validan 15 días antes de hacer la request.