Proveedores en Codenica API

El nombre técnico de este recurso en la Public API es vendors y el tipo que devuelve la API es vendor. Una ficha de proveedor puede contener el nombre de la empresa, los datos de contacto, la información registral, el estado y una descripción de la relación comercial.

Antes de enviar la primera solicitud, prepara la clave descrita en Codenica API - introducción. El flujo siguiente cubre todo el trabajo: consultar el esquema y las listas, crear y editar un proveedor, gestionar los destinos de relación permitidos, trabajar con archivos, ejecutar operaciones por lotes y eliminar un registro.

  • leer listas de proveedores con paginación, ordenación y filtros;
  • solicitar únicamente los campos necesarios para la integración;
  • crear fichas de proveedores y aplicar actualizaciones parciales;
  • proteger los cambios con ETag y If-Match;
  • repetir las operaciones de escritura de forma segura con Idempotency-Key;
  • utilizar los destinos de relación que el esquema expone para Proveedores;
  • subir, descargar, adjuntar y eliminar archivos;
  • consultar estadísticas, valores de campos y procesar lotes.

Los campos obligatorios y los valores admitidos pueden depender de la configuración de tu base de datos. Consulta el esquema actual antes de escribir datos.

Proveedores - dirección de la API y tipo de instalación

Envía las solicitudes a la dirección pública donde está disponible tu instalación de Codenica. No utilices la dirección de la base de datos, de un contenedor ni de un puerto accesible solo dentro del servidor. Las rutas de Proveedores comienzan por:

{BASE_URL}/api/v1/vendors

En Codenica Cloud, utiliza el dominio asignado a tu instalación:

export BASE_URL="https://tu-empresa.codenica.com"

En la instalación On-Premise predeterminada, Codenica Discovery registra el servicio localmente en:

export BASE_URL="http://codenica.local:5150"

Si el administrador ha publicado la instalación On-Premise mediante un dominio corporativo, un proxy inverso, HTTPS u otro puerto externo, utiliza la dirección exacta que te hayan indicado:

export BASE_URL="https://api.tu-empresa.example"

La base de datos se selecciona a partir de la dirección del host. No la selecciones mediante tenantId, un parámetro adicional en la cadena de consulta ni un valor en el cuerpo de la solicitud. No uses localhost si el programa de integración se ejecuta en otro ordenador.

BASE_URL no debe incluir el sufijo final /api/v1:

# Codenica Cloud:
export BASE_URL="https://tu-empresa.codenica.com"

# On-Premise predeterminado con Codenica Discovery:
# export BASE_URL="http://codenica.local:5150"

# On-Premise con una dirección publicada por el administrador:
# export BASE_URL="https://api.tu-empresa.example"

Proveedores - clave de API y permisos de acceso

Crea la clave para una integración externa en Codenica, en Ajustes - API - Claves API. Asígnale un nombre que identifique la aplicación, el entorno y el propósito, por ejemplo Compras - Proveedores - producción. Selecciona solo los scopes que necesita la integración y guarda una sola vez el Client ID y el Client Secret mostrados en un almacén seguro de secretos.

El flujo completo de este artículo requiere:

  • vendors:read, vendors:write y vendors:delete - leer, crear, editar y eliminar registros;
  • vendors:schema - campos y destinos de relación;
  • vendors:stats - estadísticas y valores de campos;
  • vendors:relationships:read y vendors:relationships:write - leer y modificar relaciones;
  • vendors:files:read y vendors:files:write - operaciones con archivos.

Si la integración lee Documentos u otro destino de relación, añade también su permiso de lectura, por ejemplo documents:read. El scope de relaciones de Proveedores no sustituye el acceso al objeto de destino.

Para una integración de solo lectura normalmente bastan:

vendors:read
vendors:schema

Los límites de claves dependen de la licencia:

Licencia
Public API
Número máximo de claves
Starter
no disponible
0
Plus
disponible
50
Enterprise
disponible
100

El panel de API conserva las claves creadas para tu base de datos. Una clave separada para cada aplicación y entorno facilita controlar el acceso, rotar un secreto o eliminar una integración sin interrumpir las demás. Una clave eliminada ya no puede autenticar solicitudes y no se cuenta como activa.

El Client Secret solo se muestra al crear o rotar una clave. No lo guardes en un repositorio, una URL, los registros, el historial de comandos ni en código que se ejecute en el navegador.

Proveedores - cabeceras de autenticación

La aplicación externa envía solicitudes de servidor a servidor con dos cabeceras que identifican la clave:

export CLIENT_ID="cna_su_client_id"
export CLIENT_SECRET="cns_su_client_secret"

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

En este escenario no envíes un JWT de administrador ni las cookies del panel. La integración utiliza la clave de API asignada a esta base de datos y la instalación de producción debe utilizar HTTPS.

Toda operación que modifique datos necesita una cabecera única:

Idempotency-Key: public-api-vendors-create-20260905111218

Las actualizaciones, eliminaciones, cambios de relaciones y operaciones con archivos necesitan el ETag actual del registro:

If-Match: "etag-actual-del-proveedor"

Después de cada cambio correcto, guarda el nuevo ETag devuelto en la cabecera y en data.meta.etag. Al repetir la misma operación lógica, conserva el mismo Idempotency-Key y el cuerpo idéntico.

Proveedores - comprobar el contexto de la instalación

Lee el contexto antes de iniciar la sincronización:

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"

Comprueba apiVersion, contractVersion, el identificador de la base de datos, tenant.resolvedDomain, caller.authentication igual a api_key, los scopes necesarios y la presencia de vendors en capabilities.resources. Lee también los límites de páginas, archivos, lotes y solicitudes.

Una integración completa normalmente debe mostrar supportsBatch, supportsRelationships, supportsFiles, supportsETag y supportsIdempotency. Conserva meta.requestId de cada respuesta. Lo necesitarás para analizar un error o contactar con el administrador.

Si el contexto apunta a otra base de datos o falta un scope necesario, detén la sincronización y corrige la dirección o la clave. No intentes cambiar la base de datos en el cuerpo de la solicitud.

Proveedores - esquema de campos y destinos de relación

Lee el esquema antes de realizar la primera escritura:

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

En la respuesta, data.itemType tiene el valor vendor. El esquema describe el tipo de campo, si se puede leer o escribir, si es obligatorio, su longitud máxima, su unicidad y su generación automática. En el esquema actual, name es obligatorio y admite hasta 300 caracteres:

Campo
Tipo
Obligatorio
Límite
Significado de ejemplo
name
string
sí
300
nombre del proveedor

Los campos más utilizados pertenecen a varios grupos:

  • identificación: customId, name, displayName, type, category, role, status;
  • ubicación: location, department, address, city, country, state, zipCode;
  • contacto: email, phone, phoneWork, phoneMobile, contactName, contactPhone, contactMobile, contactEmail;
  • registros y etiquetas: website, tag, taxId, idNumber, registryNumber, link, number;
  • descripción y estado: comments, description, notification, value, isLicensed, isVerified.

El esquema también devuelve el catálogo de destinos de relación. En el modelo actual de Proveedores son documents, notes, worktasks y requesteditems. No supongas que todos los recursos visibles en el contexto pueden ser destinos de relación para un Proveedor.

Proveedores - mapa de endpoints

Este mapa agrupa las operaciones principales sobre las fichas de proveedores. Sustituye los valores entre llaves por los UUID que devuelvan las respuestas anteriores.

  • GET /api/v1/vendors - lista;
  • GET /api/v1/vendors/schema - esquema de campos y relaciones;
  • GET /api/v1/vendors/stats - estadísticas;
  • GET /api/v1/vendors/values - valores de campos;
  • GET /api/v1/vendors/{id} - ficha individual;
  • POST /api/v1/vendors - crear;
  • PATCH /api/v1/vendors/{id} - actualización parcial;
  • DELETE /api/v1/vendors/{id} - eliminar;
  • POST /api/v1/vendors:batch - operaciones de creación, actualización y eliminación;
  • GET /api/v1/vendors/{id}/relationships - lista de relaciones;
  • POST /api/v1/vendors/{id}/relationships - añadir una relación;
  • POST /api/v1/vendors/{id}/relationships:batch - cambiar varias relaciones en una solicitud;
  • DELETE /api/v1/vendors/{id}/relationships/{targetDataSet}/{targetId} - eliminar una relación;
  • GET /api/v1/vendors/{id}/files - lista de archivos;
  • POST /api/v1/vendors/{id}/files - subir un archivo;
  • POST /api/v1/vendors/{id}/files/{fileId} - adjuntar un archivo existente;
  • PUT /api/v1/vendors/{id}/files/{fileId}/main - establecer el archivo principal;
  • DELETE /api/v1/vendors/{id}/files/{fileId} - eliminar un archivo;
  • GET /api/v1/vendors/{id}/files/{fileId}/content - descargar el contenido.

Si un endpoint devuelve 403, comprueba primero el scope asignado a la clave y después los permisos de su propietario.

Proveedores - listas, ordenación y paginación

Lee la lista página a página. Este ejemplo devuelve las primeras veinte fichas y las ordena por nombre:

curl --request GET --url "$BASE_URL/api/v1/vendors?page=1&pageSize=20&sort=name&direction=asc" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

La envoltura de la colección contiene items, page, pageSize, totalItems, totalPages y hasNextPage. Cuando hasNextPage es true, lee la página siguiente. Para que la sincronización sea reproducible, establece siempre el orden de forma explícita.

Lee el límite de pageSize en el contexto. No supongas que la primera página contiene todos los registros ni que el orden predeterminado se mantendrá.

Proveedores - búsqueda y filtrado

Después de crear un registro, puedes encontrarlo por su identificador propio y su estado:

curl --request GET --url "$BASE_URL/api/v1/vendors?customId=PUBLIC-API-VEN-20260905111218-SOURCE&status=Active&sort=customId&direction=asc&page=1&pageSize=10" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Utiliza search para buscar texto:

curl --request GET --url "$BASE_URL/api/v1/vendors?search=technology&page=1&pageSize=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Según el esquema, puedes utilizar parámetros como ids, search, name, displayName, email, status, category, type, role, location, department, customId, tag, createdAfter, createdBefore, updatedAfter y updatedBefore.

Para condiciones más precisas, utiliza filter:

filter=status:eq:Active
filter=name:contains:Technology
filter=category:in:Technology,Hardware
filter=description:notEmpty:

Los operadores permiten comparar valores, buscar fragmentos de texto, escoger un valor entre varios y comprobar campos vacíos. Codifica los espacios y caracteres especiales según las reglas de las URL antes de enviar el filtro.

Proveedores - seleccionar campos e incluir datos

Utiliza fields para limitar la respuesta a las propiedades que necesita la integración:

curl --request GET --url "$BASE_URL/api/v1/vendors?fields=id,itemType,customId,displayName,email,status" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Utiliza include para leer archivos y relaciones junto con la ficha:

curl --request GET --url "$BASE_URL/api/v1/vendors/a8156781-3b1c-4fa5-9cf2-05077e5d1399?fields=customId,displayName,email,status,description&include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

La respuesta puede contener los atributos solicitados y las colecciones files y relationships. El acceso a los datos incluidos debe concederse por separado. La ausencia de vendors:files:read o vendors:relationships:read no se puede eludir con fields=*.

Proveedores - crear una ficha

Utiliza POST /api/v1/vendors para crear un registro. Coloca los campos que se pueden escribir dentro de attributes. La solicitud mínima requiere name, pero conviene enviar también el identificador del sistema de origen y los datos de contacto básicos:

{
  "attributes": {
    "customId": "ERP-VENDOR-2026-001",
    "name": "Northwind Technology Services",
    "displayName": "Northwind Technology Services",
    "email": "[email protected]",
    "category": "Technology",
    "type": "Supplier",
    "role": "Supplier",
    "status": "Active",
    "description": "Proveedor de servicios de infraestructura de TI."
  }
}
curl --request POST --url "$BASE_URL/api/v1/vendors" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-vendors-create-erp-vendor-2026-001" \
  --data @vendor-create.json

Una respuesta correcta tiene el estado 201 Created. Guarda data.id, data.meta.etag y la cabecera HTTP ETag. En la ficha de demostración, la API devolvió itemType: vendor y el identificador a8156781-3b1c-4fa5-9cf2-05077e5d1399.

Proveedores - repetir una creación de forma segura

Si se produce un tiempo de espera o se pierde la respuesta después de enviar la solicitud, no crees inmediatamente una segunda ficha. Repite exactamente la misma solicitud con la misma clave:

Idempotency-Key: public-api-vendors-create-erp-vendor-2026-001

El cuerpo debe ser idéntico y la clave debe pertenecer únicamente a esta operación lógica. Repetirla con la misma clave no creará un segundo Proveedor. No reutilices la clave para otra ficha, una actualización o una eliminación.

La idempotencia se aplica a las operaciones que modifican datos. Cada nueva escritura debe recibir una clave nueva y única.

Proveedores - leer una ficha

Después de crear o localizar un proveedor, léelo con el UUID devuelto por la API:

VENDOR_ID="a8156781-3b1c-4fa5-9cf2-05077e5d1399"

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

Una respuesta 200 OK contiene data.itemType: vendor; el ETag actual aparece en la cabecera HTTP y en data.meta.etag. No utilices el identificador del sistema de origen en lugar del UUID, salvo que primero hayas buscado el registro.

Proveedores - actualización parcial con ETag

Primero lee el registro y utiliza el ETag devuelto. PATCH solo cambia las propiedades enviadas en attributes:

CURRENT_ETAG='"ao_LJiJqs-uhBu9oDENCFJH6JY8qwbl_vt77Gl5cjGQ"'

curl --request PATCH --url "$BASE_URL/api/v1/vendors/$VENDOR_ID" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-update-20260905111218" \
  --data '{"attributes":{"displayName":"Northwind Technology Services - departamento de compras","description":"Datos del proveedor actualizados por la integración."}}'

Una respuesta correcta tiene el estado 200 OK. No envíes propiedades que no quieras modificar. Después de la operación sustituye el ETag guardado por el nuevo valor, por ejemplo "ek44P2KnmKSAB1xX4Ycs_NgIn0I3NLoDdqsezEUgBTY".

Proveedores - evitar sobrescribir cambios

Si dos procesos han leído la misma ficha, el segundo puede tener una versión antigua. La Public API rechaza esa actualización con el código if_match_failed y el estado 412 Precondition Failed:

{
  "type": "https://docs.codenica.com/errors/if_match_failed",
  "title": "Precondition failed.",
  "status": 412,
  "detail": "The supplied ETag is not the current vendor version.",
  "code": "if_match_failed"
}

Si falta If-Match al actualizar o eliminar, se devuelve 428 Precondition Required con el código if_match_required. Después de un 412 o 428, vuelve a leer el registro, revisa su estado actual y decide solo entonces si debes repetir el cambio. No envíes un ETag al azar.

Proveedores - catálogo limitado de relaciones

No todos los objetos disponibles en el sistema pueden ser destinos de relación de un Proveedor. La fuente de verdad es relationshipTargets, que devuelve /api/v1/vendors/schema. El modelo actual expone:

documents
notes
worktasks
requesteditems

No relaciones Proveedores con clients ni con assets. Tampoco deduzcas que se admite otra colección solo porque aparece en capabilities.resources. La lista general de recursos de la instalación es más amplia que los destinos de relación de un objeto concreto.

Las relaciones entre objetos de Proveedores no utilizan relationshipType. No lo envíes en el cuerpo ni añadas relationshipType=related a la cadena de consulta. Si un endpoint de archivos utiliza relationshipType=documentation o relationshipType=manual, ese valor es metadato del archivo y no representa una relación con otro objeto.

Proveedores - añadir y leer una relación

Lee un ETag reciente del Proveedor antes de cambiar una relación. El cuerpo contiene el destino, la colección y, cuando lo exige el objeto de destino, su targetItemType:

{
  "targetId": "31fe2881-6236-4100-9a87-2c018cbaf709",
  "targetDataSet": "documents",
  "targetItemType": "warranty"
}
curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-document-a-20260905111218" \
  --data '{"targetId":"31fe2881-6236-4100-9a87-2c018cbaf709","targetDataSet":"documents","targetItemType":"warranty"}'

La adición correcta devuelve 201 Created. Lee las relaciones por separado:

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships?targetDataSet=documents&page=1&pageSize=50" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

La respuesta incluye, entre otros, targetId, targetDataSet, targetItemType, customId y status. La lista de relaciones no contiene el parámetro relationshipType.

Proveedores - lotes de relaciones y eliminación de un vínculo

Utiliza relationships:batch para añadir o eliminar varias relaciones en una sola solicitud:

{
  "add": [
    {
      "targetId": "31eed973-79cf-4650-ac0e-1e3ef5513d9f",
      "targetDataSet": "documents",
      "targetItemType": "warranty"
    }
  ],
  "remove": []
}
curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-batch-20260905111218" \
  --data @vendor-relationships-batch.json

El resultado contiene los contadores added, removed y skipped. Elimina una relación con:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships/documents/31fe2881-6236-4100-9a87-2c018cbaf709" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-delete-20260905111218"

No añadas relationshipType. Vuelve a leer la colección después de la operación para confirmar el estado de la relación.

Proveedores - listar archivos

Los archivos forman una colección separada asociada a la ficha del Proveedor:

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files?page=1&pageSize=50" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Una colección vacía incluye valores como items: [], totalItems: 0 y hasNextPage: false. Después de cada operación con archivos, vuelve a leer la colección porque muestra los valores reales de isMain, relationshipType, el tamaño y la dirección de descarga.

Proveedores - subir un archivo

Lee el ETag actual del Proveedor antes de subir el archivo. La carga utiliza una solicitud multipart:

curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files?makeMain=true&relationshipType=documentation" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-upload-20260905111218" \
  --form "[email protected];type=text/plain"

Aquí relationshipType=documentation describe el archivo, no una relación entre objetos. La respuesta 201 Created incluye el identificador del archivo, su nombre, el tipo de contenido, el tamaño y downloadUrl. Confirma mediante la lista que el archivo tiene isMain: true.

Lee el límite de carga en data.capabilities.limits.maxUploadBytes. En la instalación de ejemplo era de 20971520 bytes.

Proveedores - descargar un archivo y cambiar el archivo principal

Descarga el contenido mediante downloadUrl o el endpoint equivalente:

FILE_ID="025222b9-abef-4bad-a2ba-28229a0d73fb"

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output vendors-primary-downloaded.txt

La respuesta debe contener 200 OK, el Content-Type correcto y la cabecera Content-Disposition. Para añadir un segundo archivo sin cambiar el principal, utiliza makeMain=false y, por ejemplo, relationshipType=manual. Después establécelo como principal:

curl --request PUT --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/cc182dea-47d3-4ca2-818b-c639cde5a124/main" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-set-main-20260905111218"

Después de volver a leer la lista, el archivo nuevo tiene isMain: true y el anterior isMain: false.

Proveedores - adjuntar un archivo existente

Puedes adjuntar a otra ficha un archivo almacenado con un Proveedor sin volver a subir su contenido. Es una operación con archivos, por lo que relationshipType es aquí un metadato del archivo:

TARGET_VENDOR_ID="4bfece8f-5bb3-438c-a95b-f14ccf93cce3"
TARGET_ETAG='"l5sRayy308rVRi4PNmUReFFcJGowi0KZUi8-hOGGlr0"'

curl --request POST --url "$BASE_URL/api/v1/vendors/$TARGET_VENDOR_ID/files/2a1f9727-0990-405d-b22c-fbd93273cc6e?makeMain=true&relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TARGET_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-attach-20260905111218"

Desvincularlo elimina la conexión de la ficha de destino, pero no elimina el archivo de la ficha propietaria:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$TARGET_VENDOR_ID/files/2a1f9727-0990-405d-b22c-fbd93273cc6e" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TARGET_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-detach-20260905111218"

Después de desvincularlo, comprueba la lista de archivos tanto del Proveedor de destino como del propietario.

Proveedores - eliminar un archivo

Eliminar un archivo también requiere el ETag actual de la ficha del Proveedor:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/cc182dea-47d3-4ca2-818b-c639cde5a124" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-delete-20260905111218"

Si eliminas el archivo principal actual, el sistema puede elegir automáticamente otro archivo restante como principal. Después de 200 OK, vuelve a leer la lista y comprueba totalItems e isMain. Desvincular un archivo no es lo mismo que eliminar el archivo del propietario.

Proveedores - estadísticas y valores de campos

Las estadísticas ayudan a comprobar cómo se distribuyen los datos entre las fichas de proveedores:

curl --request GET --url "$BASE_URL/api/v1/vendors/stats?field=status&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

El resultado puede contener el número total de registros, el nombre del campo y valores con sus contadores. Los valores proceden de tu base de datos. Por ejemplo, active, Active y proveedor activo pueden ser entradas distintas si proceden de fuentes diferentes.

Utiliza el endpoint values para crear sugerencias de filtros:

curl --request GET --url "$BASE_URL/api/v1/vendors/values?field=status&search=Act&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Las estadísticas y los valores son operaciones de solo lectura y no modifican los datos.

Proveedores - creación por lotes

Un lote permite crear varias fichas de proveedores en una sola solicitud. Cada elemento contiene operation: create y un objeto create:

{
  "items": [
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "ERP-VENDOR-BATCH-A",
          "name": "Northwind Batch A",
          "email": "[email protected]",
          "category": "Technology",
          "type": "Supplier",
          "role": "Supplier",
          "status": "Active"
        }
      }
    },
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "ERP-VENDOR-BATCH-B",
          "name": "Northwind Batch B",
          "email": "[email protected]",
          "category": "Technology",
          "type": "Supplier",
          "role": "Supplier",
          "status": "Active"
        }
      }
    }
  ]
}
curl --request POST --url "$BASE_URL/api/v1/vendors:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-vendors-batch-create-20260905111218" \
  --data @vendors-batch-create.json

El resultado contiene el estado de la solicitud completa y el estado de cada operación en data.items. Un lote correcto puede devolver 200 OK, succeeded: 2, failed: 0 y dos elementos con estado 201. Guarda cada UUID y ETag por separado.

Proveedores - actualización, eliminación y éxito parcial por lotes

Una actualización por lotes requiere id, el ifMatch actual y un objeto update:

{
  "items": [
    {
      "operation": "update",
      "id": "76d1698d-dfdb-47a3-9d84-3e476fa7894c",
      "ifMatch": "ETAG_FROM_GET",
      "update": {
        "attributes": {
          "displayName": "Northwind Batch A - actualización",
          "description": "Cambio realizado mediante la operación por lotes de Proveedores."
        }
      }
    },
    {
      "operation": "invalid"
    }
  ]
}

Si una operación es correcta y otra no es válida, la API devuelve 207 Multi-Status. No trates 207 como un fallo total ni como un éxito total. Procesa cada elemento de data.items por separado. Para eliminar se aplica la misma regla: envía el identificador y el ifMatch actual:

{
  "operation": "delete",
  "id": "9462d541-c405-44bf-9c75-000d8b862136",
  "ifMatch": "ETAG_FROM_GET"
}

Después de un borrado por lotes, realiza un GET de control. El registro eliminado debería devolver 404 con el código vendor_not_found.

Proveedores - eliminar una ficha

Vuelve a leer el registro antes de eliminarlo para disponer de un ETag actual:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-delete-20260905111218"

Una eliminación correcta devuelve 200 OK y data: true. Una lectura posterior devuelve 404 Not Found con el código vendor_not_found. También puedes filtrar por tu customId y confirmar totalItems: 0.

Si se pierde la respuesta DELETE, no envíes inmediatamente una operación nueva con otra clave. Conserva el Idempotency-Key original, comprueba el estado del registro y decide después cómo continuar.

Proveedores - errores, límites y recorrido completo de integración

Los errores de la Public API utilizan el formato Problem Details. Basa la lógica de la aplicación en el campo estable code y conserva requestId cuando informes de un problema.

  • 400 - campo, destino de relación o elemento de lote no válido;
  • 401 - credenciales ausentes o no válidas;
  • 403 - falta un scope o un permiso;
  • 404 - el registro, archivo o destino no existe o no es visible;
  • 409 - conflicto de datos o de unicidad;
  • 412 - ETag obsoleto;
  • 413 - el archivo supera el límite;
  • 422 - error de validación de negocio;
  • 428 - falta If-Match o Idempotency-Key;
  • 429 - se ha superado el límite de solicitudes;
  • 207 - el lote se ha ejecutado parcialmente.

Lee X-RateLimit-Limit y X-RateLimit-Remaining. Ante un 429, utiliza Retry-After cuando se devuelva y aumenta el intervalo entre intentos. No registres nunca X-Codenica-Client-Secret, secretos ni contenido sensible de archivos.

Orden recomendado:

  1. Establece BASE_URL con la instalación correcta.
  2. Crea una clave en Ajustes - API - Claves API con los permisos mínimos.
  3. Lee /api/v1/context y /api/v1/vendors/schema.
  4. Crea un Proveedor con un Idempotency-Key único y guarda su UUID y ETag.
  5. Lee las listas con paginación, filtros y include opcional.
  6. Actualiza el registro solo con el If-Match actual.
  7. Añade relaciones únicamente a destinos del esquema y sin relationshipType.
  8. Utiliza los endpoints específicos de archivos y comprueba la lista después de cada cambio.
  9. Para conjuntos grandes, revisa el resultado de cada operación por lotes.
  10. Lee el ETag actual antes de eliminar y realiza un GET de control después.

Los ejemplos utilizan el prefijo de demostración PUBLIC-API-VEN-20260905111218. Tu integración debe utilizar los identificadores devueltos por tu propia base de datos, no los valores mostrados en esta página.