Modelo de datos

• Los campos van en inglés y snake_case. Cada objeto dice qué es en object.
• Todo campo del esquema viene siempre: si no hay dato, va null (nunca se omite). La única excepción es customer en la venta, que viene sólo con include=customer.
• Fechas ISO 8601 con el huso de la sucursal y milisegundos: 2026-10-27T09:15:02.123-03:00. Las de los clientes, con el huso de la casa matriz.
• Importes como número con hasta 2 decimales, en la moneda de la sucursal (currency, ISO 4217).
• En la v1 sólo se agregan campos y valores: ignorá lo que no conozcas y aceptá valores nuevos en los enumerados.

La cuenta es la casa matriz de una cadena (o el local, si es uno solo). Una credencial ve la matriz y todas sus sucursales de hoy; cada objeto trae su branch_id. La matriz sale con is_headquarters: true. El external_code de una sucursal es el código que le pone el comercio, para cruzarla con tu sistema.

• Una sucursal que entra a la cadena trae su historia con su updated_at de siempre (viejo): la sincronización incremental no la ve. Compará GET /branches en cada corrida y, para una nueva, hacé una carga inicial con branch_id=<nueva> y una fecha vieja.
• Una sucursal que sale de la cadena desaparece de todos los listados, sin lápida. Lo que ya sincronizaste de ella queda en tu base: decidí vos qué hacer. En la v1 active de una sucursal es siempre true.

Cada orden de Kicket es una venta: lo que se cobra en el mostrador, lo que pide una mesa, un pedido de la carta online, uno de delivery. En una mesa, cada ronda es una venta y check_id las agrupa: es la cuenta de la mesa.

items viene en árbol: parent_item_id apunta al renglón padre. La plata vive en un solo nivel, así la suma de line_total de los renglones vigentes da el total.

• external_code es el código externo vigente del producto, leído al armar la respuesta: si lo cambiás después, las ventas viejas muestran el nuevo. Pero cambiarlo no mueve el updated_at de las ventas: las que ya sincronizaste se quedan con el código de antes. Para cruzar, usá product_id contra /products (ahí sí se mueve updated_at cuando cambia el código).
• modifier_id sale del nombre del adicional u opción: es el mismo en toda la cadena y cambia si el local lo renombra. En la v1 no hay un catálogo de modificadores: los conocés por las ventas.
• Un renglón anulado sale aparte con voided: true, cuándo y por qué. Si de 3 cafés se anularon 2, hay un renglón vivo con 1 y uno anulado con 2.
• quantity tiene hasta 3 decimales; en lo que se vende al peso, unit es kg. Lo que se vende por litro también sale con kg en la v1: el número son litros.
• Cada renglón cumple line_total = unit_price × quantity − discount. Los centavos que no cierran (un precio que no da justo en centavos, lo pesado) van en el descuento del último renglón y, en la venta, como un descuento other llamado «Redondeo» (de pocos centavos, puede ser negativo). Un descuento sin rótulo sale como other «Ajuste».
• En los descuentos, benefit es el premio del programa de puntos (Kickets) y company el de una empresa, también el que se da por el dominio del mail.
• Un combo anulado entero sale como combo anulado en $0, con su valor en los componentes anulados (al revés que un combo vivo): así lo anulado nunca se cuenta dos veces.
• combo_name dice de qué combo salió un renglón, también en ventas viejas, de antes de que existiera el árbol, donde los componentes vienen como product sueltos.

[
  {
    "object": "sale_item",
    "sale_id": "6720a3f1c9e2b4d7a1f3e8c2",
    "parent_item_id": null,
    "product_id": "66b2e47a91c3d05f8e2a4b61",
    "external_code": "CAF-010",
    "modifier_id": null,
    "combo_name": null,
    "quantity": 1,
    "unit": "unit",
    "unit_price": 2800,
    "discount": 280,
    "line_total": 2520,
    "voided": false,
    "voided_at": null,
    "void_reason": null,
    "id": "6720a3f1c9e2b4d7a1f3e8c3",
    "kind": "product",
    "name": "Café con leche"
  },
  {
    "object": "sale_item",
    "sale_id": "6720a3f1c9e2b4d7a1f3e8c2",
    "parent_item_id": "6720a3f1c9e2b4d7a1f3e8c3",
    "product_id": null,
    "external_code": null,
    "modifier_id": "a3f9c2e1b7d04",
    "combo_name": null,
    "quantity": 1,
    "unit": "unit",
    "unit_price": 600,
    "discount": 60,
    "line_total": 540,
    "voided": false,
    "voided_at": null,
    "void_reason": null,
    "id": "6720a3f1c9e2b4d7a1f3e8c3:m:a3f9c2e1b7d04",
    "kind": "modifier",
    "name": "Leche de almendras"
  },
  {
    "object": "sale_item",
    "sale_id": "6720a3f1c9e2b4d7a1f3e8c2",
    "parent_item_id": "6720a3f1c9e2b4d7a1f3e8c3",
    "product_id": null,
    "external_code": null,
    "modifier_id": "o5e1d7c3a9b20",
    "combo_name": null,
    "quantity": 1,
    "unit": "unit",
    "unit_price": 0,
    "discount": 0,
    "line_total": 0,
    "voided": false,
    "voided_at": null,
    "void_reason": null,
    "id": "6720a3f1c9e2b4d7a1f3e8c3:m:o5e1d7c3a9b20",
    "kind": "modifier",
    "name": "Tamaño: Grande"
  },
  {
    "object": "sale_item",
    "sale_id": "6720a3f1c9e2b4d7a1f3e8c2",
    "parent_item_id": null,
    "product_id": "66b2e47a91c3d05f8e2a4b70",
    "external_code": "CMB-002",
    "modifier_id": null,
    "combo_name": "Desayuno clásico",
    "quantity": 1,
    "unit": "unit",
    "unit_price": 7500,
    "discount": 750,
    "line_total": 6750,
    "voided": false,
    "voided_at": null,
    "void_reason": null,
    "id": "6720a3f1c9e2b4d7a1f3e8d0",
    "kind": "combo",
    "name": "Desayuno clásico"
  },
  {
    "object": "sale_item",
    "sale_id": "6720a3f1c9e2b4d7a1f3e8c2",
    "parent_item_id": "6720a3f1c9e2b4d7a1f3e8d0",
    "product_id": "66b2e47a91c3d05f8e2a4b62",
    "external_code": "PAN-003",
    "modifier_id": null,
    "combo_name": "Desayuno clásico",
    "quantity": 1,
    "unit": "unit",
    "unit_price": 0,
    "discount": 0,
    "line_total": 0,
    "voided": false,
    "voided_at": null,
    "void_reason": null,
    "id": "6720a3f1c9e2b4d7a1f3e8c4",
    "kind": "combo_component",
    "name": "Medialunas (3)"
  },
  {
    "object": "sale_item",
    "sale_id": "6720a3f1c9e2b4d7a1f3e8c2",
    "parent_item_id": "6720a3f1c9e2b4d7a1f3e8d0",
    "product_id": "66b2e47a91c3d05f8e2a4b63",
    "external_code": "BEB-021",
    "modifier_id": null,
    "combo_name": "Desayuno clásico",
    "quantity": 1,
    "unit": "unit",
    "unit_price": 0,
    "discount": 0,
    "line_total": 0,
    "voided": false,
    "voided_at": null,
    "void_reason": null,
    "id": "6720a3f1c9e2b4d7a1f3e8c5",
    "kind": "combo_component",
    "name": "Jugo de naranja"
  },
  {
    "object": "sale_item",
    "sale_id": "6720a3f1c9e2b4d7a1f3e8c2",
    "parent_item_id": null,
    "product_id": "66b2e47a91c3d05f8e2a4b64",
    "external_code": "COC-104",
    "modifier_id": null,
    "combo_name": null,
    "quantity": 1,
    "unit": "unit",
    "unit_price": 4500,
    "discount": 0,
    "line_total": 4500,
    "voided": true,
    "voided_at": "2026-10-27T09:31:12.045-03:00",
    "void_reason": "Lo pidió por error",
    "id": "6720a3f1c9e2b4d7a1f3e8c6:v1",
    "kind": "product",
    "name": "Tostado de jamón y queso"
  }
]

/products trae una fila por sucursal: el «Café con leche» de una cadena de siete locales son siete productos, cada uno con su product_id, su precio y su estado. chain_product_id los junta: es el mismo en las copias que la casa matriz vinculó: las que nacen del alta de la cadena y las que se juntan en Cadena → «Vínculos entre sucursales» (el código externo no las vincula).

• Para «el producto de la cadena», agrupá por chain_product_id; si viene null, el producto no está vinculado: usá su id.
• La disponibilidad es por fila: status y active de la copia de cada sucursal.
• barcode es el código de barras del producto (el que lee el lector de la caja): único por sucursal y null si no tiene. No es el external_code, que es el código de tu sistema.
• Los renglones de las ventas traen el product_id de la copia de la sucursal: para sumar por producto de la cadena, cruzalo contra /products.

Los pagos de una venta suman su total. Además de la plata que entró, hay créditos que cubren una parte; los distingue kind:

• method_id es la clave estable del medio (la lista de abajo) y method_type su familia: cash, debit, credit, transfer, qr, wallet u other.
• amount es la parte del total que cubre; charged_amount, lo que de verdad se cobró con ese medio (en lo online, con servicio, propina y envío; en la caja y la mesa, la parte que se cargó, sin la propina; null en los créditos).
• Los pagos de una venta son un conjunto: cuando cambia el updated_at de la venta, reemplazalos todos. Si se corrige el reparto, un pago puede cambiar de id.
• Una devolución sale del pago por cuyo medio volvió la plata: si una venta pagada con efectivo y débito devuelve una parte en efectivo, sólo el pago en efectivo queda partially_refunded. charged_amount es lo que se cobró con ese medio, refunded_amount lo que volvió y amount lo que quedó de la venta en ese medio.
• En una venta CANCELED los pagos salen approved si la plata quedó en la caja, y canceled si nunca se cobró (una venta duplicada o cargada por error): ahí ningún pago suma.

Casi todos son el id de Kicket: 24 caracteres hexadecimales, únicos en toda la plataforma. Algunos objetos no tienen un id propio en Kicket y la API les arma uno estable:

• El consumo que viene incluido con una entrada y los vales de regalo: su plata está en la entrada, y Analítica tampoco los cuenta como ventas.
• Los checkouts que nadie pagó (un link de cobro sin pagar). Cuando se pagan, aparecen.
• Las cajas abiertas: sólo se exponen cerradas.
• Las sucursales que dejaron de ser parte de la cadena.
• Mails del equipo, notas internas y datos de pagadores: nunca salen.

Un cliente es una persona en toda la cuenta: el mismo cus_… en todas las sucursales. Se identifica por su teléfono (en E.164) o, si no dejó, por su mail. La venta trae customer_id (o null si fue anónima); el cliente completo pide customers:read. El id es opaco: con él no se puede recuperar el teléfono ni el mail. Ver la referencia.

• Si alguien dejó primero sólo el mail y después el teléfono, son dos clientes en la v1: unirlos le cambiaría el id a uno que ya sincronizaste.
• updated_at se mueve sólo cuando cambian sus datos (nombre, teléfono, mail, una sucursal nueva), no con cada compra: last_purchase_at cambia sin moverlo.
• GET /customers?phone=… y ?email=… llevan el dato personal en la URL: no dejes esas URLs en logs que vea cualquiera. Lo que escribe el personal en el motivo de una anulación (void_reason) sale con los mails y teléfonos tapados.
• Los clientes los arma Kicket cada minuto: el customer_id de una venta recién cobrada puede llegar uno o dos minutos antes que el cliente a /customers (mientras tanto, su GET da 404 e include=customer no lo trae).