Codenica API

Codenica API conecta aplicaciones externas con los datos de tu sistema Codenica, tanto en Cloud como en On-Premise. Este artículo explica las reglas comunes de toda la API: crear una clave, elegir ámbitos, localizar la dirección del servicio, autenticar las solicitudes y enviarlas de forma segura. Los campos y las operaciones de cada objeto se describen en artículos API independientes.

Crear una clave API

Empieza a preparar la integración creando la clave API adecuada. La clave pertenece a tu empresa y permite que una aplicación externa ejecute únicamente las operaciones incluidas en los ámbitos seleccionados.

Abre Ajustes y selecciona API y API Keys.
Escribe el nombre de la integración en Nombre, por ejemplo Integración de almacén o Informes BI.
Añade una descripción si quieres identificar más adelante el uso de la clave.
Define la fecha Activo hasta. Un periodo más corto limita las consecuencias de una exposición accidental de las credenciales.
Selecciona solo los ámbitos que necesita la integración.
Selecciona Crear clave API.
Copia inmediatamente el Client ID y el Client Secret y guárdalos en el almacén de secretos utilizado por la integración.

El Client Secret solo se muestra al crear la clave o durante su rotación. La lista conserva la información de la clave, pero no vuelve a mostrar el secreto. Si lo pierdes, rota la clave o elimínala y crea otra.

Panel API Keys en los ajustes de Codenica, con el formulario de creación de claves y la lista de ámbitos de permisos.

Límites de claves según la licencia

Considera cada clave como un canal de acceso independiente para una integración. El número de claves disponibles depende de la licencia de la empresa:

Licencia

Acceso a la API

Máximo de claves activas

Starter

No disponible

Plus

Sí

Enterprise

Sí

100

Al eliminar una clave se elimina su registro y se libera espacio dentro del límite. La operación es permanente, así que comprueba antes que la integración ya no utiliza esa clave.

Cuando llega la fecha de caducidad, la autenticación se detiene, pero el registro sigue visible en la lista.

Si no estableces una fecha final al crearla, la validez predeterminada es de 90 días. Una clave puede estar activa como máximo 5 años. En la práctica, ajusta la fecha al ciclo de revisión de la integración.

Dirección de la API y autenticación

La dirección base depende del modelo de despliegue. Añade /api/v1 y la ruta del recurso elegido a la dirección base.

Cloud: utiliza la dirección pública de la empresa, por ejemplo https://tu-empresa.codenica.com/api/v1.
On-Premise: la dirección predeterminada registrada por Codenica Discovery es http://codenica.local:5150/api/v1. Si el administrador ha publicado la instalación con un nombre DNS propio, un proxy inverso o HTTPS, utiliza la dirección accesible para el servidor de integración. Los detalles del despliegue se describen en la guía de instalación de Codenica On-Premise.

No utilices localhost, una dirección de contenedor ni la dirección de la base de datos, salvo que la aplicación de integración se ejecute exactamente en el mismo equipo y sea una configuración de prueba intencionada. El servidor de integración debe tener acceso de red a la dirección publicada de Codenica.

Autentica cada solicitud de la API con dos cabeceras:

X-Codenica-Client-Id - identificador de la clave;
X-Codenica-Client-Secret - secreto de la clave.

No envíes a la API pública la sesión del panel ni el JWT del usuario. No incluyas nunca el secreto en la URL, los parámetros de consulta, el contenido de las respuestas ni los registros.

export BASE_URL="https://tu-empresa.codenica.com"
export CLIENT_ID="cna_tu_client_id"
export CLIENT_SECRET="cns_tu_client_secret"

curl --request GET \
  --url "$BASE_URL/api/v1/context" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Para la instalación On-Premise predeterminada, sustituye BASE_URL del ejemplo por http://codenica.local:5150. En producción utiliza HTTPS cuando la instalación esté publicada con un certificado.

Formato estándar de las solicitudes

Los ejemplos de los artículos siguientes utilizan una estructura REST sencilla: método, URL, cabeceras y, en las operaciones con contenido, JSON enviado mediante --data-raw. Puedes trasladar este formato directamente al código de la aplicación o a una herramienta de integración.

Las operaciones que modifican datos requieren además la cabecera Idempotency-Key. Asígnale un valor único para cada intención de operación. Repetir exactamente la misma solicitud con la misma clave no debe crear un segundo registro.

curl --request POST \
  --url "$BASE_URL/api/v1/<resource>" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: integration-create-20260907-001" \
  --data-raw '{"field":"value"}'

Para actualizar, eliminar, gestionar relaciones u operar con archivos, envía también la cabecera If-Match con el valor actual de ETag. Las páginas de cada objeto contienen las rutas, los nombres de campos y los cuerpos JSON exactos.

Flujo común de trabajo de una integración

Envía GET /api/v1/context para comprobar los datos de la empresa y el caller, los ámbitos, las capacidades de la API y los límites.
Abre el esquema del objeto que necesitas, por ejemplo GET /api/v1/assets/schema, para conocer sus campos, operaciones, ámbitos y relaciones compatibles.
Obtén las listas de objetos con paginación y filtros. Los parámetros de filtrado se describen en el artículo del objeto correspondiente.
Lee un registro individual por su identificador cuando necesites sus datos actuales y su ETag.
Crea, actualiza y elimina registros utilizando Idempotency-Key y, cuando sea necesario, If-Match.
Utiliza relaciones, archivos, operaciones por lotes y acciones especiales únicamente mediante las rutas documentadas para ese objeto.

Formato común de las respuestas

Las respuestas correctas devuelven los datos en la propiedad data. La información técnica, como requestId y en algunos casos ETag, se encuentra en meta. Conserva requestId en el registro de la integración para localizar rápidamente una solicitud cuando sea necesario diagnosticar un problema.

ETag, reintentos y errores

ETag protege un registro para que no sobrescribas cambios realizados por otra persona o integración. Después de leerlo, guarda el valor de la cabecera ETag. Antes de actualizarlo o eliminarlo, envía ese valor en If-Match. Después de un cambio correcto, utiliza el nuevo valor devuelto por la API.

428 Precondition Required con el código if_match_required significa que falta la cabecera obligatoria If-Match o Idempotency-Key.
412 Precondition Failed con el código if_match_failed significa que el valor de ETag enviado ya no es actual. Vuelve a leer el registro y decide si quieres repetir el cambio.
429 Too Many Requests significa que se ha superado el límite. Lee la cabecera Retry-After, si se devuelve, y reintenta después de ese tiempo con esperas progresivamente mayores.

Los errores utilizan el formato Problem Details. Los campos principales son status, code, detail y requestId. No uses el texto de detail como identificador estable del error: utiliza el campo code en la lógica de la aplicación.

Las respuestas también incluyen cabeceras de límites como X-RateLimit-Limit y X-RateLimit-Remaining. La integración debe controlar el ritmo de las solicitudes, reaccionar a 429 y evitar bucles agresivos de reintentos.

Artículos API para cada objeto

Después de crear la clave y comprobar la conexión, elige el artículo correspondiente a los datos que quieres integrar:

API - Activos - ordenadores, dispositivos, software y otros elementos del inventario, con sus campos, relaciones y archivos.
API - Documentos - documentos de la empresa, como facturas, sus datos descriptivos, archivos y relaciones.
API - Clientes / Empleados - datos de clientes o empleados, contactos, información organizativa y relaciones compatibles.
API - Proveedores - fichas de proveedores y las relaciones disponibles para este objeto, especialmente documentos y notas.
API - Tickets - tickets del Service Desk, ciclo de vida, campos operativos, archivos y relaciones.
API - Cambios - cambios planificados en el entorno de TI, etapas de ejecución y datos para controlar el proceso.
API - Problemas - problemas que requieren análisis de causa, gestión del proceso y vínculos con otros elementos.
API - Releases - planificación y gestión de releases, estados e información sobre los cambios desplegados.
API - Soluciones - artículos de la base de soluciones y sus relaciones con problemas.
API - Notas - notas, privacidad, fijación, archivos y relaciones con registros.
API - Aprobaciones - procesos de aprobación, datos de decisión, asignaciones y gestión del resultado.
API - Confirmaciones - confirmaciones que requieren una decisión del cliente, con sus archivos y relaciones.
API - Tareas - tareas de trabajo, asignaciones, estados, relaciones y archivos adjuntos.
API - Solicitudes - solicitudes de productos o servicios, datos de realización, archivos y relaciones.
API - Horas de trabajo - registros de tiempo relacionados con un ticket, cambio, problema, release o tarea.

Lista breve antes de poner la integración en producción

Crea una clave independiente para cada integración y concédele solo los ámbitos que necesita.
Guarda el Client ID y el Client Secret en un almacén de secretos, nunca en un repositorio ni en código enviado al navegador.
Define un periodo de actividad adecuado para la forma en que se administra la integración.
En producción utiliza HTTPS y una dirección de la empresa accesible para el servidor de integración.
Registra requestId, el estado HTTP y el código de error, pero oculta el Client Secret.
Gestiona la paginación, los límites, 429, ETag y los reintentos seguros.

Cuando hayas comprobado estos puntos, abre el artículo del objeto elegido. Allí encontrarás las rutas, los campos y los ejemplos de operaciones específicos de ese tipo de datos.