Documentación
Introducción
Qué es la API de NiuCore, qué modelo mental necesitás y qué entra en la v1.0.
La API pública de NiuCore expone 54 operaciones —los recursos bajo https://api.niucore.com/api/v1 más los cuatro endpoints OAuth— para conversar con los modelos de la organización, administrar el conocimiento que usan y leer las métricas de consumo. Es la misma plataforma que usa la aplicación, con el mismo motor y las mismas reglas.
El modelo mental
Hay una idea de la que se deriva casi todo lo demás: una credencial no es un usuario nuevo, es un permiso para actuar como uno existente.
Cuando alguien crea una credencial, esa credencial hereda su acceso: sus permisos, sus bibliotecas, su licencia, su empresa. Los scopes recortan ese acceso; nunca lo amplían. Si mañana esa persona pierde un permiso, la credencial lo pierde en el request siguiente, sin que nadie tenga que tocarla.
De ahí salen dos consecuencias que conviene tener claras desde el principio: un 403 casi nunca se arregla desde el código —se arregla en la configuración del usuario o de la credencial— y una integración de larga vida no debería colgar de la cuenta personal de alguien que puede irse de la empresa.
Qué podés hacer
Qué no entra en la v1.0
Preferimos decirlo acá y no que lo descubras a mitad de una integración:
| No se puede | Por qué |
|---|---|
| Subir ni eliminar archivos de una biblioteca. | La ingesta de documentos sigue siendo de la aplicación. La API lee bibliotecas y archivos, y crea o edita bibliotecas. |
| Autorizar un conector nuevo (Gmail, Drive, Calendar…). | Completar un OAuth exige un navegador y una persona. Se usan los que el usuario ya conectó. |
| Crear o editar áreas y usuarios. | Es administración de la organización, no automatización. |
| Administrar credenciales por API. | La API pública no puede fabricarse más acceso a sí misma. |
El permission_mode: "plan" de la aplicación. | Su ciclo —aprobar un plan y después seguirlo a lo largo de varios turnos— la API todavía no lo modela. La interacción plan_approval sí existe: llega en manual o en auto cuando el modelo propone un plan dentro del turno, y se responde con `respond-plan`. |
Los chats de la API
El espacio de nombres público de un chat es (empresa, usuario, credencial). Un chat creado desde la aplicación, o por otra credencial del mismo usuario, no existe para tu credencial: no lo lista, no lo lee y no le puede mandar un turno.
En la aplicación pasa lo contrario: los chats que crea tu integración aparecen en la lista del usuario como cualquier otro, y se pueden leer, renombrar y continuar desde la interfaz. El aislamiento es del espacio de nombres, no del dato.
Versionado
Esta documentación describe la v1.0. La versión viaja en la URL, y dentro de v1 los cambios son compatibles hacia adelante: pueden aparecer campos nuevos, pero no desaparece uno existente ni cambia su significado. Programá ignorando lo que no conocés.