Usa nuestra API
La API REST es la superficie cruda de la plataforma: cada capacidad, expuesta en sus endpoints tal cual. Los SDK son una capa delgada sobre estos mismos endpoints, así que nada de lo que leas aquí queda fuera de lo que ellos llaman.
Cuándo te conviene
Este es tu camino si tu stack no tiene SDK oficial, o si necesitas un endpoint que el SDK todavía no envuelve. Si te ves escribiendo el envoltorio tú mismo, mira primero Usa el SDK: cubre la API completa y ya pagina y traduce los errores por ti.
Conectarte
Necesitas una sola cosa: una clave secreta sk_. La emite un OWNER o ADMIN de tu empresa desde el panel (API Keys) y queda ligada a tu empresa; su valor completo se muestra solo al crearla — después la plataforma no puede recuperarlo. Guárdala en la variable NIMOBASE_SECRET_KEY.
Nada más. La URL la maneja el cliente: no hay base URL que configurar. Si llamas con curl y necesitas el host de tu entorno, consulta Entornos.
Cómo usarlo
Primer request: lista las empresas activas de tu tenant (Companies). TU_HOST es el host de tu entorno — ver Entornos — y v1 es la versión del contrato: las rutas de esta documentación se muestran sin prefijo, así que al llamar a mano lo agregas tú.
curl "https://TU_HOST/v1/companies?page=1&limit=20" \
-H "X-API-Key: $NIMOBASE_SECRET_KEY"No llega un array plano: cada listado viene en un envelope con el conteo y la página que pediste.
{
"data": [/* las empresas de esta página */],
"total": 12,
"page": 1,
"limit": 20
}data— las instancias de la página pedida.total— el conteo real del listado completo.pageylimit— la página y el tamaño que se aplicaron.
Una página fuera de rango no es un error: data llega vacío y total sigue reflejando el conteo real.
Paginación — todo listado acepta ?page (default 1) y ?limit (default 20, máximo 100). El tope de 100 instancias por request lo impone el API.
Errores — el estado HTTP dice qué falló, y el mensaje del body lo concreta:
| Estado | Cuándo aparece |
|---|---|
400 | La entrada no se puede procesar: un campo inválido, o una entidad que todavía solo tiene borrador. |
401 | No hay credencial válida — la clave no existe o fue revocada (Invalid API key), o alcanzó su fecha de expiración (API key has expired). |
403 | La clave es válida pero su lista de operaciones no incluye lo que llamaste (Insufficient authorization for this operation), o al plan le falta la funcionalidad pedida. |
404 | El recurso no existe — también responde 404 una lectura de otro tenant, sin filtrar que existe. |
409 | Conflicto con una regla de negocio: un límite de plan alcanzado, una rotación sobre una clave ya revocada. |
Un 401 en un request que por lo demás luce correcto suele significar que la clave fue rotada: la rotación invalida el secreto anterior de inmediato, sin período de gracia.
Siguientes pasos
- Entornos — Producción y Sandbox, y cómo los eliges.
- Módulos — los endpoints de cada capacidad, con sus roles y límites.
- Usa el SDK — la misma API, ya envuelta.