Autenticación
Una clave de API identifica a una empresa. No hay usuarios ni contraseñas en la API.
Crear una clave
Desde la aplicación, en Ajustes → Claves de API. Al crearla se muestra una sola vez: la plataforma no guarda la clave, solo un hash SHA-256 de ella, así que nadie —tampoco el soporte— puede recuperarla después. Si la pierdes, se revoca y se crea otra.
Cada clave tiene un nombre que eliges tú. Ponle el del sistema que la va a usar («ERP producción», «script de conciliación»): cuando haya que revocar una, el nombre es lo único que permite saber qué se va a romper.
Formato
Una clave se ve así, y sus primeros caracteres —el prefijo— son lo único que se muestra en el listado para poder identificarla sin revelarla:
grc_live_Xf8kQ2mPz9vLnR4tYw7bHsJcA1dE6gUiEnviarla en cada petición
En la cabecera x-tenant-api-key. Se acepta también x-api-key como alias, por compatibilidad con clientes que ya usan ese nombre.
bash
curl -X POST https://app.grclaft.com/api/tx-monitor/ingest \
-H "x-tenant-api-key: grc_live_Xf8kQ2mPz9vLnR4tYw7bHsJcA1dE6gUi" \
-H "content-type: application/json" \
-d '{ "reference": "TX-001", "txType": "TRANSFER_OUT", "channel": "ONLINE",
"amount": 1500000, "currency": "COP", "occurredAt": "2026-09-21T14:32:00Z" }'javascript
const res = await fetch(
"https://app.grclaft.com/api/tx-monitor/ingest",
{
method: "POST",
headers: {
"x-tenant-api-key": process.env.GRC_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
reference: "TX-001",
txType: "TRANSFER_OUT",
channel: "ONLINE",
amount: 1500000,
currency: "COP",
occurredAt: new Date().toISOString(),
}),
},
);python
import os, requests
respuesta = requests.post(
"https://app.grclaft.com/api/tx-monitor/ingest",
headers={"x-tenant-api-key": os.environ["GRC_API_KEY"]},
json={
"reference": "TX-001",
"txType": "TRANSFER_OUT",
"channel": "ONLINE",
"amount": 1500000,
"currency": "COP",
"occurredAt": "2026-09-21T14:32:00Z",
},
timeout=30,
)Nunca desde el navegador
Una clave enviada desde código que corre en el navegador es una clave pública: quien abra las herramientas de desarrollo la ve. Las llamadas con clave se hacen desde tu servidor. Si necesitas datos en una pantalla propia, que los pida tu backend.
Estados de una clave
| Estado | Qué pasa | Respuesta |
|---|---|---|
| Activa | Funciona con normalidad. | 200 |
| Revocada | Se anuló a mano desde la aplicación. No se puede reactivar; se crea otra. | 401 |
| Caducada | Pasó su fecha de expiración, si se le puso una al crearla. | 401 |
| Inexistente | La clave no corresponde a ninguna registrada. Suele ser un copiado incompleto. | 401 |
Los cuatro casos responden 401 a propósito: distinguirlos en la respuesta le diría a quien prueba claves al azar cuáles existen.
Permisos de la clave
Al crear la clave eliges qué puede hacer. Para cargar operaciones en el monitoreo transaccional hace falta write:transactions; para leerlas, read:transactions. Una clave con admin puede todo.
Dale solo el permiso que su sistema necesita. Esa clave va a vivir dentro de tu ERP o de tu core, y una credencial con admin guardada en un sistema de terceros vale tanto como la cuenta entera. Una clave sin el permiso recibe 403 y la respuesta dice qué permiso le falta.
Cuántas peticiones por minuto
El tope lo fija tu plan y se aplica por clave. Al pasarlo, la respuesta es 429 con la cabecera Retry-After: 60, y dice cuál es tu límite.
Si vas a cargar un histórico o un cierre de día, usa /api/tx-monitor/ingest/batch: son hasta 500 operaciones en una sola petición, así que gasta una del cupo en vez de 500. La ingesta es idempotente por reference, de modo que repetir un lote tras un corte no duplica nada.
Rotación
Rotar una clave es crear la nueva, desplegarla en tu sistema y revocar la vieja después, en ese orden. Al revés hay una ventana en la que tu integración está caída.
La plataforma registra la última vez que se usó cada clave. Antes de revocar una que no reconoces, mira esa fecha: si es reciente, algo tuyo la está usando.