Autenticación
Toda solicitud a la API lleva una clave de API. Una clave pertenece a una organización y solo puede leer los perfiles de cumplimiento de esa organización.
Crear una clave
- En la plataforma, abra Ajustes → Claves de API y cree una clave. Póngale un nombre para su propia referencia.
- Elija el ámbito: deje sin marcar «Permitir que esta clave envíe productos a la bandeja de entrada» para una clave de solo lectura, o márquela para una clave
read_write. - Si su organización tiene dos o más perfiles de cumplimiento, puede vincular la clave a uno de ellos.
- Copie la clave. Empieza por
cfa_live_y se muestra una sola vez: Conphora no puede volver a mostrarla. Si la pierde, revóquela y cree una nueva.
La lista de claves muestra los primeros caracteres de cada clave, su nombre, su ámbito, su vinculación a un perfil, cuándo se creó y cuándo se usó por última vez. Revocar una clave surte efecto de inmediato; la clave recibe entonces 401 revoked_api_key. Puede cambiar el nombre de una clave, pero no su ámbito ni su vinculación: cree una nueva en su lugar.
Enviar la clave
Envíe la clave en la cabecera x-api-key. También se acepta Authorization: Bearer <key>; si se envían ambas, prevalece x-api-key.
x-api-key: cfa_live_…
# or
Authorization: Bearer cfa_live_… Utilice la clave solo en su servidor, nunca en el JavaScript de una tienda o de un navegador. No se admite que los navegadores llamen directamente a la API.
Ámbitos
| Ámbito de la clave | Significado |
|---|---|
read | GET /api/v1/products y GET /api/v1/fields. Es el valor por defecto. |
read_write | Todo lo que puede llamar read, más POST /api/v1/intake. |
El ámbito queda fijado al crear la clave.
Vinculación a un perfil
- Una clave vinculada a un perfil solo puede nombrar ese perfil. Cualquier otro
profileIdrecibe403 profile_not_allowed. - Una clave sin vincular puede nombrar cualquier perfil de su organización. Un perfil que no existe, o que pertenece a otra organización, recibe
404 profile_not_found.
Dónde encontrar el id de su perfil
Todos los endpoints necesitan un profileId: el id de un perfil de cumplimiento en la plataforma. Ajustes → Claves de API muestra un ejemplo de solicitud que ya lo contiene. GET /api/v1/fields devuelve el id y el nombre del perfil, de modo que puede comprobar que es el correcto.
GET/api/v1/products
Consultar productos
Consulte de 1 a 100 productos por su propio identificador, por nombre o por código de barras, y obtenga su estado de cumplimiento, su Risk Score, la siguiente acción y el paquete para clientes. No existe ningún endpoint que liste un catálogo entero; para eso, utilice el feed de productos.
Ámbito de la clave: readPlan: todos los planes
Parámetros de consulta
| Parámetro | Tipo | Obligatorio | Valor por defecto | Significado |
|---|---|---|---|---|
profileId | string | sí | El perfil de cumplimiento en el que buscar. Debe pertenecer a la organización de la clave y coincidir con su vinculación si la clave está vinculada. | |
values | string (comma-separated or repeated) | sí | Los valores que consultar. Tanto values=A,B,C como values=A&values=B funcionan; utilice la forma repetida cuando un valor contenga una coma. Los valores se recortan, los vacíos se descartan y los duplicados exactos se descartan y se cuentan. Como máximo 100 una vez eliminados los duplicados. | |
value | string | alias | Se acepta como alias de values y se combina con él. | |
field | identifier | name | gtin | no | identifier | Qué son los valores: identifier = su propio identificador de producto (la columna que su importación asignó como identificador, como «SKU»), name = el nombre del producto, gtin = un código de barras EAN / UPC / GTIN. No distingue mayúsculas de minúsculas. No se aceptan otros nombres. |
includeArchived | true | no | false | Incluir los productos archivados. Sin este parámetro, las coincidencias archivadas se omiten y un resultado not_found informa de archivedMatchCount cuando han coincidido productos archivados. |
Cómo funciona la coincidencia
identifier: primero una coincidencia exacta y luego variantes tolerantes: se ignoran los ceros iniciales de los valores totalmente numéricos («0012345» encuentra «12345»), después la puntuación y después las mayúsculas. Los valores totalmente numéricos de más de 15 dígitos se rechazan comovalue_precision_unsupported. Un valor puede tener como máximo 512 caracteres.gtin: el código de barras se normaliza a la forma GS1 de 14 dígitos y se compara de forma exacta. Se admiten 8, 12, 13 y 14 dígitos y separadores; cualquier otra cosa esnot_a_gtin.name: primero el nombre exacto y después una búsqueda que ignora mayúsculas y puntuación.- Cuando coincide más de un producto, el resultado es
ambiguouscon los candidatos. La API nunca adivina: vuelva a preguntar con elidentifierde un candidato. - Con
field=identifier, un valor que todavía no es un producto pero que espera en la bandeja de entrada se devuelve comostaged.
Respuesta
La respuesta contiene results (uno por valor distinto, en el orden de la solicitud), summary y meta. Un valor que no se encuentra, es ambiguo o no es válido no es un error HTTP: se devuelve dentro del 200 como su propio resultado.
Resultados por estado
status | Campo | Significado |
|---|---|---|
found | value, matchedVia, product | Ha coincidido exactamente un producto. |
not_found | value, archivedMatchCount (only when > 0) | Sin coincidencias. |
staged | value, inbox { status: pending | dismissed, receivedAt } | Espera en la bandeja de entrada, todavía sin seguimiento, por lo que aún no hay estado de cumplimiento. |
ambiguous | value, matches [{ id, identifier, name }] | Han coincidido varios productos. |
ambiguous_truncated | value | La búsqueda alcanzó su límite de candidatos. Acote el valor o utilice identifier. No puede ocurrir con field=gtin. |
invalid_value | value, reason: empty_value | value_too_long | value_precision_unsupported | not_a_gtin | El valor no se puede consultar. |
matchedVia indica cómo coincidió un producto found: identifier_exact, identifier_numeric_zerostrip, identifier_numeric_roundtrip, identifier_alnum, identifier_normalized, name_exact, name_normalized, gtin_exact, gtin_canonical.
summary cuenta los resultados: requested, found, notFound, staged, ambiguous, invalid, duplicatesDropped. ambiguous incluye ambiguous_truncated; duplicatesDropped aparece solo cuando se han descartado valores.
meta contiene resolvedField (el campo utilizado), identifierField (cómo llamó su importación a la columna del identificador, a título informativo) y apiVersion.
El objeto de producto
Todas las claves están siempre presentes, en este orden. Las columnas de la hoja de cálculo importada nunca se devuelven por la API.
| Campo | Tipo | Significado |
|---|---|---|
id | string | El id estable del producto en Conphora. No es un valor de consulta. |
profileId | string | El perfil de cumplimiento. |
identifier | string | Su identificador de producto. |
identifierField | string | null | El nombre que da su importación a la columna del identificador. |
gtin | string | null | El código de barras en 14 dígitos, con ceros a la izquierda; null cuando la importación no tenía un código de barras válido. |
name | string | El nombre del producto. |
imageUrl | string | null | La URL de la imagen de su importación. |
hsCode | string | null | El código SA / código de mercancía. |
archived | boolean | True para un producto archivado. |
status.classification | in_progress | awaiting_clarification | completed | failed | null | En qué punto está la clasificación; null cuando no ha empezado. |
status.compliance | not_checked | compliant | requires_compliance | El estado de cumplimiento. Nunca es null: not_checked cuando el producto nunca se ha evaluado. |
compliance.lastCheckedAt | number (ms epoch) | null | Cuándo se evaluó el producto por última vez. |
compliance.summary.matchedCount | number | Cuántos requisitos se aplican. |
compliance.summary.fulfilledCount | number | Cuántos de ellos están cumplidos. |
compliance.progress | { compliance, attributes, documents }: { filled, total } | Pares rellenados / total para requisitos, datos de producto y documentos; {0, 0} cuando no hay ninguno. |
compliance.matchedRegulations[] | { id, shortName, fullTitle | null, eurLexUrl | null } | Los reglamentos que se aplican. |
compliance.missingRequirements[] | { key, kind, regulation, requirementId, domain | null, label, deferred } | Los requisitos abiertos. kind es doc, attr, symbol o checkpoint. deferred = marcado como «Todavía no tengo este dato»; sigue contando como pendiente. |
riskScore | integer 0–100 | null | El Risk Score de Conphora: una prioridad, no un veredicto. Null hasta que el producto se puntúa. |
riskBand | low | watch | high | critical | null | El nivel de la puntuación. Null cuando no hay puntuación. |
nextAction | object | null | Lo siguiente que hacer. Null cuando no hay puntuación o no hay nada que hacer. |
nextAction.kind | string (see the list below) | Qué hacer. |
nextAction.who | you | supplier | A quién le toca. |
nextAction.href | string (relative platform path) | Una ruta relativa en la plataforma que abre la acción. Ábrala en el host de la plataforma. |
nextAction.after | number | El Risk Score una vez realizada esta acción. |
customerPack | object | null | El paquete para clientes con los diez elementos y su estado: su vista de trabajo, la misma que en la página del producto. Se rellena en el plan de autoservicio; null en la comprobación gratuita y null cuando el perfil aún no tiene datos de empresa. |
customerPack.ready | integer 0–10 | Cuántos de los diez elementos están listos. |
customerPack.total | 10 | Siempre 10. |
customerPack.items | object: item id → ready | missing | waiting | not-needed | El estado de cada elemento, en el orden del paquete. not-needed = ninguna parte del elemento se aplica al producto. |
customerPack.url | string | null | El enlace completo a la página pública del paquete para clientes del producto: el enlace permanente propio del producto (el mismo que llevan la exportación y el feed). null cuando no existe, y en la comprobación gratuita. |
customerPack.path | string | null | El mismo enlace como ruta, /p/<token>, en el host de los documentos. |
createdAt | number (ms epoch) | Cuándo se creó el producto en Conphora. |
updatedAt | number (ms epoch) | Cuándo cambió el producto por última vez. |
Risk Score, nivel y siguiente acción
riskScore, riskBand y nextAction son iguales en todos los planes. La puntuación indica qué productos corregir primero; nunca califica un producto de conforme o no conforme. Un incumplimiento conocido sitúa el producto en critical sea cual sea la puntuación.
riskBand | Puntuación | Significado |
|---|---|---|
low | 0-24 | En seguimiento, nada que hacer |
watch | 25-49 | Se acerca algo |
high | 50-74 | Corregir este mes |
critical | 75-100 | Actuar ya |
nextAction.kind es uno de un conjunto fijo: clearNonCompliance, reEvaluate, uploadDocument, confirmRequirement, fillProductData, askSupplier, issueDeclaration, runProcedure, registerProduct, assembleTechnicalFile, renewDocument, reconfirmRuleChange, meetKeyDate, submitReport, chaseSupplier, reviewSupplierAnswer.
Elementos del paquete para clientes
Las claves de customerPack.items, en el orden del paquete. Cada estado es ready, missing, waiting o not-needed. identity, contact, declaration, standards-tests, safety-information, instructions, substances, packaging-epr, technical-file, recall-contact.
La API conserva los diez estados. La página pública del paquete que abre su cliente le muestra dos grupos: identity, contact, declaration, safety-information e instructions desde el principio, contados como «n de 5 listos para publicar»; standards-tests, substances, packaging-epr y recall-contact bajo petición, cada uno con un botón que se la pide a usted; technical-file no figura en la página.
Ejemplo de solicitud
curl "https://documents.conphora.com/api/v1/products?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c&field=identifier&values=NB-1042,NB-2210,NB-9999" \
-H "x-api-key: cfa_live_…" Ejemplo de respuesta
{
"results": [
{
"value": "NB-1042",
"status": "found",
"matchedVia": "identifier_exact",
"product": {
"id": "k57bq2x9w3m8r1t6v4c0n5p7ds",
"profileId": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
"identifier": "NB-1042",
"identifierField": "SKU",
"gtin": "05790000123452",
"name": "Birch stacking rings, 7 pieces",
"imageUrl": null,
"hsCode": "9503.00",
"archived": false,
"status": {
"classification": "completed",
"compliance": "requires_compliance"
},
"compliance": {
"lastCheckedAt": 1793260800000,
"summary": {
"matchedCount": 14,
"fulfilledCount": 9
},
"progress": {
"compliance": {
"filled": 9,
"total": 14
},
"attributes": {
"filled": 6,
"total": 8
},
"documents": {
"filled": 3,
"total": 5
}
},
"matchedRegulations": [
{
"id": "toy-safety",
"shortName": "TSR",
"fullTitle": "Toy Safety Regulation",
"eurLexUrl": null
},
{
"id": "gpsr",
"shortName": "GPSR",
"fullTitle": "General Product Safety Regulation",
"eurLexUrl": null
}
],
"missingRequirements": [
{
"key": "doc:TSR:eu-declaration-of-conformity",
"kind": "doc",
"regulation": "TSR",
"requirementId": "eu-declaration-of-conformity",
"domain": "documentation",
"label": "EU declaration of conformity",
"deferred": false
}
]
},
"riskScore": 58,
"riskBand": "high",
"nextAction": {
"kind": "issueDeclaration",
"who": "you",
"href": "/nordbirk/products/k57bq2x9w3m8r1t6v4c0n5p7ds?step=declaration",
"after": 41
},
"customerPack": {
"ready": 6,
"total": 10,
"items": {
"identity": "ready",
"contact": "ready",
"declaration": "missing",
"standards-tests": "ready",
"safety-information": "ready",
"instructions": "waiting",
"substances": "ready",
"packaging-epr": "missing",
"technical-file": "ready",
"recall-contact": "missing"
},
"url": null,
"path": null
},
"createdAt": 1790582400000,
"updatedAt": 1793260800000
}
},
{
"value": "NB-2210",
"status": "staged",
"inbox": {
"status": "pending",
"receivedAt": 1793174400000
}
},
{
"value": "NB-9999",
"status": "not_found"
}
],
"summary": {
"requested": 3,
"found": 1,
"notFound": 1,
"staged": 1,
"ambiguous": 0,
"invalid": 0
},
"meta": {
"resolvedField": "identifier",
"identifierField": "SKU",
"apiVersion": "2026-09-10"
}
} Errores
400 missing_parameter, 400 too_many_values, 400 unknown_field, 400 invalid_profile_id, 401 missing_api_key, 401 invalid_api_key, 401 revoked_api_key, 403 profile_not_allowed, 404 profile_not_found, 413 response_too_large, 429 rate_limited — Errores
GET/api/v1/fields
Descubrir campos
Muestra qué valores de `field` acepta la consulta y cómo llama la importación del perfil a su columna del identificador. Cualquier ámbito de clave; mismas reglas de perfil que más arriba.
Ámbito de la clave: readPlan: todos los planes
Parámetros de consulta
| Parámetro | Tipo | Obligatorio | Significado |
|---|---|---|---|
profileId | string | sí | El perfil de cumplimiento. |
Respuesta
| Campo | Tipo | Significado |
|---|---|---|
profile.id | string | El id del perfil. |
profile.name | string | El nombre del perfil. |
identifierField | string | null | Cómo llama la importación más reciente a la columna del identificador. |
supportedFields | string[] | Siempre ["identifier", "name", "gtin"]. |
meta.apiVersion | string | La versión de la API. |
Ejemplo de solicitud
curl "https://documents.conphora.com/api/v1/fields?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c" \
-H "x-api-key: cfa_live_…" Ejemplo de respuesta
{
"profile": {
"id": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
"name": "Nordbirk ApS"
},
"identifierField": "SKU",
"supportedFields": [
"identifier",
"name",
"gtin"
],
"meta": {
"apiVersion": "2026-09-10"
}
} Errores
400 missing_parameter, 400 invalid_profile_id, 401 missing_api_key, 401 invalid_api_key, 401 revoked_api_key, 403 profile_not_allowed, 404 profile_not_found, 429 rate_limited — Errores
POST/api/v1/intake
Enviar productos
Envíe hasta 100 productos por solicitud a la bandeja de entrada de un perfil. Los identificadores nuevos esperan en la bandeja de entrada hasta que alguien de su equipo los pasa a seguimiento; un producto cuyo identificador coincide con un producto existente actualiza ese producto en su sitio. El envío en sí no se factura, y volver a enviar el mismo producto no cambia nada.
Ámbito de la clave: read_writePlan: plan de autoservicio
Requiere una clave con el ámbito read_write (de lo contrario 403 insufficient_scope) y el plan de autoservicio (de lo contrario 403 membership_required). El cuerpo es JSON, de 1 MB como máximo.
Cuerpo de la solicitud
| Campo | Tipo | Obligatorio | Significado |
|---|---|---|---|
profileId | string | sí | El perfil de cumplimiento de destino. |
products | array (1–100) | sí | Los productos. Un duplicado posterior de un uniqueId se descarta (gana el primero) y se cuenta. |
products[].uniqueId | string | number | sí | Su identificador de producto, de 512 caracteres como máximo tras recortarlo. |
products[].name | string | sí | El nombre del producto (10.000 caracteres como máximo). |
products[].description | string | sí | La descripción del producto. La clasificación de Conphora la necesita. |
products[].gtin | string | number | no | El código de barras. Cuando está presente, debe ser un GTIN válido; de lo contrario la fila se rechaza con not_a_gtin. |
products[].imageUrl | string | no | Una URL de imagen. |
products[].attributes | object of string | number | boolean | null | no | Cualquier otra columna, como un objeto plano. Como máximo 300 claves de 200 caracteres como máximo; las cadenas largas se cortan a 10.000 caracteres; los valores anidados se rechazan. Una clave con el nombre de un campo de nivel superior se sobrescribe con el valor de nivel superior. |
products[].hints | object: category → attribute keys | no | Indica a la clasificación qué atributos describen qué. Cada clave debe existir en attributes y solo puede aparecer en una categoría. |
Categorías de pista: productDescription, material, productCategory, packaging, supplierInfo, other.
La bandeja de entrada de un perfil admite como máximo 50.000 filas en espera; un envío que lo supere recibe 429 intake_full.
Respuesta
results van en el orden de la solicitud, uno por producto: uniqueId, status y intakeId, productId o errors cuando corresponda.
Resultados por estado
status | Significado |
|---|---|
staged | Nuevo: ahora espera en la bandeja de entrada (intakeId). |
refreshed | Ya estaba esperando; se ha actualizado su contenido. |
resurfaced | Se había descartado de la bandeja de entrada y ha vuelto como pendiente porque su contenido cambió. |
unchanged | Ya conocido, y no ha cambiado nada. |
updated | Coincidió con un producto activo, que se ha actualizado (productId). |
updated_idle | Coincidió con un producto archivado, que se ha actualizado en su sitio y sigue archivado. |
invalid | La fila se ha rechazado: errors enumera { field, reason }. |
Motivos de invalid: required, invalid_type, too_long, not_a_gtin, too_many_attributes, unknown_category, reserved_key, unknown_attribute, assigned_twice.
summary cuenta los resultados: received, staged, refreshed, unchanged, updated, updatedIdle, archivedSkipped, invalid, duplicatesDropped. received cuenta los productos una vez descartados los duplicados; refreshed incluye resurfaced; archivedSkipped es siempre 0 y se conserva para clientes antiguos.
Si una solicitud falla a medias con 500 intake_failed, los productos anteriores al índice completed se guardaron y results los enumera; vuelva a enviar el resto.
Ejemplo de solicitud
curl -X POST "https://documents.conphora.com/api/v1/intake" \
-H "x-api-key: cfa_live_…" \
-H "Content-Type: application/json" \
-d '{
"profileId": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
"products": [
{
"uniqueId": "NB-3001",
"name": "Oak pull-along duck",
"description": "Wooden pull toy for children from 12 months, water-based paint.",
"gtin": "5790000123469",
"attributes": {
"Material": "Oak, water-based paint",
"Age": "12m+"
},
"hints": {
"material": [
"Material"
]
}
},
{
"uniqueId": "NB-3002",
"name": "Felt play mat"
}
]
}' Ejemplo de respuesta
{
"results": [
{
"uniqueId": "NB-3001",
"status": "staged",
"intakeId": "m12x7c4v9b2n8q5w3e6r1t0y4u"
},
{
"uniqueId": "NB-3002",
"status": "invalid",
"errors": [
{
"field": "description",
"reason": "required"
}
]
}
],
"summary": {
"received": 2,
"staged": 1,
"refreshed": 0,
"unchanged": 0,
"updated": 0,
"updatedIdle": 0,
"archivedSkipped": 0,
"invalid": 1
},
"meta": {
"apiVersion": "2026-09-10"
}
} Errores
400 missing_parameter, 400 invalid_profile_id, 400 invalid_json, 400 invalid_payload, 400 too_many_products, 401 missing_api_key, 401 invalid_api_key, 401 revoked_api_key, 403 insufficient_scope, 403 profile_not_allowed, 403 membership_required, 404 profile_not_found, 413 payload_too_large, 429 rate_limited, 429 intake_full, 500 intake_failed, 503 rate_limiter_unavailable — Errores
GET/feed/{token}
Feed de productos
Un feed de productos es una URL fija que sirve siempre los datos más recientes de los productos activos de un perfil de cumplimiento, en JSON, CSV o Excel. No necesita clave de API: el token de la URL es la credencial, de modo que cualquiera que tenga la URL puede leer el feed hasta que usted la revoque.
Crear y revocar un enlace de feed
- En la plataforma, abra Tablas, elija «Feed» en la barra de herramientas y cree un enlace. El enlace toma las columnas visibles en la tabla en ese momento; más tarde puede cambiar sus columnas y ponerle una etiqueta.
- Cada enlace tiene botones de copia para CSV, XLSX y JSON.
- Revocar un enlace surte efecto de inmediato: la siguiente solicitud recibe
404.
Los enlaces de feed están disponibles en todos los planes. Las dos columnas del paquete para clientes solo se rellenan en el plan de autoservicio.
Parámetros de consulta
| Parámetro | Significado |
|---|---|
format | El formato de salida: json (por defecto), csv o xlsx. |
shared | Conserve solo los productos que tienen un enlace de paquete para clientes abierto con esta etiqueta (el nombre de su cliente, sin distinguir mayúsculas de minúsculas) y dirija la «Customer pack URL» de cada fila a ese enlace compartido en lugar del enlace permanente del producto. Así se ofrece a un cliente un paquete a nivel de catálogo. Vacío en la comprobación gratuita, que no tiene enlaces compartidos. |
Formatos
format | Significado |
|---|---|
json | Una matriz de objetos, una clave por nombre de columna. Las columnas estructuradas son matrices y objetos, las fechas son ISO 8601 y los valores que faltan son null. |
csv | UTF-8 con una fila de encabezado con los nombres de las columnas, separado por comas. Las celdas con varios valores se unen con saltos de línea. |
xlsx | Una hoja con las mismas celdas que el CSV. |
Columnas
Un enlace sirve las columnas elegidas para él, en este orden: primero sus propias columnas importadas con sus propios nombres (identificador, nombre y el resto), a diferencia de la API, el feed sí incluye sus datos importados, y después las columnas de Conphora:
| Columna | Significado |
|---|---|
EAN / GTIN | El código de barras de 14 dígitos. |
Commodity Code | El código SA. |
Matched Regulations | Los nombres cortos de los reglamentos que se aplican. |
Markets | Los mercados, con código y nombre del país. |
EN Standards | Las normas recomendadas (en la plataforma se muestran como «Recommended Standards»; el feed conserva este nombre). |
Tested for | Para qué muestran sus documentos que se ensayó el producto. |
Attributes | Los datos del producto, etiqueta, valor y unidad. |
Attributes on Product | Los atributos que van en el producto. |
Attributes on Packaging | Los atributos que van en el envase. |
Attributes in Documentation | Los atributos que van en la documentación. |
Attributes in Online Listing | Los atributos que van en la ficha en línea. |
Document Links | Una entrada por documento: título, tipo, ámbitos de cumplimiento y un enlace al documento. |
Customer pack | «6 de 10 listos» y el estado de cada uno de los diez elementos (el feed conserva los diez; la página del paquete muestra cinco desde el principio y cuatro bajo petición) (en JSON: { ready, total, items }). Vacío, o null en JSON, en la comprobación gratuita. |
Customer pack URL | El enlace a la página del paquete para clientes del producto: el enlace permanente propio del producto o el enlace compartido del cliente shared cuando se filtra. Vacío en la comprobación gratuita. |
Created | Cuándo se creó el producto. |
Updated | Cuándo cambió el producto por última vez. |
El feed no tiene columna de estado de cumplimiento, de Risk Score ni de siguiente acción; esas están en la API. El feed no tiene número de versión: los nombres de sus columnas son su contrato, y los nombres de sus columnas importadas siguen a sus importaciones.
Ejemplo de solicitud
curl "https://documents.conphora.com/feed/<your-feed-token>?format=json" Ejemplo de respuesta
[
{
"SKU": "NB-1042",
"Product name": "Birch stacking rings, 7 pieces",
"Colour": "Natural",
"EAN / GTIN": "05790000123452",
"Commodity Code": "9503.00",
"Matched Regulations": [
"TSR",
"GPSR"
],
"Markets": [
{
"countryCode": "DK",
"name": "Denmark"
},
{
"countryCode": "SE",
"name": "Sweden"
}
],
"Customer pack": {
"ready": 6,
"total": 10,
"items": {
"identity": "ready",
"contact": "ready",
"declaration": "missing",
"standards-tests": "ready",
"safety-information": "ready",
"instructions": "waiting",
"substances": "ready",
"packaging-epr": "missing",
"technical-file": "ready",
"recall-contact": "missing"
}
},
"Customer pack URL": null,
"Created": "2026-09-29T08:00:00.000Z",
"Updated": "2026-10-29T08:00:00.000Z"
}
] Los errores del feed son texto plano, no JSON: 404 cuando el enlace no es válido o está revocado, 413 cuando la exportación sería demasiado grande (CSV es el formato más compacto).
Límites de frecuencia
Las lecturas y las escrituras tienen límites distintos, cada uno contado por clave de API y por organización (todas las claves juntas). Una solicitud debe cumplir ambos. Las cifras son los valores de hoy, fijados para detener scripts descontrolados, no para frenar el uso normal.
| Solicitudes | Contado por | Frecuencia | Ráfaga |
|---|---|---|---|
GET /api/v1/products, GET /api/v1/fields | clave de API | 600 / minuto | 120 |
GET /api/v1/products, GET /api/v1/fields | organización | 3,000 / minuto | 500 |
POST /api/v1/intake | clave de API | 120 / minuto | 30 |
POST /api/v1/intake | organización | 600 / minuto | 100 |
Superado el límite, la API responde 429 con el error rate_limited, un campo retryAfterMs y una cabecera Retry-After en segundos (al menos 1). Espere ese tiempo antes de reintentar.
HTTP/1.1 429 Too Many Requests
Retry-After: 2
{
"error": "rate_limited",
"message": "Too many requests. Slow down and retry.",
"retryAfterMs": 1800
} Errores
Todo error de un endpoint `/api/v1` es JSON con la forma `{ "error": "<code>", "message": "<text>" }`, a veces con campos adicionales, enviado con el estado HTTP. Ramifique según `error`, nunca según `message`. Un método incorrecto o una ruta desconocida no es uno de estos endpoints y no responde con esta forma.
| Estado | error | Cuándo | Campos adicionales | Endpoints |
|---|---|---|---|---|
| 400 | missing_parameter | Falta profileId, faltan valores, o falta products / hay una matriz vacía. | todos | |
| 400 | too_many_values | Más de 100 valores distintos. | maxValues | GET /api/v1/products |
| 400 | unknown_field | field no es identifier, name ni gtin. | supportedFields | GET /api/v1/products |
| 400 | invalid_profile_id | profileId no es un id bien formado. | todos | |
| 400 | invalid_json | El cuerpo no es JSON. | POST /api/v1/intake | |
| 400 | invalid_payload | El cuerpo no es un objeto, o products no es una matriz. | POST /api/v1/intake | |
| 400 | too_many_products | Más de 100 productos. | maxProducts | POST /api/v1/intake |
| 401 | missing_api_key | No se ha enviado ninguna clave. | todos | |
| 401 | invalid_api_key | La clave es desconocida. | todos | |
| 401 | revoked_api_key | La clave se ha revocado. | todos | |
| 403 | insufficient_scope | Una clave read ha llamado a intake. | POST /api/v1/intake | |
| 403 | profile_not_allowed | La clave está vinculada a otro perfil. | todos | |
| 403 | membership_required | La organización no tiene un plan de autoservicio activo. | POST /api/v1/intake | |
| 404 | profile_not_found | El perfil no existe o pertenece a otra organización. | todos | |
| 413 | response_too_large | El resultado superaría unos 18 MB. Pida menos valores. | GET /api/v1/products | |
| 413 | payload_too_large | El cuerpo supera 1 MB. | maxBodyBytes | POST /api/v1/intake |
| 429 | rate_limited | Se ha alcanzado un límite de frecuencia. | retryAfterMs + Retry-After header | todos |
| 429 | intake_full | La bandeja de entrada del perfil superaría las 50.000 filas en espera. | POST /api/v1/intake | |
| 500 | intake_failed | La solicitud falló a medias; los productos anteriores al índice completed se guardaron. | completed, results | POST /api/v1/intake |
| 503 | rate_limiter_unavailable | Las escrituras no están disponibles momentáneamente. Reintente tras el tiempo de la cabecera Retry-After. | Retry-After header | POST /api/v1/intake |
Versiones
- La versión figura en la ruta (
/api/v1) y en el cuerpo de cada respuesta comometa.apiVersion. - Se pueden añadir campos en cualquier momento. Construya clientes que ignoren los campos que no conocen.
- Un cambio incompatible cambia la versión.
meta.apiVersion: "2026-09-10"