Autenticazione
Ogni richiesta all’API reca una chiave API. Una chiave appartiene a una sola organizzazione e può leggere soltanto i profili di conformità di quell’organizzazione.
Creare una chiave
- Sulla piattaforma, apra Impostazioni → Chiavi API e crei una chiave. Le assegni un nome per Suo riferimento.
- Scelga l’ambito: lasci deselezionata la casella «Consenti a questa chiave di inviare prodotti all’Inbox» per una chiave di sola lettura, la selezioni per una chiave
read_write. - Se la Sua organizzazione ha due o più profili di conformità, può associare la chiave a uno di essi.
- Copi la chiave. Inizia con
cfa_live_e viene mostrata una sola volta: Conphora non può mostrarla di nuovo. Se la perde, la revochi e ne crei una nuova.
L’elenco delle chiavi mostra di ciascuna i primi caratteri, il nome, l’ambito, l’associazione al profilo, la data di creazione e l’ultimo utilizzo. La revoca di una chiave ha effetto immediato; la chiave riceve da quel momento 401 revoked_api_key. Può rinominare una chiave, ma non modificarne l’ambito o l’associazione: in quel caso crei una nuova chiave.
Inviare la chiave
Invii la chiave nell’intestazione x-api-key. È accettato anche Authorization: Bearer <key>; se vengono inviate entrambe, prevale x-api-key.
x-api-key: cfa_live_…
# or
Authorization: Bearer cfa_live_… Usi la chiave soltanto sul Suo server, mai nel JavaScript di un negozio online o del browser. Le chiamate dirette all’API da parte dei browser non sono supportate.
Ambiti
| Ambito della chiave | Significato |
|---|---|
read | GET /api/v1/products e GET /api/v1/fields. È l’impostazione predefinita. |
read_write | Tutto ciò che può chiamare read, più POST /api/v1/intake. |
L’ambito è definito al momento della creazione della chiave.
Associazione al profilo
- Una chiave associata a un profilo può indicare soltanto quel profilo. Qualsiasi altro
profileIdriceve403 profile_not_allowed. - Una chiave non associata può indicare qualsiasi profilo della propria organizzazione. Un profilo che non esiste, o che appartiene a un’altra organizzazione, riceve
404 profile_not_found.
Dove trovare l’id del profilo
Ogni endpoint richiede un profileId: l’id di un profilo di conformità sulla piattaforma. In Impostazioni → Chiavi API trova una richiesta di esempio che lo contiene già. GET /api/v1/fields restituisce l’id e il nome del profilo, così può verificare di avere quello giusto.
GET/api/v1/products
Cercare prodotti
Cerchi da 1 a 100 prodotti tramite il Suo identificativo, il nome o il codice a barre e ottenga stato di conformità, Risk Score, azione successiva e pacchetto cliente. Non esiste un endpoint che elenchi un intero catalogo: per questo usi il feed dei prodotti.
Ambito della chiave: readPiano: ogni piano
Parametri della query
| Parametro | Tipo | Obbligatorio | Predefinito | Significato |
|---|---|---|---|---|
profileId | string | sì | Il profilo di conformità in cui cercare. Deve appartenere all’organizzazione della chiave e corrispondere all’associazione della chiave, se questa è associata. | |
values | string (comma-separated or repeated) | sì | I valori da cercare. Sia values=A,B,C sia values=A&values=B funzionano; usi la forma ripetuta quando un valore contiene una virgola. I valori vengono ripuliti dagli spazi, i valori vuoti vengono scartati e i duplicati esatti vengono scartati e conteggiati. Al massimo 100 dopo l’eliminazione dei duplicati. | |
value | string | alias | Accettato come alias di values e unito ad esso. | |
field | identifier | name | gtin | no | identifier | Che cosa sono i valori: identifier = il Suo identificativo di prodotto (la colonna che la Sua importazione ha associato all’identificativo, ad esempio «SKU»), name = il nome del prodotto, gtin = un codice a barre EAN / UPC / GTIN. Senza distinzione tra maiuscole e minuscole. Non sono accettati altri nomi. |
includeArchived | true | no | false | Includere i prodotti archiviati. Senza questo parametro, le corrispondenze archiviate vengono escluse e un risultato not_found riporta archivedMatchCount quando hanno corrisposto prodotti archiviati. |
Come funziona l’abbinamento
identifier: prima una corrispondenza esatta, poi varianti tolleranti: si ignorano gli zeri iniziali dei valori composti solo da cifre («0012345» trova «12345»), poi la punteggiatura, poi le maiuscole. I valori composti solo da cifre e più lunghi di 15 cifre vengono rifiutati comevalue_precision_unsupported. Un valore può avere al massimo 512 caratteri.gtin: il codice a barre viene normalizzato nella forma GS1 a 14 cifre e confrontato esattamente. Vanno bene 8, 12, 13 e 14 cifre e i separatori; qualsiasi altra cosa ènot_a_gtin.name: prima il nome esatto, poi una ricerca che ignora maiuscole e punteggiatura.- Quando corrisponde più di un prodotto, il risultato è
ambiguouscon i candidati. L’API non tira mai a indovinare: riformuli la richiesta con l’identifierdi un candidato. - Con
field=identifier, un valore che non è ancora un prodotto ma è in attesa nell’Inbox viene restituito comestaged.
Risposta
La risposta contiene results (uno per ogni valore distinto, nell’ordine della richiesta), summary e meta. Un valore non trovato, ambiguo o non valido non è un errore HTTP: viene restituito all’interno del 200 come risultato a sé.
Risultati per stato
status | Campo | Significato |
|---|---|---|
found | value, matchedVia, product | Ha corrisposto esattamente un prodotto. |
not_found | value, archivedMatchCount (only when > 0) | Nessuna corrispondenza. |
staged | value, inbox { status: pending | dismissed, receivedAt } | In attesa nell’Inbox, non ancora monitorato, quindi non esiste ancora uno stato di conformità. |
ambiguous | value, matches [{ id, identifier, name }] | Hanno corrisposto più prodotti. |
ambiguous_truncated | value | La ricerca ha raggiunto il limite di candidati. Restringa il valore o usi identifier. Non può verificarsi con field=gtin. |
invalid_value | value, reason: empty_value | value_too_long | value_precision_unsupported | not_a_gtin | Il valore non può essere cercato. |
matchedVia indica come ha corrisposto un prodotto found: identifier_exact, identifier_numeric_zerostrip, identifier_numeric_roundtrip, identifier_alnum, identifier_normalized, name_exact, name_normalized, gtin_exact, gtin_canonical.
summary conta i risultati: requested, found, notFound, staged, ambiguous, invalid, duplicatesDropped. ambiguous comprende ambiguous_truncated; duplicatesDropped compare soltanto quando sono stati scartati dei valori.
meta contiene resolvedField (il campo usato), identifierField (come la Sua importazione ha chiamato la colonna dell’identificativo, a titolo informativo) e apiVersion.
L’oggetto prodotto
Ogni chiave è sempre presente, in quest’ordine. Le colonne del foglio di calcolo importato non vengono mai restituite dall’API.
| Campo | Tipo | Significato |
|---|---|---|
id | string | L’id stabile del prodotto in Conphora. Non è un valore di ricerca. |
profileId | string | Il profilo di conformità. |
identifier | string | Il Suo identificativo di prodotto. |
identifierField | string | null | Il nome che la Sua importazione dà alla colonna dell’identificativo. |
gtin | string | null | Il codice a barre di 14 cifre, completato con zeri; null quando l’importazione non conteneva un codice a barre valido. |
name | string | Il nome del prodotto. |
imageUrl | string | null | L’URL dell’immagine dalla Sua importazione. |
hsCode | string | null | Il codice SA (HS) / codice merceologico. |
archived | boolean | True per un prodotto archiviato. |
status.classification | in_progress | awaiting_clarification | completed | failed | null | A che punto è la classificazione; null quando non è iniziata. |
status.compliance | not_checked | compliant | requires_compliance | Lo stato di conformità. Mai null: not_checked quando il prodotto non è mai stato valutato. |
compliance.lastCheckedAt | number (ms epoch) | null | Quando il prodotto è stato valutato l’ultima volta. |
compliance.summary.matchedCount | number | Quanti requisiti si applicano. |
compliance.summary.fulfilledCount | number | Quanti di questi sono soddisfatti. |
compliance.progress | { compliance, attributes, documents }: { filled, total } | Coppie compilati / totale per requisiti, dati del prodotto e documenti; {0, 0} quando non ce ne sono. |
compliance.matchedRegulations[] | { id, shortName, fullTitle | null, eurLexUrl | null } | Le normative che si applicano. |
compliance.missingRequirements[] | { key, kind, regulation, requirementId, domain | null, label, deferred } | I requisiti aperti. kind è doc, attr, symbol o checkpoint. deferred = contrassegnato come «Non dispongo ancora di questo dato»; conta comunque come mancante. |
riskScore | integer 0–100 | null | Il Risk Score di Conphora: una priorità, non un verdetto. Null finché il prodotto non è stato valutato. |
riskBand | low | watch | high | critical | null | La fascia del punteggio. Null quando non c’è un punteggio. |
nextAction | object | null | L’unica cosa da fare successivamente. Null quando non c’è un punteggio o non c’è nulla da fare. |
nextAction.kind | string (see the list below) | Che cosa fare. |
nextAction.who | you | supplier | A chi tocca. |
nextAction.href | string (relative platform path) | Un percorso relativo sulla piattaforma che apre l’azione. Lo apra sull’host della piattaforma. |
nextAction.after | number | Il Risk Score una volta completata questa azione. |
customerPack | object | null | Il pacchetto cliente con tutti e dieci gli elementi e il loro stato: la Sua vista di lavoro, la stessa della pagina del prodotto. Compilato con il piano self-service; null con la verifica gratuita e null quando il profilo non ha ancora dati aziendali. |
customerPack.ready | integer 0–10 | Quanti dei dieci elementi sono pronti. |
customerPack.total | 10 | Sempre 10. |
customerPack.items | object: item id → ready | missing | waiting | not-needed | Lo stato di ciascun elemento, nell’ordine del pacchetto. not-needed = nessuna parte dell’elemento si applica al prodotto. |
customerPack.url | string | null | Il link completo alla pagina pubblica del pacchetto cliente del prodotto: il link permanente del prodotto stesso (lo stesso che riportano l’esportazione e il feed). null quando non esiste e con la verifica gratuita. |
customerPack.path | string | null | Lo stesso link come percorso, /p/<token>, sull’host dei documenti. |
createdAt | number (ms epoch) | Quando il prodotto è stato creato in Conphora. |
updatedAt | number (ms epoch) | Quando il prodotto è stato modificato l’ultima volta. |
Risk Score, fascia e azione successiva
riskScore, riskBand e nextAction sono uguali con ogni piano. Il punteggio indica quali prodotti sistemare per primi; non definisce mai un prodotto conforme o non conforme. Una non conformità nota colloca il prodotto in critical qualunque sia il punteggio.
riskBand | Punteggio | Significato |
|---|---|---|
low | 0-24 | Monitorato, nulla da fare |
watch | 25-49 | Qualcosa in arrivo |
high | 50-74 | Da sistemare questo mese |
critical | 75-100 | Intervenire subito |
nextAction.kind è uno di un insieme fisso: clearNonCompliance, reEvaluate, uploadDocument, confirmRequirement, fillProductData, askSupplier, issueDeclaration, runProcedure, registerProduct, assembleTechnicalFile, renewDocument, reconfirmRuleChange, meetKeyDate, submitReport, chaseSupplier, reviewSupplierAnswer.
Elementi del pacchetto cliente
Le chiavi di customerPack.items, nell’ordine del pacchetto. Ogni stato è ready, missing, waiting o not-needed. identity, contact, declaration, standards-tests, safety-information, instructions, substances, packaging-epr, technical-file, recall-contact.
L’API conserva tutti e dieci gli stati. La pagina pubblica del pacchetto che il Suo cliente apre mostra al Suo cliente due gruppi: identity, contact, declaration, safety-information e instructions fin dall’inizio, conteggiati come «n di 5 pronti per l’inserimento»; standards-tests, substances, packaging-epr e recall-contact su richiesta, ciascuno con un pulsante che li richiede a Lei; technical-file non compare nella pagina.
Esempio di richiesta
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_…" Esempio di risposta
{
"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"
}
} Errori
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 — Errori
GET/api/v1/fields
Scoprire i campi
Mostra quali valori di `field` accetta la ricerca e come l’importazione del profilo chiama la colonna dell’identificativo. Qualsiasi ambito della chiave; stesse regole sul profilo di cui sopra.
Ambito della chiave: readPiano: ogni piano
Parametri della query
| Parametro | Tipo | Obbligatorio | Significato |
|---|---|---|---|
profileId | string | sì | Il profilo di conformità. |
Risposta
| Campo | Tipo | Significato |
|---|---|---|
profile.id | string | L’id del profilo. |
profile.name | string | Il nome del profilo. |
identifierField | string | null | Come l’importazione più recente chiama la colonna dell’identificativo. |
supportedFields | string[] | Sempre ["identifier", "name", "gtin"]. |
meta.apiVersion | string | La versione dell’API. |
Esempio di richiesta
curl "https://documents.conphora.com/api/v1/fields?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c" \
-H "x-api-key: cfa_live_…" Esempio di risposta
{
"profile": {
"id": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
"name": "Nordbirk ApS"
},
"identifierField": "SKU",
"supportedFields": [
"identifier",
"name",
"gtin"
],
"meta": {
"apiVersion": "2026-09-10"
}
} Errori
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 — Errori
POST/api/v1/intake
Inviare prodotti
Invii fino a 100 prodotti per richiesta nell’Inbox di un profilo. I nuovi identificativi restano nell’Inbox finché qualcuno del Suo team non li sposta nel monitoraggio; un prodotto il cui identificativo corrisponde a un prodotto esistente aggiorna quel prodotto sul posto. L’invio in sé non è fatturato e inviare di nuovo lo stesso prodotto non cambia nulla.
Ambito della chiave: read_writePiano: piano self-service
Richiede una chiave con ambito read_write (altrimenti 403 insufficient_scope) e il piano self-service (altrimenti 403 membership_required). Il corpo è JSON, al massimo 1 MB.
Corpo della richiesta
| Campo | Tipo | Obbligatorio | Significato |
|---|---|---|---|
profileId | string | sì | Il profilo di conformità di destinazione. |
products | array (1–100) | sì | I prodotti. Un duplicato successivo di un uniqueId viene scartato (prevale il primo) e conteggiato. |
products[].uniqueId | string | number | sì | Il Suo identificativo di prodotto, al massimo 512 caratteri dopo l’eliminazione degli spazi. |
products[].name | string | sì | Il nome del prodotto (al massimo 10.000 caratteri). |
products[].description | string | sì | La descrizione del prodotto. La classificazione di Conphora ne ha bisogno. |
products[].gtin | string | number | no | Il codice a barre. Se presente, deve essere un GTIN valido, altrimenti la riga viene rifiutata con not_a_gtin. |
products[].imageUrl | string | no | L’URL di un’immagine. |
products[].attributes | object of string | number | boolean | null | no | Qualsiasi altra colonna, come oggetto piatto. Al massimo 300 chiavi di al massimo 200 caratteri; le stringhe lunghe vengono troncate a 10.000 caratteri; i valori annidati vengono rifiutati. Una chiave con lo stesso nome di un campo di primo livello viene sovrascritta dal valore di primo livello. |
products[].hints | object: category → attribute keys | no | Indica alla classificazione quali attributi descrivono che cosa. Ogni chiave deve esistere in attributes e può comparire in una sola categoria. |
Categorie di suggerimenti: productDescription, material, productCategory, packaging, supplierInfo, other.
L’Inbox di un profilo contiene al massimo 50.000 righe in attesa; un invio che superi questo limite riceve 429 intake_full.
Risposta
I results sono nell’ordine della richiesta, uno per prodotto: uniqueId, status e, dove applicabili, intakeId, productId o errors.
Risultati per stato
status | Significato |
|---|---|
staged | Nuovo: ora in attesa nell’Inbox (intakeId). |
refreshed | Era già in attesa; il suo contenuto è stato aggiornato. |
resurfaced | Era stato scartato dall’Inbox ed è tornato in sospeso perché il suo contenuto è cambiato. |
unchanged | Già noto e nulla è cambiato. |
updated | Corrispondeva a un prodotto attivo, che è stato aggiornato (productId). |
updated_idle | Corrispondeva a un prodotto archiviato, che è stato aggiornato sul posto e resta archiviato. |
invalid | La riga è stata rifiutata: errors elenca { field, reason }. |
Motivi di invalid: required, invalid_type, too_long, not_a_gtin, too_many_attributes, unknown_category, reserved_key, unknown_attribute, assigned_twice.
summary conta i risultati: received, staged, refreshed, unchanged, updated, updatedIdle, archivedSkipped, invalid, duplicatesDropped. received conta i prodotti dopo l’eliminazione dei duplicati; refreshed comprende resurfaced; archivedSkipped è sempre 0 e viene mantenuto per i client meno recenti.
Se una richiesta fallisce a metà con 500 intake_failed, i prodotti precedenti all’indice completed sono stati salvati e results li elenca; invii di nuovo il resto.
Esempio di richiesta
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"
}
]
}' Esempio di risposta
{
"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"
}
} Errori
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 — Errori
GET/feed/{token}
Feed dei prodotti
Un feed dei prodotti è un URL fisso che fornisce sempre i dati più recenti dei prodotti attivi di un profilo di conformità, in JSON, CSV o Excel. Non richiede una chiave API: il token nell’URL è la credenziale, perciò chiunque abbia l’URL può leggere il feed finché Lei non lo revoca.
Creare e revocare un link del feed
- Sulla piattaforma, apra Tabelle, scelga «Feed» nella barra degli strumenti e crei un link. Il link riprende le colonne visibili nella tabella in quel momento; potrà modificarne le colonne e assegnargli un’etichetta in seguito.
- Ogni link ha pulsanti di copia per CSV, XLSX e JSON.
- La revoca di un link ha effetto immediato: la richiesta successiva riceve
404.
I link del feed sono disponibili con ogni piano. Le due colonne del pacchetto cliente sono compilate soltanto con il piano self-service.
Parametri della query
| Parametro | Significato |
|---|---|
format | Il formato di output: json (predefinito), csv o xlsx. |
shared | Mantenga soltanto i prodotti che hanno un link di condivisione del pacchetto cliente aperto con questa etichetta (il nome del Suo cliente, senza distinzione tra maiuscole e minuscole) e faccia puntare l’«URL del pacchetto cliente» di ogni riga a quella condivisione anziché al link permanente del prodotto. Si ottiene così un pacchetto a livello di catalogo per un cliente. Vuoto con la verifica gratuita, che non ha link di condivisione. |
Formati
format | Significato |
|---|---|
json | Un array di oggetti, una chiave per ogni nome di colonna. Le colonne strutturate sono array e oggetti, le date sono ISO 8601, i valori mancanti sono null. |
csv | UTF-8 con una riga di intestazione dei nomi delle colonne, separata da virgole. Le celle con più valori sono unite da interruzioni di riga. |
xlsx | Un foglio con le stesse celle del CSV. |
Colonne
Un link fornisce le colonne scelte per esso, in quest’ordine: prima le Sue colonne importate con il loro nome (identificativo, nome, poi le altre), a differenza dell’API, il feed include i Suoi dati importati, poi le colonne di Conphora:
| Colonna | Significato |
|---|---|
EAN / GTIN | Il codice a barre di 14 cifre. |
Commodity Code | Il codice SA (HS). |
Matched Regulations | I nomi brevi delle normative che si applicano. |
Markets | I mercati, con codice e nome del paese. |
EN Standards | Le norme raccomandate (mostrate sulla piattaforma come «Recommended Standards»; il feed mantiene questo nome). |
Tested for | Per che cosa i Suoi documenti mostrano che il prodotto è stato provato. |
Attributes | I dati del prodotto, etichetta, valore e unità. |
Attributes on Product | Gli attributi che vanno sul prodotto. |
Attributes on Packaging | Gli attributi che vanno sull’imballaggio. |
Attributes in Documentation | Gli attributi che vanno nella documentazione. |
Attributes in Online Listing | Gli attributi che vanno nell’inserzione online. |
Document Links | Una voce per documento: titolo, tipo, aree di conformità e un link al documento. |
Customer pack | «6 di 10 pronti» e lo stato di ciascuno dei dieci elementi (il feed conserva tutti e dieci; la pagina del pacchetto ne mostra cinque fin dall’inizio e quattro su richiesta) (in JSON: { ready, total, items }). Vuoto, o null in JSON, con la verifica gratuita. |
Customer pack URL | Il link alla pagina del pacchetto cliente del prodotto: il link permanente del prodotto stesso oppure la condivisione del cliente shared quando si filtra. Vuoto con la verifica gratuita. |
Created | Quando il prodotto è stato creato. |
Updated | Quando il prodotto è stato modificato l’ultima volta. |
Il feed non ha colonne di stato di conformità, Risk Score o azione successiva: si trovano nell’API. Il feed non ha un numero di versione: i nomi delle sue colonne sono il suo contratto e i nomi delle Sue colonne importate seguono le Sue importazioni.
Esempio di richiesta
curl "https://documents.conphora.com/feed/<your-feed-token>?format=json" Esempio di risposta
[
{
"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"
}
] Gli errori del feed sono testo semplice, non JSON: 404 quando il link non è valido o è stato revocato, 413 quando l’esportazione sarebbe troppo grande (il CSV è il formato più compatto).
Limiti di frequenza
Letture e scritture hanno limiti distinti, ciascuno conteggiato per chiave API e per organizzazione (tutte le chiavi insieme). Una richiesta deve rispettarli entrambi. Le cifre sono i valori attuali, fissati per fermare script fuori controllo, non per limitare l’uso normale.
| Richieste | Conteggiato per | Frequenza | Picco |
|---|---|---|---|
GET /api/v1/products, GET /api/v1/fields | chiave API | 600 / minuto | 120 |
GET /api/v1/products, GET /api/v1/fields | organizzazione | 3,000 / minuto | 500 |
POST /api/v1/intake | chiave API | 120 / minuto | 30 |
POST /api/v1/intake | organizzazione | 600 / minuto | 100 |
Oltre il limite, l’API risponde 429 con l’errore rate_limited, un campo retryAfterMs e un’intestazione Retry-After in secondi (almeno 1). Attenda questo tempo prima di riprovare.
HTTP/1.1 429 Too Many Requests
Retry-After: 2
{
"error": "rate_limited",
"message": "Too many requests. Slow down and retry.",
"retryAfterMs": 1800
} Errori
Ogni errore di un endpoint `/api/v1` è un JSON nella forma `{ "error": "<code>", "message": "<text>" }`, a volte con campi aggiuntivi, inviato con lo stato HTTP. Si basi su `error`, mai su `message`. Un metodo errato o un percorso sconosciuto non è uno di questi endpoint e non risponde in questa forma.
| Stato | error | Quando | Campi aggiuntivi | Endpoint |
|---|---|---|---|---|
| 400 | missing_parameter | Nessun profileId, nessun valore, oppure nessun products / array vuoto. | tutti | |
| 400 | too_many_values | Più di 100 valori distinti. | maxValues | GET /api/v1/products |
| 400 | unknown_field | field non è identifier, name o gtin. | supportedFields | GET /api/v1/products |
| 400 | invalid_profile_id | profileId non è un id ben formato. | tutti | |
| 400 | invalid_json | Il corpo non è JSON. | POST /api/v1/intake | |
| 400 | invalid_payload | Il corpo non è un oggetto, oppure products non è un array. | POST /api/v1/intake | |
| 400 | too_many_products | Più di 100 prodotti. | maxProducts | POST /api/v1/intake |
| 401 | missing_api_key | Non è stata inviata alcuna chiave. | tutti | |
| 401 | invalid_api_key | La chiave è sconosciuta. | tutti | |
| 401 | revoked_api_key | La chiave è stata revocata. | tutti | |
| 403 | insufficient_scope | Una chiave read ha chiamato l’intake. | POST /api/v1/intake | |
| 403 | profile_not_allowed | La chiave è associata a un altro profilo. | tutti | |
| 403 | membership_required | L’organizzazione non ha un piano self-service attivo. | POST /api/v1/intake | |
| 404 | profile_not_found | Il profilo non esiste o appartiene a un’altra organizzazione. | tutti | |
| 413 | response_too_large | Il risultato supererebbe circa 18 MB. Richieda meno valori. | GET /api/v1/products | |
| 413 | payload_too_large | Il corpo supera 1 MB. | maxBodyBytes | POST /api/v1/intake |
| 429 | rate_limited | È stato raggiunto un limite di frequenza. | retryAfterMs + Retry-After header | tutti |
| 429 | intake_full | L’Inbox del profilo supererebbe le 50.000 righe in attesa. | POST /api/v1/intake | |
| 500 | intake_failed | La richiesta è fallita a metà; i prodotti precedenti all’indice completed sono stati salvati. | completed, results | POST /api/v1/intake |
| 503 | rate_limiter_unavailable | Le scritture sono brevemente non disponibili. Riprovi dopo il tempo indicato nell’intestazione Retry-After. | Retry-After header | POST /api/v1/intake |
Versioni
- La versione è nel percorso (
/api/v1) e in ogni corpo di risposta comemeta.apiVersion. - I campi possono essere aggiunti in qualsiasi momento. Realizzi client che ignorino i campi che non conoscono.
- Una modifica incompatibile cambia la versione.
meta.apiVersion: "2026-09-10"