Ayuda · Integraciones y API

Cómo crear una llave de la API y hacer la primera consulta

La API deja que otro sistema lea tus pedidos, tu menú, tus reservas y el estado de tus mesas. Para entrar, ese sistema usa una llave: una clave larga que creas tú, con los permisos justos, y que puedes revocar cuando quieras. La primera parte de esta guía es para quien administra la cuenta; la segunda, para quien programa la conexión.

#Paso 1: abre la pestaña API

Abre Configuraciones y elige API, en el grupo Desarrolladores. Ahí ves las llaves que ya existen, con sus permisos y la última vez que se usó cada una.

Captura del sistema, sólo para clientesConfiguraciones → API. Cada llave muestra sus permisos y cuándo se usó por última vezVerla con tu cuenta

#Paso 2: crea una llave por sistema

Pulsa Nueva llave, ponle un nombre que diga quién la va a usar («Contabilidad», «Tienda en línea») y marca sólo los permisos que ese sistema necesita:

Conviene una llave por sistema: si un día hay que revocar una, las demás integraciones siguen funcionando.

Captura del sistema, sólo para clientesNueva llave: el nombre y sólo los permisos que ese sistema necesitaVerla con tu cuenta

#Paso 3: copia la llave en ese momento

Al pulsar Crear llave, la llave completa aparece una sola vez. Cópiala y pásasela a quien programa la conexión por un canal seguro. Nosotros guardamos sólo una huella de la llave, así que ni el equipo de CorekChat puede volver a mostrártela: si se pierde, se revoca y se crea otra.

Captura del sistema, sólo para clientesLa llave completa se ve una única vez. Después, sólo su comienzoVerla con tu cuenta

Trátala como una contraseña: no la pegues en un chat grupal, en un correo reenviado ni en un repositorio de código.

#Revocar una llave

Revocar la deja inservible al instante: la próxima consulta con esa llave recibe un rechazo. Hazlo cuando cambies de proveedor, cuando alguien que la conocía deje el equipo o si sospechas que se filtró. Puedes tener hasta diez llaves activas a la vez.

#Para quien programa: cómo se consulta

Todas las consultas van a esta dirección base, con la llave en el encabezado Authorization:

https://corekchat.com/api/v1
Authorization: Bearer ck_live_...

Un primer pedido de prueba, que trae los cinco pedidos más recientes:

curl -H "Authorization: Bearer ck_live_TU_LLAVE" \
  "https://corekchat.com/api/v1/orders?limit=5"

#Lo que se puede consultar

Las fechas van en formato ISO 8601 (2026-09-27T00:00:00-05:00). Los importes van en pesos colombianos y sin decimales.

#Cómo vienen las respuestas

Una lista trae los resultados en data y dice si hay más:

{
  "data": [
    {
      "id": "8f1c…",
      "status": "delivered",
      "channel": "whatsapp",
      "branch_id": "3a2e…",
      "customer_name": "Julián Pardo",
      "total": 42000,
      "currency": "COP",
      "items": [
        {
          "product_id": "b71d…",
          "name": "Hamburguesa La Esquina",
          "quantity": 2,
          "subtotal": 38000
        }
      ],
      "cancellation_reason": null,
      "created_at": "2026-09-27T13:05:12.000Z",
      "updated_at": "2026-09-27T13:40:02.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "8f1c…"
}

Para la página siguiente, repite la consulta con cursor= igual al next_cursor que llegó. Se pagina por cursor y no por número de página a propósito: si entran pedidos mientras recorres la lista, no se repiten ni se saltan filas. Cada página trae 25 resultados por defecto y 100 como máximo (limit).

Una mesa trae además su status —available (libre), occupied (ocupada) o bill_requested (pidió la cuenta)— y, si está abierta, la session con la hora en que se abrió.

#Errores

Los errores tienen siempre la misma forma, con un code estable contra el que se puede programar:

{ "error": { "code": "insufficient_scope", "message": "…" } }

#Límite de consultas

Cada llave puede hacer hasta 120 consultas por minuto. Las respuestas traen los encabezados x-ratelimit-limit, x-ratelimit-remaining y x-ratelimit-reset para que el sistema sepa cuánto le queda. Si necesitas enterarte de cada pedido al instante, no consultes la API cada pocos segundos: usa los webhooks, que avisan solos.