Authentifizierung
Jede API-Anfrage trägt einen API-Schlüssel. Ein Schlüssel gehört zu einer Organisation und kann nur die Compliance-Profile dieser Organisation lesen.
Schlüssel erstellen
- Öffnen Sie auf der Plattform Einstellungen → API-Schlüssel und erstellen Sie einen Schlüssel. Geben Sie ihm einen Namen zu Ihrer eigenen Orientierung.
- Wählen Sie den Bereich: Lassen Sie „Diesem Schlüssel erlauben, Produkte in den Posteingang zu übertragen“ deaktiviert für einen reinen Lese-Schlüssel, aktivieren Sie es für einen
read_write-Schlüssel. - Hat Ihre Organisation zwei oder mehr Compliance-Profile, können Sie den Schlüssel an eines davon binden.
- Kopieren Sie den Schlüssel. Er beginnt mit
cfa_live_und wird nur einmal angezeigt: Conphora kann ihn nicht erneut anzeigen. Wenn Sie ihn verlieren, widerrufen Sie ihn und erstellen Sie einen neuen.
Die Schlüsselliste zeigt für jeden Schlüssel die ersten Zeichen, den Namen, den Bereich, die Profilbindung, das Erstellungsdatum und die letzte Verwendung. Das Widerrufen eines Schlüssels wirkt sofort; der Schlüssel erhält danach 401 revoked_api_key. Sie können einen Schlüssel umbenennen, aber Bereich und Bindung nicht ändern, erstellen Sie stattdessen einen neuen Schlüssel.
Schlüssel senden
Senden Sie den Schlüssel im Header x-api-key. Authorization: Bearer <key> wird ebenfalls akzeptiert; werden beide gesendet, gilt x-api-key.
x-api-key: cfa_live_…
# or
Authorization: Bearer cfa_live_… Verwenden Sie den Schlüssel nur auf Ihrem Server, niemals in Shop-Frontends oder im JavaScript des Browsers. Direkte Aufrufe der API aus Browsern werden nicht unterstützt.
Bereiche
| Schlüsselbereich | Bedeutung |
|---|---|
read | GET /api/v1/products und GET /api/v1/fields. Der Standard. |
read_write | Alles, was read aufrufen kann, plus POST /api/v1/intake. |
Der Bereich wird beim Erstellen des Schlüssels festgelegt.
Profilbindung
- Ein an ein Profil gebundener Schlüssel darf nur dieses Profil nennen. Jede andere
profileIderhält403 profile_not_allowed. - Ein ungebundener Schlüssel darf jedes Profil seiner Organisation nennen. Ein Profil, das nicht existiert oder zu einer anderen Organisation gehört, erhält
404 profile_not_found.
Wo Sie Ihre Profil-ID finden
Jeder Endpunkt benötigt eine profileId: die ID eines Compliance-Profils auf der Plattform. Unter Einstellungen → API-Schlüssel finden Sie eine Beispielanfrage, die sie bereits enthält. GET /api/v1/fields gibt ID und Namen des Profils zurück, damit Sie prüfen können, ob es das richtige ist.
GET/api/v1/products
Produkte abfragen
Fragen Sie 1 bis 100 Produkte nach Ihrer eigenen Kennung, nach Name oder nach Barcode ab und erhalten Sie Compliance-Status, Risk Score, nächste Maßnahme und Kundenpaket. Es gibt keinen Endpunkt, der einen ganzen Katalog auflistet; dafür dient der Produkt-Feed.
Schlüsselbereich: readTarif: jeder Tarif
Abfrageparameter
| Parameter | Typ | Erforderlich | Standard | Bedeutung |
|---|---|---|---|---|
profileId | string | ja | Das Compliance-Profil, in dem gesucht wird. Es muss zur Organisation des Schlüssels gehören und, wenn der Schlüssel gebunden ist, zur Bindung passen. | |
values | string (comma-separated or repeated) | ja | Die nachzuschlagenden Werte. values=A,B,C und values=A&values=B funktionieren beide; verwenden Sie die wiederholte Form, wenn ein Wert ein Komma enthält. Werte werden getrimmt, leere Werte entfallen, exakte Duplikate werden entfernt und gezählt. Höchstens 100 nach Entfernen der Duplikate. | |
value | string | Alias | Wird als Alias von values akzeptiert und mit diesem zusammengeführt. | |
field | identifier | name | gtin | nein | identifier | Was die Werte sind: identifier = Ihre eigene Produktkennung (die Spalte, die Ihr Import als Kennung zugeordnet hat, etwa „SKU“), name = der Produktname, gtin = ein EAN-/UPC-/GTIN-Barcode. Groß- und Kleinschreibung egal. Andere Namen werden nicht akzeptiert. |
includeArchived | true | nein | false | Archivierte Produkte einbeziehen. Ohne diese Angabe bleiben archivierte Treffer außen vor, und ein not_found-Ergebnis meldet archivedMatchCount, wenn archivierte Produkte gepasst haben. |
So funktioniert der Abgleich
identifier: zuerst ein exakter Treffer, dann tolerante Varianten, führende Nullen rein numerischer Werte werden ignoriert („0012345“ findet „12345“), danach Satzzeichen, danach Groß- und Kleinschreibung. Rein numerische Werte mit mehr als 15 Ziffern werden alsvalue_precision_unsupportedabgelehnt. Ein Wert darf höchstens 512 Zeichen lang sein.gtin: Der Barcode wird in die 14-stellige GS1-Form normalisiert und exakt abgeglichen. 8, 12, 13 und 14 Ziffern sowie Trennzeichen sind in Ordnung; alles andere istnot_a_gtin.name: zuerst der exakte Name, dann eine Suche, die Groß- und Kleinschreibung sowie Satzzeichen ignoriert.- Passt mehr als ein Produkt, lautet das Ergebnis
ambiguousmit den Kandidaten. Die API rät nie: Fragen Sie erneut mit deridentifiereines Kandidaten ab. - Bei
field=identifierkommt ein Wert, der noch kein Produkt ist, aber im Posteingang wartet, alsstagedzurück.
Antwort
Die Antwort enthält results (eines je eindeutigem Wert, in Reihenfolge der Anfrage), summary und meta. Ein Wert, der nicht gefunden wird, mehrdeutig oder ungültig ist, ist kein HTTP-Fehler: Er kommt innerhalb der 200 als eigenes Ergebnis zurück.
Ergebnisse nach Status
status | Feld | Bedeutung |
|---|---|---|
found | value, matchedVia, product | Genau ein Produkt passt. |
not_found | value, archivedMatchCount (only when > 0) | Kein Treffer. |
staged | value, inbox { status: pending | dismissed, receivedAt } | Wartet im Posteingang, wird noch nicht verfolgt, daher gibt es noch keinen Compliance-Zustand. |
ambiguous | value, matches [{ id, identifier, name }] | Mehrere Produkte passen. |
ambiguous_truncated | value | Die Suche hat ihr Limit an Kandidaten erreicht. Grenzen Sie den Wert ein oder verwenden Sie identifier. Bei field=gtin nicht möglich. |
invalid_value | value, reason: empty_value | value_too_long | value_precision_unsupported | not_a_gtin | Der Wert kann nicht nachgeschlagen werden. |
matchedVia gibt an, wie ein found-Produkt gepasst hat: identifier_exact, identifier_numeric_zerostrip, identifier_numeric_roundtrip, identifier_alnum, identifier_normalized, name_exact, name_normalized, gtin_exact, gtin_canonical.
summary zählt die Ergebnisse: requested, found, notFound, staged, ambiguous, invalid, duplicatesDropped. ambiguous schließt ambiguous_truncated ein; duplicatesDropped erscheint nur, wenn Werte entfernt wurden.
meta enthält resolvedField (das verwendete Feld), identifierField (wie Ihr Import die Kennungsspalte genannt hat, zur Information) und apiVersion.
Das Produktobjekt
Jeder Schlüssel ist immer vorhanden, in dieser Reihenfolge. Die Spalten Ihrer importierten Tabelle gibt die API nie zurück.
| Feld | Typ | Bedeutung |
|---|---|---|
id | string | Die stabile Produkt-ID von Conphora. Kein Suchwert. |
profileId | string | Das Compliance-Profil. |
identifier | string | Ihre Produktkennung. |
identifierField | string | null | Der Name der Kennungsspalte in Ihrem Import. |
gtin | string | null | Der Barcode als 14 Ziffern, mit Nullen aufgefüllt; null, wenn der Import keinen gültigen Barcode hatte. |
name | string | Der Produktname. |
imageUrl | string | null | Die Bild-URL aus Ihrem Import. |
hsCode | string | null | Der HS-/Warencode. |
archived | boolean | True bei einem archivierten Produkt. |
status.classification | in_progress | awaiting_clarification | completed | failed | null | Stand der Klassifizierung; null, wenn sie nicht begonnen hat. |
status.compliance | not_checked | compliant | requires_compliance | Der Compliance-Zustand. Nie null: not_checked, wenn das Produkt noch nie bewertet wurde. |
compliance.lastCheckedAt | number (ms epoch) | null | Wann das Produkt zuletzt bewertet wurde. |
compliance.summary.matchedCount | number | Wie viele Anforderungen gelten. |
compliance.summary.fulfilledCount | number | Wie viele davon erfüllt sind. |
compliance.progress | { compliance, attributes, documents }: { filled, total } | Paare aus ausgefüllt/gesamt für Anforderungen, Produktdaten und Dokumente; {0, 0}, wenn es keine gibt. |
compliance.matchedRegulations[] | { id, shortName, fullTitle | null, eurLexUrl | null } | Die geltenden Vorschriften. |
compliance.missingRequirements[] | { key, kind, regulation, requirementId, domain | null, label, deferred } | Die offenen Anforderungen. kind ist doc, attr, symbol oder checkpoint. deferred = als „Diese Daten habe ich noch nicht“ markiert; zählt weiterhin als fehlend. |
riskScore | integer 0–100 | null | Der Conphora Risk Score: eine Priorität, kein Urteil. Null, bis das Produkt bewertet ist. |
riskBand | low | watch | high | critical | null | Die Stufe des Scores. Null, wenn es keinen Score gibt. |
nextAction | object | null | Der eine nächste Schritt. Null, wenn es keinen Score gibt oder nichts zu tun ist. |
nextAction.kind | string (see the list below) | Was zu tun ist. |
nextAction.who | you | supplier | Wer an der Reihe ist. |
nextAction.href | string (relative platform path) | Ein relativer Pfad auf der Plattform, der die Maßnahme öffnet. Öffnen Sie ihn auf dem Host der Plattform. |
nextAction.after | number | Der Risk Score, sobald diese Maßnahme erledigt ist. |
customerPack | object | null | Das Kundenpaket mit allen zehn Elementen und ihrem Status, Ihre Arbeitsansicht, dieselbe wie auf der Produktseite. Befüllt im Self-Service-Tarif; null beim kostenlosen Check und null, wenn das Profil noch keine Unternehmensdaten hat. |
customerPack.ready | integer 0–10 | Wie viele der zehn Elemente bereit sind. |
customerPack.total | 10 | Immer 10. |
customerPack.items | object: item id → ready | missing | waiting | not-needed | Der Status jedes Elements, in der Reihenfolge des Pakets. not-needed = kein Teil des Elements trifft auf das Produkt zu. |
customerPack.url | string | null | Der vollständige Link zur öffentlichen Kundenpaket-Seite des Produkts: der eigene dauerhafte Link des Produkts (derselbe wie im Export und im Feed). null, wenn es keinen gibt, und beim kostenlosen Check. |
customerPack.path | string | null | Derselbe Link als Pfad, /p/<token>, auf dem Dokumenten-Host. |
createdAt | number (ms epoch) | Wann das Produkt in Conphora angelegt wurde. |
updatedAt | number (ms epoch) | Wann sich das Produkt zuletzt geändert hat. |
Risk Score, Stufe und nächste Maßnahme
riskScore, riskBand und nextAction sind in jedem Tarif gleich. Der Score sagt, welche Produkte Sie zuerst beheben sollten; er nennt ein Produkt nie konform oder nicht konform. Eine bekannte Nichtkonformität setzt das Produkt unabhängig vom Score auf critical.
riskBand | Score | Bedeutung |
|---|---|---|
low | 0-24 | Überwacht, nichts zu tun |
watch | 25-49 | Es kommt etwas auf Sie zu |
high | 50-74 | Diesen Monat beheben |
critical | 75-100 | Sofort handeln |
nextAction.kind ist einer aus einer festen Menge: clearNonCompliance, reEvaluate, uploadDocument, confirmRequirement, fillProductData, askSupplier, issueDeclaration, runProcedure, registerProduct, assembleTechnicalFile, renewDocument, reconfirmRuleChange, meetKeyDate, submitReport, chaseSupplier, reviewSupplierAnswer.
So funktioniert der Risk Score
Elemente des Kundenpakets
Die Schlüssel von customerPack.items, in der Reihenfolge des Pakets. Jeder Status ist ready, missing, waiting oder not-needed. identity, contact, declaration, standards-tests, safety-information, instructions, substances, packaging-epr, technical-file, recall-contact.
Die API liefert alle zehn Status. Die öffentliche Paketseite, die Ihr Kunde öffnet, zeigt Ihrem Kunden zwei Gruppen: identity, contact, declaration, safety-information und instructions von Anfang an, gezählt als „n von 5 bereit zur Listung“; standards-tests, substances, packaging-epr und recall-contact auf Anfrage, jeweils mit einer Schaltfläche, die bei Ihnen nachfragt; technical-file steht nicht auf der Seite.
Beispielanfrage
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_…" Beispielantwort
{
"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"
}
} Fehler
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 — Fehler
GET/api/v1/fields
Felder ermitteln
Zeigt, welche `field`-Werte die Abfrage akzeptiert und wie der Import des Profils seine Kennungsspalte nennt. Jeder Schlüsselbereich; dieselben Profilregeln wie oben.
Schlüsselbereich: readTarif: jeder Tarif
Abfrageparameter
| Parameter | Typ | Erforderlich | Bedeutung |
|---|---|---|---|
profileId | string | ja | Das Compliance-Profil. |
Antwort
| Feld | Typ | Bedeutung |
|---|---|---|
profile.id | string | Die Profil-ID. |
profile.name | string | Der Profilname. |
identifierField | string | null | Wie der neueste Import die Kennungsspalte nennt. |
supportedFields | string[] | Immer ["identifier", "name", "gtin"]. |
meta.apiVersion | string | Die API-Version. |
Beispielanfrage
curl "https://documents.conphora.com/api/v1/fields?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c" \
-H "x-api-key: cfa_live_…" Beispielantwort
{
"profile": {
"id": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
"name": "Nordbirk ApS"
},
"identifierField": "SKU",
"supportedFields": [
"identifier",
"name",
"gtin"
],
"meta": {
"apiVersion": "2026-09-10"
}
} Fehler
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 — Fehler
POST/api/v1/intake
Produkte übertragen
Übertragen Sie bis zu 100 Produkte je Anfrage in den Posteingang eines Profils. Neue Kennungen warten im Posteingang, bis jemand aus Ihrem Team sie ins Tracking übernimmt; ein Produkt, dessen Kennung zu einem vorhandenen Produkt passt, aktualisiert dieses Produkt an Ort und Stelle. Die Übertragung selbst wird nicht berechnet, und das erneute Senden desselben Produkts ändert nichts.
Schlüsselbereich: read_writeTarif: Self-Service-Tarif
Erfordert einen Schlüssel mit dem Bereich read_write (sonst 403 insufficient_scope) und den Self-Service-Tarif (sonst 403 membership_required). Der Anfragekörper ist JSON, höchstens 1 MB.
Anfragekörper
| Feld | Typ | Erforderlich | Bedeutung |
|---|---|---|---|
profileId | string | ja | Das Ziel-Compliance-Profil. |
products | array (1–100) | ja | Die Produkte. Ein späteres Duplikat einer uniqueId entfällt (das erste gilt) und wird gezählt. |
products[].uniqueId | string | number | ja | Ihre Produktkennung, höchstens 512 Zeichen nach dem Trimmen. |
products[].name | string | ja | Der Produktname (höchstens 10.000 Zeichen). |
products[].description | string | ja | Die Produktbeschreibung. Die Klassifizierung von Conphora benötigt sie. |
products[].gtin | string | number | nein | Der Barcode. Wenn vorhanden, muss er eine gültige GTIN sein, sonst wird die Zeile mit not_a_gtin abgelehnt. |
products[].imageUrl | string | nein | Eine Bild-URL. |
products[].attributes | object of string | number | boolean | null | nein | Beliebige weitere Spalten als flaches Objekt. Höchstens 300 Schlüssel mit höchstens 200 Zeichen; lange Zeichenfolgen werden auf 10.000 Zeichen gekürzt; verschachtelte Werte werden abgelehnt. Ein Schlüssel, der wie ein Feld der obersten Ebene heißt, wird vom Wert der obersten Ebene überschrieben. |
products[].hints | object: category → attribute keys | nein | Sagt der Klassifizierung, welche Attribute was beschreiben. Jeder Schlüssel muss in attributes vorkommen und darf nur in einer Kategorie stehen. |
Hinweiskategorien: productDescription, material, productCategory, packaging, supplierInfo, other.
Der Posteingang eines Profils fasst höchstens 50.000 wartende Zeilen; eine Übertragung darüber hinaus erhält 429 intake_full.
Antwort
results stehen in Reihenfolge der Anfrage, eines je Produkt: uniqueId, status und intakeId, productId oder errors, wo zutreffend.
Ergebnisse nach Status
status | Bedeutung |
|---|---|
staged | Neu: wartet jetzt im Posteingang (intakeId). |
refreshed | Wartete bereits; sein Inhalt wurde aktualisiert. |
resurfaced | Wurde aus dem Posteingang verworfen und kam als ausstehend zurück, weil sich sein Inhalt geändert hat. |
unchanged | Bereits bekannt, nichts hat sich geändert. |
updated | Passte zu einem aktiven Produkt, das aktualisiert wurde (productId). |
updated_idle | Passte zu einem archivierten Produkt, das an Ort und Stelle aktualisiert wurde und archiviert bleibt. |
invalid | Die Zeile wurde abgelehnt: errors listet { field, reason }. |
Gründe für invalid: required, invalid_type, too_long, not_a_gtin, too_many_attributes, unknown_category, reserved_key, unknown_attribute, assigned_twice.
summary zählt die Ergebnisse: received, staged, refreshed, unchanged, updated, updatedIdle, archivedSkipped, invalid, duplicatesDropped. received zählt Produkte nach dem Entfernen von Duplikaten; refreshed schließt resurfaced ein; archivedSkipped ist immer 0 und bleibt für ältere Clients erhalten.
Schlägt eine Anfrage mittendrin mit 500 intake_failed fehl, wurden die Produkte vor dem Index completed gespeichert, und results listet sie auf; senden Sie den Rest erneut.
Beispielanfrage
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"
}
]
}' Beispielantwort
{
"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"
}
} Fehler
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 — Fehler
GET/feed/{token}
Produkt-Feed
Ein Produkt-Feed ist eine feste URL, die stets die neuesten Daten der aktiven Produkte eines Compliance-Profils liefert, als JSON, CSV oder Excel. Er braucht keinen API-Schlüssel: Das Token in der URL ist die Zugangsberechtigung, sodass jeder, der die URL hat, den Feed lesen kann, bis Sie ihn widerrufen.
Feed-Link erstellen und widerrufen
- Öffnen Sie auf der Plattform Tabellen, wählen Sie in der Symbolleiste „Feed“ und erstellen Sie einen Link. Der Link übernimmt die Spalten, die in diesem Moment in der Tabelle sichtbar sind; Spalten und Bezeichnung können Sie später ändern.
- Jeder Link hat Kopier-Schaltflächen für CSV, XLSX und JSON.
- Das Widerrufen eines Links wirkt sofort: Die nächste Anfrage erhält
404.
Feed-Links stehen in jedem Tarif zur Verfügung. Die beiden Spalten des Kundenpakets werden nur im Self-Service-Tarif befüllt.
Abfrageparameter
| Parameter | Bedeutung |
|---|---|
format | Das Ausgabeformat: json (Standard), csv oder xlsx. |
shared | Nur die Produkte behalten, die einen offenen Freigabe-Link des Kundenpakets mit dieser Bezeichnung haben (der Name Ihres Kunden, Groß- und Kleinschreibung egal), und die „Customer pack URL“ jeder Zeile auf diese Freigabe statt auf den dauerhaften Link des Produkts richten. So erhält ein Kunde ein Paket auf Katalogebene. Leer beim kostenlosen Check, der keine Freigabe-Links hat. |
Formate
format | Bedeutung |
|---|---|
json | Ein Array von Objekten, ein Schlüssel je Spaltenname. Strukturierte Spalten sind Arrays und Objekte, Datumsangaben sind ISO 8601, fehlende Werte sind null. |
csv | UTF-8 mit einer Kopfzeile aus Spaltennamen, durch Kommas getrennt. Zellen mit mehreren Werten werden mit Zeilenumbrüchen verbunden. |
xlsx | Ein Blatt mit denselben Zellen wie die CSV-Datei. |
Spalten
Ein Link liefert die für ihn gewählten Spalten in dieser Reihenfolge: zuerst Ihre eigenen importierten Spalten unter ihren eigenen Namen (Kennung, Name, dann der Rest), anders als die API enthält der Feed Ihre importierten Daten, danach die Spalten von Conphora:
| Spalte | Bedeutung |
|---|---|
EAN / GTIN | Der 14-stellige Barcode. |
Commodity Code | Der HS-Code. |
Matched Regulations | Die Kurznamen der geltenden Vorschriften. |
Markets | Die Märkte, mit Ländercode und Name. |
EN Standards | Die empfohlenen Normen (auf der Plattform als „Recommended Standards“ angezeigt; der Feed behält diesen Namen). |
Tested for | Wofür Ihre Dokumente zeigen, dass das Produkt geprüft wurde. |
Attributes | Die Produktdaten, Bezeichnung, Wert und Einheit. |
Attributes on Product | Die Attribute, die auf das Produkt gehören. |
Attributes on Packaging | Die Attribute, die auf die Verpackung gehören. |
Attributes in Documentation | Die Attribute, die in die Dokumentation gehören. |
Attributes in Online Listing | Die Attribute, die in das Online-Angebot gehören. |
Document Links | Ein Eintrag je Dokument: Titel, Art, Compliance-Bereiche und ein Link zum Dokument. |
Customer pack | „6 von 10 bereit“ und der Status jedes der zehn Elemente (der Feed behält alle zehn; die Paketseite zeigt fünf von Anfang an und vier auf Anfrage) (in JSON: { ready, total, items }). Leer, in JSON null, beim kostenlosen Check. |
Customer pack URL | Der Link zur Kundenpaket-Seite des Produkts: der eigene dauerhafte Link des Produkts oder die Freigabe des shared-Kunden, wenn Sie filtern. Leer beim kostenlosen Check. |
Created | Wann das Produkt angelegt wurde. |
Updated | Wann sich das Produkt zuletzt geändert hat. |
Der Feed hat keine Spalte für Compliance-Status, Risk Score oder nächste Maßnahme; diese gibt es in der API. Der Feed hat keine Versionsnummer: Seine Spaltennamen sind sein Vertrag, und die Namen Ihrer importierten Spalten folgen Ihren Importen.
Beispielanfrage
curl "https://documents.conphora.com/feed/<your-feed-token>?format=json" Beispielantwort
[
{
"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"
}
] Feed-Fehler sind Klartext, kein JSON: 404, wenn der Link ungültig oder widerrufen ist, 413, wenn der Export zu groß würde (CSV ist das kompakteste Format).
Ratenlimits
Lesen und Schreiben haben getrennte Limits, jeweils gezählt je API-Schlüssel und je Organisation (alle Schlüssel zusammen). Eine Anfrage muss beide bestehen. Die Zahlen sind heutige Werte, gesetzt, um außer Kontrolle geratene Skripte zu stoppen, nicht um die normale Nutzung zu drosseln.
| Anfragen | Gezählt je | Rate | Burst |
|---|---|---|---|
GET /api/v1/products, GET /api/v1/fields | API-Schlüssel | 600 / Minute | 120 |
GET /api/v1/products, GET /api/v1/fields | Organisation | 3,000 / Minute | 500 |
POST /api/v1/intake | API-Schlüssel | 120 / Minute | 30 |
POST /api/v1/intake | Organisation | 600 / Minute | 100 |
Über dem Limit antwortet die API mit 429, dem Fehler rate_limited, einem Feld retryAfterMs und einem Retry-After-Header in Sekunden (mindestens 1). Warten Sie so lange, bevor Sie es erneut versuchen.
HTTP/1.1 429 Too Many Requests
Retry-After: 2
{
"error": "rate_limited",
"message": "Too many requests. Slow down and retry.",
"retryAfterMs": 1800
} Fehler
Jeder Fehler eines `/api/v1`-Endpunkts ist JSON der Form `{ "error": "<code>", "message": "<text>" }`, manchmal mit zusätzlichen Feldern, gesendet mit dem HTTP-Status. Verzweigen Sie nach `error`, nie nach `message`. Eine falsche Methode oder ein unbekannter Pfad gehört nicht zu diesen Endpunkten und antwortet nicht in dieser Form.
| Status | error | Wann | Zusätzliche Felder | Endpunkte |
|---|---|---|---|---|
| 400 | missing_parameter | Keine profileId, keine Werte oder kein products / ein leeres Array. | alle | |
| 400 | too_many_values | Mehr als 100 verschiedene Werte. | maxValues | GET /api/v1/products |
| 400 | unknown_field | field ist nicht identifier, name oder gtin. | supportedFields | GET /api/v1/products |
| 400 | invalid_profile_id | profileId ist keine wohlgeformte ID. | alle | |
| 400 | invalid_json | Der Anfragekörper ist kein JSON. | POST /api/v1/intake | |
| 400 | invalid_payload | Der Anfragekörper ist kein Objekt, oder products ist kein Array. | POST /api/v1/intake | |
| 400 | too_many_products | Mehr als 100 Produkte. | maxProducts | POST /api/v1/intake |
| 401 | missing_api_key | Es wurde kein Schlüssel gesendet. | alle | |
| 401 | invalid_api_key | Der Schlüssel ist unbekannt. | alle | |
| 401 | revoked_api_key | Der Schlüssel wurde widerrufen. | alle | |
| 403 | insufficient_scope | Ein read-Schlüssel hat die Übertragung aufgerufen. | POST /api/v1/intake | |
| 403 | profile_not_allowed | Der Schlüssel ist an ein anderes Profil gebunden. | alle | |
| 403 | membership_required | Die Organisation hat keinen aktiven Self-Service-Tarif. | POST /api/v1/intake | |
| 404 | profile_not_found | Das Profil existiert nicht oder gehört zu einer anderen Organisation. | alle | |
| 413 | response_too_large | Das Ergebnis wäre größer als etwa 18 MB. Fragen Sie weniger Werte ab. | GET /api/v1/products | |
| 413 | payload_too_large | Der Anfragekörper ist größer als 1 MB. | maxBodyBytes | POST /api/v1/intake |
| 429 | rate_limited | Ein Ratenlimit wurde erreicht. | retryAfterMs + Retry-After header | alle |
| 429 | intake_full | Der Posteingang des Profils würde 50.000 wartende Zeilen überschreiten. | POST /api/v1/intake | |
| 500 | intake_failed | Die Anfrage ist mittendrin fehlgeschlagen; die Produkte vor dem Index completed wurden gespeichert. | completed, results | POST /api/v1/intake |
| 503 | rate_limiter_unavailable | Schreibzugriffe sind kurzzeitig nicht verfügbar. Versuchen Sie es nach dem Retry-After-Header erneut. | Retry-After header | POST /api/v1/intake |
Versionierung
- Die Version steht im Pfad (
/api/v1) und in jedem Antwortkörper alsmeta.apiVersion. - Felder können jederzeit hinzukommen. Bauen Sie Clients, die unbekannte Felder ignorieren.
- Eine inkompatible Änderung ändert die Version.
meta.apiVersion: "2026-09-10"