Uso Server-Side
Patrones recomendados para consumir el SDK desde backend, jobs y route handlers.
El SDK debe instanciarse dentro de código server-side, después de resolver la conexión POS autorizada.
Flujo Recomendado
request / server action / job
-> resolver tenant, restaurante y local autorizado
-> leer conexión POS desde storage seguro
-> createPosClient(...)
-> ejecutar método normalizado
-> mapear resultado a la appEjemplo: Leer Productos
import { createPosClient } from "@cartamatic/pos-sdk";
export const syncProductsForLocal = async ({ tenantId, restaurantId, localId }: SyncInput) => {
const posConnection = await loadRestaurantPosConnection({ tenantId, restaurantId, localId });
const pos = createPosClient({
provider: posConnection.provider,
toteat: {
restaurantId: posConnection.externalRestaurantId,
localId: posConnection.externalLocalId,
userId: posConnection.externalUserId,
apiToken: posConnection.apiToken
}
});
const products = await pos.catalog.getProducts({ activeProducts: true });
return products.map((product) => ({
externalId: product.providerProductId,
name: product.name,
available: product.available,
price: product.price
}));
};Timeouts Y Reintentos
El cliente Toteat soporta timeout por request y retries solo para lecturas GET.
const pos = createPosClient({
provider: "toteat",
toteat: {
restaurantId,
localId,
userId,
apiToken,
requestTimeoutMs: 15_000,
readRetry: {
maxRetries: 1,
delayMs: 250,
statusCodes: [408, 429, 500, 502, 503, 504]
}
}
});Las operaciones POST nunca se reintentan automáticamente.
Error Handling Seguro
import { PosHttpError, PosNetworkError, PosValidationError } from "@cartamatic/pos-sdk";
try {
return await pos.sales.getSales({ startDate, endDate });
} catch (error) {
if (error instanceof PosValidationError) {
throw new Error(`Solicitud POS inválida: ${error.message}`);
}
if (error instanceof PosHttpError || error instanceof PosNetworkError) {
console.error("Fallo al consultar POS", {
provider: error.provider,
method: error.method,
path: error.path
});
}
throw error;
}Los errores de request exponen method y path sin query string para evitar filtrar credenciales.
Anti-Patrones
| No hagas esto | Por qué |
|---|---|
| Importar el SDK en client components. | Expone lógica y puede filtrar credenciales. |
Guardar credenciales POS en NEXT_PUBLIC_*. | Se publican al browser. |
| Reintentar escrituras manualmente sin idempotencia. | Puede duplicar acciones en el POS. |
Usar raw.request como integración permanente. | Evita validación, normalización y contratos del SDK. |
| Loggear config Toteat completa. | Contiene restaurantId, localId, userId y apiToken. |