API de Kicket
Conectá tu sistema (un ERP, tu BI, tu software de gestión) con Kicket: leé las ventas, los pagos, el catálogo, los clientes y las cajas de tu comercio, y vinculá tus productos con tus propios códigos.
Qué es
Es una API REST de lectura, servidor a servidor, que devuelve JSON. Una credencial ve toda la cuenta: la casa matriz y sus sucursales, o el local, si es uno solo. Lo único que se escribe es el código externo de un producto o combo, para que tu sistema y Kicket hablen de lo mismo.
| Qué | Cómo |
|---|---|
| URL base | https://kicket.club/api/v1 |
| Autenticación | OAuth 2.0 client credentials (token Bearer de una hora) |
| Formato | JSON en UTF-8; errores en application/problem+json (RFC 9457) |
| Fechas | ISO 8601 con el huso de la sucursal y milisegundos |
| Importes | Números con hasta 2 decimales, en la moneda de la sucursal |
| Paginación | Por cursor, en orden fijo (updated_at, id), con sincronización incremental |
| Límite | 300 pedidos por minuto por credencial |
| Avisos | Webhooks firmados (Standard Webhooks) |
| Contrato | OpenAPI 3.1 |
Entornos: producción y prueba
Hay una sola URL. El entorno lo decide la credencial que uses, y la respuesta de GET / te dice cuál es (environment).
| Entorno | Credencial | Qué lee |
|---|---|---|
| Producción | kc_live_… | Los datos reales de tu cuenta. |
| Prueba | kc_test_… | Una cuenta de prueba de Kicket con datos de ficción: los mismos endpoints y las mismas formas, para desarrollar sin tocar lo real. Cada respuesta trae el header Kicket-Environment: test. |
Qué trae la cuenta de prueba
- Una casa matriz y tres sucursales, con los códigos
SBX-CASA-CENTRAL,SBX-PALERMO,SBX-BELGRANOySBX-MICROCENTRO. - Productos con código externo (
CAF-001,PAS-…,SAL-…,BEB-…, uno al pesoALM-001) y uno sin código; combos con pasos (CMB-001) y fijos (CMB-002). - Ventas de las últimas 30 jornadas en todos los estados y casi todos los canales (no hay
qr_table,kioskniother), una ronda de mesa abierta y una venta borrada (con su lápida). - Clientes con teléfonos y mails de ficción, y cajas cerradas con su arqueo.
- Los datos se renuevan cuando Kicket la vuelve a sembrar: no esperes ventas nuevas a cada minuto.
- La cuenta de prueba es una sola para todos los que integran:
PATCH /products/{id}valida y responde como en producción (también el 409), pero no guarda. Y los webhooks de prueba reciben sólotest.ping.
Versión
Ésta es la versión 1, publicada el 29 de octubre de 2026. Va en la URL (/api/v1) y en el header Kicket-Api-Version: 1 de cada respuesta.
En la v1 nada de lo que existe se renombra ni se borra: sólo se agregan campos, valores y rutas. Por eso tu código tiene que ignorar los campos que no conoce y aceptar valores nuevos en los enumerados (por ejemplo, un canal nuevo). Cada cambio queda en Cambios.
La guía
- Primeros pasosDe cero a la primera llamada en cinco minutos.
- AutenticaciónCredenciales, tokens, permisos, rotación y buenas prácticas.
- Paginación y sincronizaciónCursores,
updated_since, lápidas y la receta completa para tener tu base al día. - ErroresCada código de error, qué significa y qué hacer.
- Límites de usoCuántos pedidos por minuto, los headers y cómo reintentar.
- WebhooksAvisos firmados cuando una venta o un producto cambia.
- ConciliaciónCómo cuadrar tus números con los de Analítica.
- Modelo de datosVentas, renglones, combos, pagos, ids y qué queda afuera.
- ReferenciaCada endpoint con sus parámetros, su respuesta y un ejemplo.
- DescargasEl OpenAPI, Postman, Insomnia y cómo generar un cliente.
- CambiosQué cambió en cada versión.
¿Necesitás ayuda?
Escribinos a kicket@kicket.club. Si es por un error, mandanos el request_id de la respuesta (también viene en el header X-Request-Id): con eso lo encontramos enseguida. Nunca nos mandes el secreto de la credencial.