Referencia API

Todas las funciones, clases, métodos y tipos públicos expuestos por @cartamatic/pos-sdk.

Esta página lista la superficie pública actual del package @cartamatic/pos-sdk.

Exports Runtime

Export	Tipo	Uso principal
`createPosClient`	función	Crear la fachada provider-neutral que usan las apps.
`createToteatClient`	función	Crear cliente Toteat directo para tests, adapter work o diagnóstico.
`parseToteatWebhook`	función	Parsear webhooks Toteat soportados.
`redactToteatCredentials`	función	Redactar objetos con credenciales Toteat.
`redactToteatUrl`	función	Redactar query params sensibles en URLs Toteat.
`TOTEAT_REDACTED_VALUE`	constante	Valor usado por helpers de redacción: `[REDACTED]`.

createPosClient

const createPosClient = (options: CreatePosClientOptions): PosClient;

Crea un cliente POS neutral por proveedor. Es la función que debe usar código de producto.

const pos = createPosClient({
  provider: "toteat",
  toteat: {
    restaurantId,
    localId,
    userId,
    apiToken
  }
});

CreatePosClientOptions:

type CreatePosClientOptions = {
  provider: PosProviderId;
  toteat?: ToteatClientOptions;
};

Si provider es "toteat" y no se entrega toteat, lanza Error.

createToteatClient

const createToteatClient = (options: ToteatClientOptions): PosClient;

Crea una implementación Toteat del mismo PosClient. Úsala solo para tests, adapter work o diagnóstico específico de provider.

ToteatClientOptions:

type ToteatClientOptions = {
  restaurantId: string;
  localId: string;
  userId: string;
  apiToken: string;
  baseUrl?: string;
  environment?: "production" | "development";
  fetch?: FetchLike;
  readRetry?: false | PosRetryOptions;
  requestTimeoutMs?: number;
};

PosClient

type PosClient = {
  provider: PosProviderId;
  capabilities: PosCapabilities;
  accounting: PosAccountingClient;
  catalog: PosCatalogClient;
  fiscal: PosFiscalClient;
  inventory: PosInventoryClient;
  orders: PosOrdersClient;
  purchases: PosPurchasesClient;
  raw: PosRawClient;
  sales: PosSalesClient;
  shifts: PosShiftsClient;
  tables: PosTablesClient;
};

Métodos Del Cliente

Namespace	Método	Firma	Retorno
`catalog`	`getProducts`	`(options?: GetProductsOptions)`	`Promise<PosProduct[]>`
`tables`	`getTables`	`()`	`Promise<PosTable[]>`
`shifts`	`getCurrentShiftStatus`	`()`	`Promise<PosShiftStatus>`
`orders`	`createOrder`	`(options: CreateOrderOptions)`	`Promise<PosOrderSubmissionResult>`
`orders`	`getOrderStatus`	`(options: GetOrderStatusOptions)`	`Promise<PosOrderStatus>`
`orders`	`getCancellationReport`	`(options: GetOrderCancellationReportOptions)`	`Promise<PosOrderCancellation[]>`
`orders`	`notifyDispatch`	`(options: NotifyOrderDispatchOptions)`	`Promise<PosOrderDispatchResult>`
`sales`	`getSales`	`(options: GetSalesOptions)`	`Promise<PosSale[]>`
`sales`	`getSalesByWaiter`	`(options: GetSalesByWaiterOptions)`	`Promise<PosSalesByWaiterReport[]>`
`sales`	`getCollection`	`(options: GetCollectionOptions)`	`Promise<PosCollectionReport>`
`fiscal`	`getFiscalDocuments`	`(options: GetFiscalDocumentsOptions)`	`Promise<PosFiscalDocument[]>`
`inventory`	`getInventoryState`	`(options: GetInventoryStateOptions)`	`Promise<PosInventoryState>`
`accounting`	`getAccountingMovements`	`(options: GetAccountingMovementsOptions)`	`Promise<PosAccountingMovements>`
`purchases`	`createPurchaseMovement`	`(options: CreatePurchaseMovementOptions)`	`Promise<PosPurchaseMovementResult>`
`raw`	`request`	`<TResponse>(path: string, options?: RawRequestOptions)`	`Promise<TResponse>`

Opciones Por Método

catalog.getProducts

type GetProductsOptions = {
  activeProducts?: boolean;
};

Lee productos y devuelve PosProduct[].

orders.getOrderStatus

type GetOrderStatusOptions = {
  orderId: string;
  detailType?: "ONLY_STATUS" | "ALL_INFORMATION" | "DELIVERY_INFORMATION";
};

Consulta una orden por ID provider.

orders.createOrder

type CreateOrderOptions = {
  order: PosCreateOrderPayload;
  returnOrderDetail?: boolean;
};

order debe ser un objeto no vacío. El SDK conserva una forma abierta porque faltan fixtures reales para confirmar el shape completo de document.

orders.notifyDispatch

type NotifyOrderDispatchOptions = {
  orderId: string;
  platform: string;
  status: string;
  errorMessage?: string | null;
  trackingUrl?: string | null;
};

orderId, platform y status deben ser strings no vacíos.

Fechas De Reportes

Los métodos siguientes usan YYYY-MM-DD y validan máximo 15 días cuando aplica:

type PosDateRangeOptions = {
  startDate: string;
  endDate: string;
};

Método	Opciones adicionales
`sales.getSales`	`includeCancelledOrderDetails?: boolean`
`sales.getSalesByWaiter`	Ninguna
`orders.getCancellationReport`	Ninguna
`fiscal.getFiscalDocuments`	`documentType?: PosFiscalDocumentType`
`inventory.getInventoryState`	Ninguna
`accounting.getAccountingMovements`	`includeSales?: boolean`

sales.getCollection

type GetCollectionOptions = {
  date: string;
};

date usa YYYY-MM-DD.

purchases.createPurchaseMovement

type CreatePurchaseMovementOptions = {
  invoiceNumber: string;
  emissionDate: string;
  providerVat: string;
  invoiceType: string;
  lineDetails: PosPurchaseLineDetail[];
  referenceNumber?: string;
  status?: string;
  comment?: string;
  dueDate?: string;
  accountingDate?: string;
  currency?: string;
  netAmount?: number;
  taxesAmount?: number;
  totalAmount?: number;
  taxes?: PosPurchaseTax[];
};

Campos obligatorios no vacíos: invoiceNumber, emissionDate, providerVat, invoiceType. lineDetails debe tener al menos un item.

raw.request

type RawRequestOptions = {
  method?: "GET" | "POST";
  query?: Record<string, string | number | boolean | null | undefined>;
  body?: unknown;
  retry?: false | PosRetryOptions;
  timeoutMs?: number;
};

type PosRetryOptions = {
  maxRetries?: number;
  delayMs?: number;
  statusCodes?: number[];
};

En Toteat los retries solo aplican a GET. Si method es POST, el retry efectivo es cero.

Modelos Normalizados

Tipo	Uso
`PosProduct`	Producto normalizado.
`PosTable`	Mesa normalizada.
`PosShiftStatus`	Estado actual de turno.
`PosOrderStatus`	Estado resumido de orden.
`PosOrderCancellation`	Item de reporte de cancelación.
`PosOrderSubmissionResult`	Resultado de crear orden.
`PosOrderDispatchResult`	Resultado de notificar despacho.
`PosSale`	Venta normalizada.
`PosSalesByWaiterReport`	Reporte de ventas por garzón.
`PosCollectionReport`	Recaudación de un día.
`PosFiscalDocument`	Documento fiscal.
`PosInventoryState`	Estado agregado de inventario.
`PosAccountingMovements`	Movimientos contables.
`PosPurchaseMovementResult`	Resultado de movimiento de compra.
`PosProviderStore`	Referencia normalizada a bodega/local externo.

Todos los modelos preservan raw: unknown cuando corresponde.

Errores Exportados

Clase	Cuándo ocurre	Metadata segura
`PosValidationError`	Input inválido antes de llamar al provider.	`provider`
`PosNetworkError`	Timeout, abort o fallo antes de recibir respuesta.	`provider`, `method`, `path`, `cause`
`PosHttpError`	HTTP no exitoso.	`provider`, `method`, `path`, `status`, `statusText`, `responseBody`
`PosJsonError`	Respuesta HTTP OK con JSON inválido.	`provider`, `method`, `path`, `responseBody`
`PosResponseError`	JSON válido pero respuesta provider no exitosa.	`provider`, `response`

method y path nunca incluyen query string Toteat.

Webhooks Exportados

parseToteatWebhook soporta eventos:

order_status_changed
shifts_status_changed
menu_changed
product_transfer

Los tipos exportados incluyen:

ParseToteatWebhookOptions
ToteatWebhookAuthenticationOptions
ToteatWebhookEventType
ToteatWebhook
ToteatWebhookBase
ToteatWebhookEnvelopeBase
ToteatOrderStatusChangedWebhook
ToteatShiftsStatusChangedWebhook
ToteatMenuChangedWebhook
ToteatProductTransferWebhook

Tipos Utilitarios Exportados

Tipo	Uso
`PosProviderId`	Provider soportado: actualmente `"toteat"`.
`FetchLike`	Transport inyectable compatible con `fetch`.
`JsonObject`	Extensiones y payloads abiertos.
`PosCapabilities`	Matriz de capacidades por provider.
`ToteatEnvironment`	`"production"` o `"development"`.
`ToteatClientOptions`	Credenciales y opciones de construcción Toteat.
`ToteatSensitiveQueryParam`	Query params Toteat sensibles.
`ToteatSensitiveCredentialField`	Campos de credenciales Toteat sensibles.

On this page