Autenticação
Cada pedido à API leva uma chave de API. Uma chave pertence a uma organização e só pode ler os perfis de conformidade dessa organização.
Criar uma chave
- Na plataforma, abra Settings → API Keys e crie uma chave. Dê-lhe um nome para futura referência.
- Escolha o âmbito: deixe a opção «Allow this key to push products into the Inbox» desmarcada para uma chave só de leitura e marque-a para uma chave
read_write. - Se a sua organização tiver dois ou mais perfis de conformidade, pode associar a chave a um deles.
- Copie a chave. Começa por
cfa_live_e é apresentada uma única vez: a Conphora não a pode mostrar de novo. Se a perder, revogue-a e crie uma nova.
A lista de chaves mostra os primeiros carateres de cada chave, o nome, o âmbito, a associação a um perfil, a data de criação e a data da última utilização. A revogação de uma chave produz efeitos imediatos; a chave passa então a receber 401 revoked_api_key. Pode mudar o nome de uma chave, mas não o seu âmbito nem a associação, crie antes uma nova chave.
Enviar a chave
Envie a chave no cabeçalho x-api-key. Authorization: Bearer <key> também é aceite; quando ambos são enviados, prevalece x-api-key.
x-api-key: cfa_live_…
# or
Authorization: Bearer cfa_live_… Utilize a chave apenas no seu servidor, nunca em JavaScript de loja ou de navegador. Não é suportada a chamada direta da API por navegadores.
Âmbitos
| Âmbito da chave | Significado |
|---|---|
read | GET /api/v1/products e GET /api/v1/fields. É o âmbito predefinido. |
read_write | Tudo o que read pode chamar, mais POST /api/v1/intake. |
O âmbito fica definido quando a chave é criada.
Associação a um perfil
- Uma chave associada a um perfil só pode indicar esse perfil. Qualquer outro
profileIdrecebe403 profile_not_allowed. - Uma chave sem associação pode indicar qualquer perfil da sua organização. Um perfil que não existe, ou que pertence a outra organização, recebe
404 profile_not_found.
Onde encontrar o id do seu perfil
Todos os endpoints exigem um profileId: o id de um perfil de conformidade na plataforma. Settings → API Keys mostra um exemplo de pedido que já o contém. GET /api/v1/fields devolve o id e o nome do perfil, para que possa confirmar que tem o correto.
GET/api/v1/products
Consultar produtos
Consulte de 1 a 100 produtos pelo seu próprio identificador, pelo nome ou pelo código de barras e obtenha o respetivo estado de conformidade, Risk Score, ação seguinte e pacote do cliente. Não existe nenhum endpoint que liste um catálogo inteiro; para isso, utilize o feed de produtos.
Âmbito da chave: readPlano: todos os planos
Parâmetros de consulta
| Parâmetro | Tipo | Obrigatório | Predefinição | Significado |
|---|---|---|---|---|
profileId | string | sim | O perfil de conformidade onde pesquisar. Tem de pertencer à organização da chave e corresponder à associação da chave, se esta estiver associada. | |
values | string (comma-separated or repeated) | sim | Os valores a consultar. values=A,B,C e values=A&values=B funcionam ambos; utilize a forma repetida quando um valor contiver uma vírgula. Os valores são aparados, os brancos são descartados e os duplicados exatos são descartados e contados. No máximo 100, depois de removidos os duplicados. | |
value | string | alias | Aceite como alias de values e fundido com este. | |
field | identifier | name | gtin | não | identifier | O que são os valores: identifier = o seu identificador de produto (a coluna que a sua importação mapeou como identificador, como «SKU»), name = o nome do produto, gtin = um código de barras EAN / UPC / GTIN. Sem distinção entre maiúsculas e minúsculas. Não são aceites outros nomes. |
includeArchived | true | não | false | Inclui os produtos arquivados. Sem este parâmetro, as correspondências arquivadas são omitidas e um resultado not_found indica archivedMatchCount quando houve correspondência com produtos arquivados. |
Como funciona a correspondência
identifier: primeiro uma correspondência exata, depois variantes tolerantes, os zeros à esquerda de valores só com algarismos são ignorados («0012345» encontra «12345»), depois a pontuação, depois as maiúsculas. Os valores só com algarismos e com mais de 15 algarismos são recusados comovalue_precision_unsupported. Um valor pode ter no máximo 512 carateres.gtin: o código de barras é normalizado para a forma GS1 de 14 algarismos e comparado de forma exata. Aceitam-se 8, 12, 13 e 14 algarismos e separadores; qualquer outra coisa énot_a_gtin.name: primeiro o nome exato, depois uma pesquisa que ignora maiúsculas e pontuação.- Quando mais de um produto corresponde, o resultado é
ambiguouscom os candidatos. A API nunca adivinha: volte a perguntar com oidentifierde um candidato. - Com
field=identifier, um valor que ainda não é um produto mas está à espera na Inbox é devolvido comostaged.
Resposta
A resposta tem results (um por valor distinto, pela ordem do pedido), summary e meta. Um valor não encontrado, ambíguo ou inválido não é um erro HTTP: é devolvido dentro do 200 como resultado próprio.
Resultados por estado
status | Campo | Significado |
|---|---|---|
found | value, matchedVia, product | Correspondeu exatamente um produto. |
not_found | value, archivedMatchCount (only when > 0) | Sem correspondência. |
staged | value, inbox { status: pending | dismissed, receivedAt } | À espera na Inbox, ainda não acompanhado, pelo que ainda não há estado de conformidade. |
ambiguous | value, matches [{ id, identifier, name }] | Corresponderam vários produtos. |
ambiguous_truncated | value | A pesquisa atingiu o seu limite de candidatos. Restrinja o valor ou utilize identifier. Não pode acontecer com field=gtin. |
invalid_value | value, reason: empty_value | value_too_long | value_precision_unsupported | not_a_gtin | O valor não pode ser consultado. |
matchedVia indica como um produto found correspondeu: identifier_exact, identifier_numeric_zerostrip, identifier_numeric_roundtrip, identifier_alnum, identifier_normalized, name_exact, name_normalized, gtin_exact, gtin_canonical.
summary conta os resultados: requested, found, notFound, staged, ambiguous, invalid, duplicatesDropped. ambiguous inclui ambiguous_truncated; duplicatesDropped só aparece quando foram descartados valores.
meta contém resolvedField (o campo utilizado), identifierField (como a sua importação designou a coluna do identificador, a título informativo) e apiVersion.
O objeto produto
Todas as chaves estão sempre presentes, por esta ordem. As colunas da sua folha de cálculo importada nunca são devolvidas pela API.
| Campo | Tipo | Significado |
|---|---|---|
id | string | O id estável do produto na Conphora. Não é um valor de consulta. |
profileId | string | O perfil de conformidade. |
identifier | string | O seu identificador de produto. |
identifierField | string | null | O nome que a sua importação dá à coluna do identificador. |
gtin | string | null | O código de barras com 14 algarismos, preenchido com zeros; null quando a importação não tinha um código de barras válido. |
name | string | O nome do produto. |
imageUrl | string | null | O URL da imagem da sua importação. |
hsCode | string | null | O código SH / código de mercadoria. |
archived | boolean | Verdadeiro para um produto arquivado. |
status.classification | in_progress | awaiting_clarification | completed | failed | null | Em que ponto está a classificação; null quando não começou. |
status.compliance | not_checked | compliant | requires_compliance | O estado de conformidade. Nunca null: not_checked quando o produto nunca foi avaliado. |
compliance.lastCheckedAt | number (ms epoch) | null | Quando o produto foi avaliado pela última vez. |
compliance.summary.matchedCount | number | Quantos requisitos se aplicam. |
compliance.summary.fulfilledCount | number | Quantos destes estão cumpridos. |
compliance.progress | { compliance, attributes, documents }: { filled, total } | Pares preenchidos / total para requisitos, dados do produto e documentos; {0, 0} quando não há nenhum. |
compliance.matchedRegulations[] | { id, shortName, fullTitle | null, eurLexUrl | null } | Os regulamentos aplicáveis. |
compliance.missingRequirements[] | { key, kind, regulation, requirementId, domain | null, label, deferred } | Os requisitos em aberto. kind é doc, attr, symbol ou checkpoint. deferred = marcado como «I don't have this data yet»; continua a contar como em falta. |
riskScore | integer 0–100 | null | O Conphora Risk Score: uma prioridade, não um veredicto. Null até o produto ser pontuado. |
riskBand | low | watch | high | critical | null | A classe da pontuação. Null quando não há pontuação. |
nextAction | object | null | A única coisa a fazer a seguir. Null quando não há pontuação ou nada a fazer. |
nextAction.kind | string (see the list below) | O que fazer. |
nextAction.who | you | supplier | A quem cabe agir. |
nextAction.href | string (relative platform path) | Um caminho relativo na plataforma que abre a ação. Abra-o no domínio da plataforma. |
nextAction.after | number | O Risk Score depois de esta ação ser concluída. |
customerPack | object | null | O pacote do cliente com os dez itens e o respetivo estado, a sua vista de trabalho, igual à da página do produto. Preenchido no plano de autosserviço; null na verificação gratuita e null quando o perfil ainda não tem dados da empresa. |
customerPack.ready | integer 0–10 | Quantos dos dez itens estão prontos. |
customerPack.total | 10 | Sempre 10. |
customerPack.items | object: item id → ready | missing | waiting | not-needed | O estado de cada item, pela ordem do pacote. not-needed = nenhuma parte do item se aplica ao produto. |
customerPack.url | string | null | A ligação completa para a página pública do pacote do cliente do produto: a ligação permanente do próprio produto (a mesma que a exportação e o feed contêm). null quando não existe e na verificação gratuita. |
customerPack.path | string | null | A mesma ligação como caminho, /p/<token>, no domínio de documentos. |
createdAt | number (ms epoch) | Quando o produto foi criado na Conphora. |
updatedAt | number (ms epoch) | Quando o produto foi alterado pela última vez. |
Risk Score, classe e ação seguinte
riskScore, riskBand e nextAction são iguais em todos os planos. A pontuação diz que produtos corrigir primeiro; nunca classifica um produto como conforme ou não conforme. Uma não conformidade conhecida coloca o produto em critical, seja qual for a pontuação.
riskBand | Pontuação | Significado |
|---|---|---|
low | 0-24 | Monitorizado, nada a fazer |
watch | 25-49 | Algo se aproxima |
high | 50-74 | Corrigir este mês |
critical | 75-100 | Agir já |
nextAction.kind é um de um conjunto fixo: clearNonCompliance, reEvaluate, uploadDocument, confirmRequirement, fillProductData, askSupplier, issueDeclaration, runProcedure, registerProduct, assembleTechnicalFile, renewDocument, reconfirmRuleChange, meetKeyDate, submitReport, chaseSupplier, reviewSupplierAnswer.
Itens do pacote do cliente
As chaves de customerPack.items, pela ordem do pacote. Cada estado é ready, missing, waiting ou not-needed. identity, contact, declaration, standards-tests, safety-information, instructions, substances, packaging-epr, technical-file, recall-contact.
A API mantém os dez estados. A página pública do pacote que o seu cliente abre mostra ao seu cliente dois grupos: identity, contact, declaration, safety-information e instructions desde o início, contados como «n of 5 ready to list»; standards-tests, substances, packaging-epr e recall-contact a pedido, cada um com um botão que lhe faz esse pedido; technical-file não consta da página.
Exemplo de pedido
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_…" Exemplo de resposta
{
"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"
}
} Erros
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 — Erros
GET/api/v1/fields
Descobrir campos
Mostra que valores de `field` a consulta aceita e como a importação do perfil designa a coluna do identificador. Qualquer âmbito de chave; as mesmas regras de perfil que acima.
Âmbito da chave: readPlano: todos os planos
Parâmetros de consulta
| Parâmetro | Tipo | Obrigatório | Significado |
|---|---|---|---|
profileId | string | sim | O perfil de conformidade. |
Resposta
| Campo | Tipo | Significado |
|---|---|---|
profile.id | string | O id do perfil. |
profile.name | string | O nome do perfil. |
identifierField | string | null | Como a importação mais recente designa a coluna do identificador. |
supportedFields | string[] | Sempre ["identifier", "name", "gtin"]. |
meta.apiVersion | string | A versão da API. |
Exemplo de pedido
curl "https://documents.conphora.com/api/v1/fields?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c" \
-H "x-api-key: cfa_live_…" Exemplo de resposta
{
"profile": {
"id": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
"name": "Nordbirk ApS"
},
"identifierField": "SKU",
"supportedFields": [
"identifier",
"name",
"gtin"
],
"meta": {
"apiVersion": "2026-09-10"
}
} Erros
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 — Erros
POST/api/v1/intake
Enviar produtos
Envie até 100 produtos por pedido para a Inbox de um perfil. Os identificadores novos ficam à espera na Inbox até alguém da sua equipa os passar para acompanhamento; um produto cujo identificador corresponde a um produto existente atualiza esse produto no local. O envio em si não é faturado, e enviar de novo o mesmo produto não altera nada.
Âmbito da chave: read_writePlano: plano de autosserviço
Exige uma chave com o âmbito read_write (caso contrário, 403 insufficient_scope) e o plano de autosserviço (caso contrário, 403 membership_required). O corpo é JSON, com 1 MB no máximo.
Corpo do pedido
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
profileId | string | sim | O perfil de conformidade de destino. |
products | array (1–100) | sim | Os produtos. Um duplicado posterior de um uniqueId é descartado (prevalece o primeiro) e contado. |
products[].uniqueId | string | number | sim | O seu identificador de produto, com 512 carateres no máximo depois de aparado. |
products[].name | string | sim | O nome do produto (10 000 carateres no máximo). |
products[].description | string | sim | A descrição do produto. A classificação da Conphora precisa dela. |
products[].gtin | string | number | não | O código de barras. Quando presente, tem de ser um GTIN válido, ou a linha é rejeitada com not_a_gtin. |
products[].imageUrl | string | não | Um URL de imagem. |
products[].attributes | object of string | number | boolean | null | não | Quaisquer outras colunas, como objeto plano. No máximo 300 chaves de 200 carateres no máximo; as cadeias longas são cortadas aos 10 000 carateres; os valores aninhados são rejeitados. Uma chave com o nome de um campo de nível superior é substituída pelo valor de nível superior. |
products[].hints | object: category → attribute keys | não | Indica à classificação que atributos descrevem o quê. Todas as chaves têm de existir em attributes e só podem constar de uma categoria. |
Categorias de indicações: productDescription, material, productCategory, packaging, supplierInfo, other.
A Inbox de um perfil comporta no máximo 50 000 linhas em espera; um envio que ultrapasse esse limite recebe 429 intake_full.
Resposta
results seguem a ordem do pedido, um por produto: uniqueId, status e intakeId, productId ou errors quando aplicável.
Resultados por estado
status | Significado |
|---|---|
staged | Novo: agora à espera na Inbox (intakeId). |
refreshed | Já estava à espera; o seu conteúdo foi atualizado. |
resurfaced | Tinha sido dispensado da Inbox e voltou como pendente porque o seu conteúdo mudou. |
unchanged | Já conhecido e nada mudou. |
updated | Correspondeu a um produto ativo, que foi atualizado (productId). |
updated_idle | Correspondeu a um produto arquivado, que foi atualizado no local e continua arquivado. |
invalid | A linha foi rejeitada: errors lista { 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 conta os resultados: received, staged, refreshed, unchanged, updated, updatedIdle, archivedSkipped, invalid, duplicatesDropped. received conta os produtos depois de descartados os duplicados; refreshed inclui resurfaced; archivedSkipped é sempre 0 e mantém-se para clientes mais antigos.
Se um pedido falhar a meio com 500 intake_failed, os produtos anteriores ao índice completed foram guardados e results lista-os; envie o resto de novo.
Exemplo de pedido
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"
}
]
}' Exemplo de resposta
{
"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"
}
} Erros
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 — Erros
GET/feed/{token}
Feed de produtos
Um feed de produtos é um URL fixo que serve sempre os dados mais recentes dos produtos ativos de um perfil de conformidade, em JSON, CSV ou Excel. Não precisa de chave de API: o token no URL é a credencial, pelo que quem tiver o URL pode ler o feed até o revogar.
Criar e revogar uma ligação de feed
- Na plataforma, abra Tables, escolha «Feed» na barra de ferramentas e crie uma ligação. A ligação assume as colunas visíveis na tabela nesse momento; pode alterar as suas colunas e atribuir-lhe uma etiqueta mais tarde.
- Cada ligação tem botões de cópia para CSV, XLSX e JSON.
- A revogação de uma ligação produz efeitos imediatos: o pedido seguinte recebe
404.
As ligações de feed estão disponíveis em todos os planos. As duas colunas do pacote do cliente só são preenchidas no plano de autosserviço.
Parâmetros de consulta
| Parâmetro | Significado |
|---|---|
format | O formato de saída: json (predefinido), csv ou xlsx. |
shared | Mantém apenas os produtos que têm uma ligação de partilha de pacote do cliente aberta com esta etiqueta (o nome do seu cliente, sem distinção entre maiúsculas e minúsculas) e aponta o «Customer pack URL» de cada linha para essa partilha, em vez da ligação permanente do produto. Isto dá a um cliente um pacote ao nível do catálogo. Vazio na verificação gratuita, que não tem ligações de partilha. |
Formatos
format | Significado |
|---|---|
json | Uma matriz de objetos, com uma chave por nome de coluna. As colunas estruturadas são matrizes e objetos, as datas seguem a ISO 8601 e os valores em falta são null. |
csv | UTF-8 com uma linha de cabeçalho com os nomes das colunas, separado por vírgulas. As células com vários valores são unidas com quebras de linha. |
xlsx | Uma folha com as mesmas células que o CSV. |
Colunas
Uma ligação serve as colunas escolhidas para ela, por esta ordem: primeiro as suas próprias colunas importadas, com os seus próprios nomes (identificador, nome, depois as restantes), ao contrário da API, o feed inclui os seus dados importados, e depois as colunas da Conphora:
| Coluna | Significado |
|---|---|
EAN / GTIN | O código de barras de 14 algarismos. |
Commodity Code | O código SH. |
Matched Regulations | Os nomes abreviados dos regulamentos aplicáveis. |
Markets | Os mercados, com código e nome do país. |
EN Standards | As normas recomendadas (apresentadas na plataforma como «Recommended Standards»; o feed mantém este nome). |
Tested for | Para que o produto foi ensaiado, segundo os seus documentos. |
Attributes | Os dados do produto, etiqueta, valor e unidade. |
Attributes on Product | Os atributos que constam do produto. |
Attributes on Packaging | Os atributos que constam da embalagem. |
Attributes in Documentation | Os atributos que constam da documentação. |
Attributes in Online Listing | Os atributos que constam do anúncio em linha. |
Document Links | Uma entrada por documento: título, tipo, áreas de conformidade e uma ligação para o documento. |
Customer pack | «6 of 10 ready» e o estado de cada um dos dez itens (o feed mantém os dez; a página do pacote mostra cinco desde o início e quatro a pedido) (em JSON: { ready, total, items }). Vazio, ou null em JSON, na verificação gratuita. |
Customer pack URL | A ligação para a página do pacote do cliente do produto: a ligação permanente do próprio produto ou a partilha do cliente shared quando filtra. Vazio na verificação gratuita. |
Created | Quando o produto foi criado. |
Updated | Quando o produto foi alterado pela última vez. |
O feed não tem coluna de estado de conformidade, de Risk Score nem de ação seguinte; essas estão na API. O feed não tem número de versão: os nomes das suas colunas são o seu contrato, e os nomes das colunas importadas seguem as suas importações.
Exemplo de pedido
curl "https://documents.conphora.com/feed/<your-feed-token>?format=json" Exemplo de resposta
[
{
"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"
}
] Os erros do feed são texto simples, não JSON: 404 quando a ligação é inválida ou foi revogada, 413 quando a exportação seria demasiado grande (o CSV é o formato mais compacto).
Limites de pedidos
As leituras e as escritas têm limites separados, cada um contado por chave de API e por organização (todas as chaves em conjunto). Um pedido tem de respeitar ambos. Os valores são os de hoje, definidos para travar scripts descontrolados e não para limitar a utilização normal.
| Pedidos | Contado por | Taxa | Pico |
|---|---|---|---|
GET /api/v1/products, GET /api/v1/fields | chave de API | 600 / minuto | 120 |
GET /api/v1/products, GET /api/v1/fields | organização | 3,000 / minuto | 500 |
POST /api/v1/intake | chave de API | 120 / minuto | 30 |
POST /api/v1/intake | organização | 600 / minuto | 100 |
Acima do limite, a API responde com 429, o erro rate_limited, um campo retryAfterMs e um cabeçalho Retry-After em segundos (pelo menos 1). Aguarde esse tempo antes de tentar de novo.
HTTP/1.1 429 Too Many Requests
Retry-After: 2
{
"error": "rate_limited",
"message": "Too many requests. Slow down and retry.",
"retryAfterMs": 1800
} Erros
Todos os erros de um endpoint `/api/v1` são JSON com a forma `{ "error": "<code>", "message": "<text>" }`, por vezes com campos adicionais, enviados com o estado HTTP. Decida com base em `error`, nunca em `message`. Um método incorreto ou um caminho desconhecido não pertence a estes endpoints e não responde com esta forma.
| Estado | error | Quando | Campos adicionais | Endpoints |
|---|---|---|---|---|
| 400 | missing_parameter | Sem profileId, sem valores, ou sem products / uma matriz vazia. | todos | |
| 400 | too_many_values | Mais de 100 valores distintos. | maxValues | GET /api/v1/products |
| 400 | unknown_field | field não é identifier, name nem gtin. | supportedFields | GET /api/v1/products |
| 400 | invalid_profile_id | profileId não é um id bem formado. | todos | |
| 400 | invalid_json | O corpo não é JSON. | POST /api/v1/intake | |
| 400 | invalid_payload | O corpo não é um objeto, ou products não é uma matriz. | POST /api/v1/intake | |
| 400 | too_many_products | Mais de 100 produtos. | maxProducts | POST /api/v1/intake |
| 401 | missing_api_key | Não foi enviada nenhuma chave. | todos | |
| 401 | invalid_api_key | A chave é desconhecida. | todos | |
| 401 | revoked_api_key | A chave foi revogada. | todos | |
| 403 | insufficient_scope | Uma chave read chamou o intake. | POST /api/v1/intake | |
| 403 | profile_not_allowed | A chave está associada a outro perfil. | todos | |
| 403 | membership_required | A organização não tem um plano de autosserviço ativo. | POST /api/v1/intake | |
| 404 | profile_not_found | O perfil não existe ou pertence a outra organização. | todos | |
| 413 | response_too_large | O resultado seria superior a cerca de 18 MB. Peça menos valores. | GET /api/v1/products | |
| 413 | payload_too_large | O corpo é superior a 1 MB. | maxBodyBytes | POST /api/v1/intake |
| 429 | rate_limited | Foi atingido um limite de pedidos. | retryAfterMs + Retry-After header | todos |
| 429 | intake_full | A Inbox do perfil passaria as 50 000 linhas em espera. | POST /api/v1/intake | |
| 500 | intake_failed | O pedido falhou a meio; os produtos anteriores ao índice completed foram guardados. | completed, results | POST /api/v1/intake |
| 503 | rate_limiter_unavailable | As escritas estão temporariamente indisponíveis. Tente de novo depois do cabeçalho Retry-After. | Retry-After header | POST /api/v1/intake |
Versões
- A versão consta do caminho (
/api/v1) e de todos os corpos de resposta comometa.apiVersion. - Podem ser acrescentados campos a qualquer momento. Construa clientes que ignorem os campos que não conhecem.
- Uma alteração incompatível muda a versão.
meta.apiVersion: "2026-09-10"