Sviluppatori

Riferimento API Conphora

Legga dai Suoi sistemi lo stato di conformità, il Risk Score e il pacchetto cliente dei Suoi prodotti, invii nuovi prodotti a Conphora e ottenga l’intero catalogo come feed live. L’API è pensata per essere chiamata da un server.

Crei una chiave API
URL di base
https://documents.conphora.com
Versione attuale
/api/v1 · meta.apiVersion: "2026-09-10"

L’API di lettura (GET /api/v1/products, GET /api/v1/fields) e il feed dei prodotti sono disponibili con ogni piano. POST /api/v1/intake richiede il piano self-service e una chiave read_write.

Inizi da qui

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

  1. Sulla piattaforma, apra Impostazioni → Chiavi API e crei una chiave. Le assegni un nome per Suo riferimento.
  2. 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.
  3. Se la Sua organizzazione ha due o più profili di conformità, può associare la chiave a uno di essi.
  4. 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.

Esempio: dati inventatiHTTP
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

Ambiti
Ambito della chiaveSignificato
readGET /api/v1/products e GET /api/v1/fields. È l’impostazione predefinita.
read_writeTutto 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 profileId riceve 403 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

ParametroTipoObbligatorioPredefinitoSignificato
profileIdstringsìIl profilo di conformità in cui cercare. Deve appartenere all’organizzazione della chiave e corrispondere all’associazione della chiave, se questa è associata.
valuesstring (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.
valuestringaliasAccettato come alias di values e unito ad esso.
fieldidentifier | name | gtinnoidentifierChe 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.
includeArchivedtruenofalseIncludere 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 come value_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 è ambiguous con i candidati. L’API non tira mai a indovinare: riformuli la richiesta con l’identifier di un candidato.
  • Con field=identifier, un valore che non è ancora un prodotto ma è in attesa nell’Inbox viene restituito come staged.

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

statusCampoSignificato
foundvalue, matchedVia, productHa corrisposto esattamente un prodotto.
not_foundvalue, archivedMatchCount (only when > 0)Nessuna corrispondenza.
stagedvalue, inbox { status: pending | dismissed, receivedAt }In attesa nell’Inbox, non ancora monitorato, quindi non esiste ancora uno stato di conformità.
ambiguousvalue, matches [{ id, identifier, name }]Hanno corrisposto più prodotti.
ambiguous_truncatedvalueLa ricerca ha raggiunto il limite di candidati. Restringa il valore o usi identifier. Non può verificarsi con field=gtin.
invalid_valuevalue, reason: empty_value | value_too_long | value_precision_unsupported | not_a_gtinIl 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.

CampoTipoSignificato
idstringL’id stabile del prodotto in Conphora. Non è un valore di ricerca.
profileIdstringIl profilo di conformità.
identifierstringIl Suo identificativo di prodotto.
identifierFieldstring | nullIl nome che la Sua importazione dà alla colonna dell’identificativo.
gtinstring | nullIl codice a barre di 14 cifre, completato con zeri; null quando l’importazione non conteneva un codice a barre valido.
namestringIl nome del prodotto.
imageUrlstring | nullL’URL dell’immagine dalla Sua importazione.
hsCodestring | nullIl codice SA (HS) / codice merceologico.
archivedbooleanTrue per un prodotto archiviato.
status.classificationin_progress | awaiting_clarification | completed | failed | nullA che punto è la classificazione; null quando non è iniziata.
status.compliancenot_checked | compliant | requires_complianceLo stato di conformità. Mai null: not_checked quando il prodotto non è mai stato valutato.
compliance.lastCheckedAtnumber (ms epoch) | nullQuando il prodotto è stato valutato l’ultima volta.
compliance.summary.matchedCountnumberQuanti requisiti si applicano.
compliance.summary.fulfilledCountnumberQuanti 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.
riskScoreinteger 0–100 | nullIl Risk Score di Conphora: una priorità, non un verdetto. Null finché il prodotto non è stato valutato.
riskBandlow | watch | high | critical | nullLa fascia del punteggio. Null quando non c’è un punteggio.
nextActionobject | nullL’unica cosa da fare successivamente. Null quando non c’è un punteggio o non c’è nulla da fare.
nextAction.kindstring (see the list below)Che cosa fare.
nextAction.whoyou | supplierA chi tocca.
nextAction.hrefstring (relative platform path)Un percorso relativo sulla piattaforma che apre l’azione. Lo apra sull’host della piattaforma.
nextAction.afternumberIl Risk Score una volta completata questa azione.
customerPackobject | nullIl 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.readyinteger 0–10Quanti dei dieci elementi sono pronti.
customerPack.total10Sempre 10.
customerPack.itemsobject: item id → ready | missing | waiting | not-neededLo stato di ciascun elemento, nell’ordine del pacchetto. not-needed = nessuna parte dell’elemento si applica al prodotto.
customerPack.urlstring | nullIl 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.pathstring | nullLo stesso link come percorso, /p/<token>, sull’host dei documenti.
createdAtnumber (ms epoch)Quando il prodotto è stato creato in Conphora.
updatedAtnumber (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.

Fasce di rischio
riskBandPunteggioSignificato
low0-24Monitorato, nulla da fare
watch25-49Qualcosa in arrivo
high50-74Da sistemare questo mese
critical75-100Intervenire subito

nextAction.kind è uno di un insieme fisso: clearNonCompliance, reEvaluate, uploadDocument, confirmRequirement, fillProductData, askSupplier, issueDeclaration, runProcedure, registerProduct, assembleTechnicalFile, renewDocument, reconfirmRuleChange, meetKeyDate, submitReport, chaseSupplier, reviewSupplierAnswer.

Come funziona il Risk Score

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

Esempio: dati inventaticurl
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

Esempio: dati inventatiJSON
{
  "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

ParametroTipoObbligatorioSignificato
profileIdstringsìIl profilo di conformità.

Risposta

CampoTipoSignificato
profile.idstringL’id del profilo.
profile.namestringIl nome del profilo.
identifierFieldstring | nullCome l’importazione più recente chiama la colonna dell’identificativo.
supportedFieldsstring[]Sempre ["identifier", "name", "gtin"].
meta.apiVersionstringLa versione dell’API.

Esempio di richiesta

Esempio: dati inventaticurl
curl "https://documents.conphora.com/api/v1/fields?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c" \
  -H "x-api-key: cfa_live_…"

Esempio di risposta

Esempio: dati inventatiJSON
{
  "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

CampoTipoObbligatorioSignificato
profileIdstringsìIl profilo di conformità di destinazione.
productsarray (1–100)sìI prodotti. Un duplicato successivo di un uniqueId viene scartato (prevale il primo) e conteggiato.
products[].uniqueIdstring | numbersìIl Suo identificativo di prodotto, al massimo 512 caratteri dopo l’eliminazione degli spazi.
products[].namestringsìIl nome del prodotto (al massimo 10.000 caratteri).
products[].descriptionstringsìLa descrizione del prodotto. La classificazione di Conphora ne ha bisogno.
products[].gtinstring | numbernoIl codice a barre. Se presente, deve essere un GTIN valido, altrimenti la riga viene rifiutata con not_a_gtin.
products[].imageUrlstringnoL’URL di un’immagine.
products[].attributesobject of string | number | boolean | nullnoQualsiasi 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[].hintsobject: category → attribute keysnoIndica 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

statusSignificato
stagedNuovo: ora in attesa nell’Inbox (intakeId).
refreshedEra già in attesa; il suo contenuto è stato aggiornato.
resurfacedEra stato scartato dall’Inbox ed è tornato in sospeso perché il suo contenuto è cambiato.
unchangedGià noto e nulla è cambiato.
updatedCorrispondeva a un prodotto attivo, che è stato aggiornato (productId).
updated_idleCorrispondeva a un prodotto archiviato, che è stato aggiornato sul posto e resta archiviato.
invalidLa 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

Esempio: dati inventaticurl
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

Esempio: dati inventatiJSON
{
  "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

  1. 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.
  2. Ogni link ha pulsanti di copia per CSV, XLSX e JSON.
  3. 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

ParametroSignificato
formatIl formato di output: json (predefinito), csv o xlsx.
sharedMantenga 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

formatSignificato
jsonUn 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.
csvUTF-8 con una riga di intestazione dei nomi delle colonne, separata da virgole. Le celle con più valori sono unite da interruzioni di riga.
xlsxUn 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:

ColonnaSignificato
EAN / GTINIl codice a barre di 14 cifre.
Commodity CodeIl codice SA (HS).
Matched RegulationsI nomi brevi delle normative che si applicano.
MarketsI mercati, con codice e nome del paese.
EN StandardsLe norme raccomandate (mostrate sulla piattaforma come «Recommended Standards»; il feed mantiene questo nome).
Tested forPer che cosa i Suoi documenti mostrano che il prodotto è stato provato.
AttributesI dati del prodotto, etichetta, valore e unità.
Attributes on ProductGli attributi che vanno sul prodotto.
Attributes on PackagingGli attributi che vanno sull’imballaggio.
Attributes in DocumentationGli attributi che vanno nella documentazione.
Attributes in Online ListingGli attributi che vanno nell’inserzione online.
Document LinksUna 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 URLIl 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.
CreatedQuando il prodotto è stato creato.
UpdatedQuando 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

Esempio: dati inventaticurl
curl "https://documents.conphora.com/feed/<your-feed-token>?format=json"

Esempio di risposta

Esempio: dati inventatiJSON
[
  {
    "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.

RichiesteConteggiato perFrequenzaPicco
GET /api/v1/products, GET /api/v1/fieldschiave API600 / minuto120
GET /api/v1/products, GET /api/v1/fieldsorganizzazione3,000 / minuto500
POST /api/v1/intakechiave API120 / minuto30
POST /api/v1/intakeorganizzazione600 / minuto100

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.

Esempio: dati inventatiHTTP
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.

StatoerrorQuandoCampi aggiuntiviEndpoint
400missing_parameterNessun profileId, nessun valore, oppure nessun products / array vuoto.tutti
400too_many_valuesPiù di 100 valori distinti.maxValuesGET /api/v1/products
400unknown_fieldfield non è identifier, name o gtin.supportedFieldsGET /api/v1/products
400invalid_profile_idprofileId non è un id ben formato.tutti
400invalid_jsonIl corpo non è JSON.POST /api/v1/intake
400invalid_payloadIl corpo non è un oggetto, oppure products non è un array.POST /api/v1/intake
400too_many_productsPiù di 100 prodotti.maxProductsPOST /api/v1/intake
401missing_api_keyNon è stata inviata alcuna chiave.tutti
401invalid_api_keyLa chiave è sconosciuta.tutti
401revoked_api_keyLa chiave è stata revocata.tutti
403insufficient_scopeUna chiave read ha chiamato l’intake.POST /api/v1/intake
403profile_not_allowedLa chiave è associata a un altro profilo.tutti
403membership_requiredL’organizzazione non ha un piano self-service attivo.POST /api/v1/intake
404profile_not_foundIl profilo non esiste o appartiene a un’altra organizzazione.tutti
413response_too_largeIl risultato supererebbe circa 18 MB. Richieda meno valori.GET /api/v1/products
413payload_too_largeIl corpo supera 1 MB.maxBodyBytesPOST /api/v1/intake
429rate_limitedÈ stato raggiunto un limite di frequenza.retryAfterMs + Retry-After headertutti
429intake_fullL’Inbox del profilo supererebbe le 50.000 righe in attesa.POST /api/v1/intake
500intake_failedLa richiesta è fallita a metà; i prodotti precedenti all’indice completed sono stati salvati.completed, resultsPOST /api/v1/intake
503rate_limiter_unavailableLe scritture sono brevemente non disponibili. Riprovi dopo il tempo indicato nell’intestazione Retry-After.Retry-After headerPOST /api/v1/intake

Versioni

  • La versione è nel percorso (/api/v1) e in ogni corpo di risposta come meta.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"

Vuole collegarsi?

Crei una chiave in Impostazioni → Chiavi API sulla piattaforma e faccia la Sua prima ricerca.

Crei una chiave API