---
title: Cómo crear una llave de la API y hacer la primera consulta
updated: 2026-10-06
canonical: https://corekchat.com/ayuda/api-publica
---

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 clientes: La sección API de Configuraciones con una llave activa llamada Contabilidad)

## 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:

| Permiso | Qué puede leer |
|---|---|
| Leer pedidos | Pedidos con sus productos, estado y total |
| Leer productos y menú | Productos, precios, disponibilidad y categorías |
| Leer reservas | Reservas con su fecha, cantidad de personas y estado |
| Leer mesas y estado del salón | Mesas, en qué piso y zona están, y si están libres u ocupadas (necesita el módulo POS) |

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 clientes: El formulario de nueva llave con el nombre y dos permisos marcados)

## 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 clientes: El aviso «Copie la llave ahora» con la llave completa y el botón Copiar)

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:

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

### Lo que se puede consultar

| Consulta | Permiso | Filtros |
|---|---|---|
| `GET /orders` | Leer pedidos | `status`, `from`, `to` (fecha de creación), `limit`, `cursor` |
| `GET /orders/{id}` | Leer pedidos | — |
| `GET /products` | Leer productos y menú | `available=true` o `false`, `limit`, `cursor` |
| `GET /products/{id}` | Leer productos y menú | — |
| `GET /reservations` | Leer reservas | `status`, `from`, `to` (fecha de la reserva), `limit`, `cursor` |
| `GET /reservations/{id}` | Leer reservas | — |
| `GET /tables` | Leer mesas | `branch_id`, `active=true` o `false`, `limit`, `cursor` |
| `GET /tables/{id}` | Leer mesas | — |

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:

```json
{
  "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:

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

| Estado | `code` | Qué pasó |
|---|---|---|
| 401 | `unauthorized` | Falta la llave, está mal escrita, venció o fue revocada |
| 402 | — | El plan ya no incluye la API, o falta el módulo POS para las mesas (`module_not_purchased`) |
| 403 | `insufficient_scope` | La llave no tiene el permiso para esa consulta |
| 404 | `not_found` | No existe ese pedido, producto, reserva o mesa en tu cuenta |
| 429 | `rate_limited` | Pasaste el límite de consultas; espera lo que indica el encabezado `Retry-After` |

### 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](/ayuda/webhooks), que avisan solos.