Entwickler

Conphora-API-Referenz

Lesen Sie Compliance-Status, Risk Score und Kundenpaket Ihrer Produkte aus Ihren eigenen Systemen, übertragen Sie neue Produkte an Conphora und beziehen Sie Ihren gesamten Katalog als aktuellen Feed. Die API ist für Aufrufe von einem Server aus gedacht.

API-Schlüssel erstellen
Basis-URL
https://documents.conphora.com
Aktuelle Version
/api/v1 · meta.apiVersion: "2026-09-10"

Die Lese-API (GET /api/v1/products, GET /api/v1/fields) und der Produkt-Feed stehen in jedem Tarif zur Verfügung. POST /api/v1/intake setzt den Self-Service-Tarif und einen read_write-Schlüssel voraus.

Hier beginnen

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

  1. Öffnen Sie auf der Plattform Einstellungen → API-Schlüssel und erstellen Sie einen Schlüssel. Geben Sie ihm einen Namen zu Ihrer eigenen Orientierung.
  2. 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.
  3. Hat Ihre Organisation zwei oder mehr Compliance-Profile, können Sie den Schlüssel an eines davon binden.
  4. 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.

Beispiel: erfundene DatenHTTP
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

Bereiche
SchlüsselbereichBedeutung
readGET /api/v1/products und GET /api/v1/fields. Der Standard.
read_writeAlles, 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 profileId erhält 403 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

ParameterTypErforderlichStandardBedeutung
profileIdstringjaDas 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.
valuesstring (comma-separated or repeated)jaDie 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.
valuestringAliasWird als Alias von values akzeptiert und mit diesem zusammengeführt.
fieldidentifier | name | gtinneinidentifierWas 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.
includeArchivedtrueneinfalseArchivierte 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 als value_precision_unsupported abgelehnt. 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 ist not_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 ambiguous mit den Kandidaten. Die API rät nie: Fragen Sie erneut mit der identifier eines Kandidaten ab.
  • Bei field=identifier kommt ein Wert, der noch kein Produkt ist, aber im Posteingang wartet, als staged zurü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

statusFeldBedeutung
foundvalue, matchedVia, productGenau ein Produkt passt.
not_foundvalue, archivedMatchCount (only when > 0)Kein Treffer.
stagedvalue, inbox { status: pending | dismissed, receivedAt }Wartet im Posteingang, wird noch nicht verfolgt, daher gibt es noch keinen Compliance-Zustand.
ambiguousvalue, matches [{ id, identifier, name }]Mehrere Produkte passen.
ambiguous_truncatedvalueDie Suche hat ihr Limit an Kandidaten erreicht. Grenzen Sie den Wert ein oder verwenden Sie identifier. Bei field=gtin nicht möglich.
invalid_valuevalue, reason: empty_value | value_too_long | value_precision_unsupported | not_a_gtinDer 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.

FeldTypBedeutung
idstringDie stabile Produkt-ID von Conphora. Kein Suchwert.
profileIdstringDas Compliance-Profil.
identifierstringIhre Produktkennung.
identifierFieldstring | nullDer Name der Kennungsspalte in Ihrem Import.
gtinstring | nullDer Barcode als 14 Ziffern, mit Nullen aufgefüllt; null, wenn der Import keinen gültigen Barcode hatte.
namestringDer Produktname.
imageUrlstring | nullDie Bild-URL aus Ihrem Import.
hsCodestring | nullDer HS-/Warencode.
archivedbooleanTrue bei einem archivierten Produkt.
status.classificationin_progress | awaiting_clarification | completed | failed | nullStand der Klassifizierung; null, wenn sie nicht begonnen hat.
status.compliancenot_checked | compliant | requires_complianceDer Compliance-Zustand. Nie null: not_checked, wenn das Produkt noch nie bewertet wurde.
compliance.lastCheckedAtnumber (ms epoch) | nullWann das Produkt zuletzt bewertet wurde.
compliance.summary.matchedCountnumberWie viele Anforderungen gelten.
compliance.summary.fulfilledCountnumberWie 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.
riskScoreinteger 0–100 | nullDer Conphora Risk Score: eine Priorität, kein Urteil. Null, bis das Produkt bewertet ist.
riskBandlow | watch | high | critical | nullDie Stufe des Scores. Null, wenn es keinen Score gibt.
nextActionobject | nullDer eine nächste Schritt. Null, wenn es keinen Score gibt oder nichts zu tun ist.
nextAction.kindstring (see the list below)Was zu tun ist.
nextAction.whoyou | supplierWer an der Reihe ist.
nextAction.hrefstring (relative platform path)Ein relativer Pfad auf der Plattform, der die Maßnahme öffnet. Öffnen Sie ihn auf dem Host der Plattform.
nextAction.afternumberDer Risk Score, sobald diese Maßnahme erledigt ist.
customerPackobject | nullDas 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.readyinteger 0–10Wie viele der zehn Elemente bereit sind.
customerPack.total10Immer 10.
customerPack.itemsobject: item id → ready | missing | waiting | not-neededDer Status jedes Elements, in der Reihenfolge des Pakets. not-needed = kein Teil des Elements trifft auf das Produkt zu.
customerPack.urlstring | nullDer 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.pathstring | nullDerselbe Link als Pfad, /p/<token>, auf dem Dokumenten-Host.
createdAtnumber (ms epoch)Wann das Produkt in Conphora angelegt wurde.
updatedAtnumber (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.

Risikostufen
riskBandScoreBedeutung
low0-24Überwacht, nichts zu tun
watch25-49Es kommt etwas auf Sie zu
high50-74Diesen Monat beheben
critical75-100Sofort 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

Beispiel: erfundene Datencurl
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

Beispiel: erfundene DatenJSON
{
  "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

ParameterTypErforderlichBedeutung
profileIdstringjaDas Compliance-Profil.

Antwort

FeldTypBedeutung
profile.idstringDie Profil-ID.
profile.namestringDer Profilname.
identifierFieldstring | nullWie der neueste Import die Kennungsspalte nennt.
supportedFieldsstring[]Immer ["identifier", "name", "gtin"].
meta.apiVersionstringDie API-Version.

Beispielanfrage

Beispiel: erfundene Datencurl
curl "https://documents.conphora.com/api/v1/fields?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c" \
  -H "x-api-key: cfa_live_…"

Beispielantwort

Beispiel: erfundene DatenJSON
{
  "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

FeldTypErforderlichBedeutung
profileIdstringjaDas Ziel-Compliance-Profil.
productsarray (1–100)jaDie Produkte. Ein späteres Duplikat einer uniqueId entfällt (das erste gilt) und wird gezählt.
products[].uniqueIdstring | numberjaIhre Produktkennung, höchstens 512 Zeichen nach dem Trimmen.
products[].namestringjaDer Produktname (höchstens 10.000 Zeichen).
products[].descriptionstringjaDie Produktbeschreibung. Die Klassifizierung von Conphora benötigt sie.
products[].gtinstring | numberneinDer Barcode. Wenn vorhanden, muss er eine gültige GTIN sein, sonst wird die Zeile mit not_a_gtin abgelehnt.
products[].imageUrlstringneinEine Bild-URL.
products[].attributesobject of string | number | boolean | nullneinBeliebige 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[].hintsobject: category → attribute keysneinSagt 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

statusBedeutung
stagedNeu: wartet jetzt im Posteingang (intakeId).
refreshedWartete bereits; sein Inhalt wurde aktualisiert.
resurfacedWurde aus dem Posteingang verworfen und kam als ausstehend zurück, weil sich sein Inhalt geändert hat.
unchangedBereits bekannt, nichts hat sich geändert.
updatedPasste zu einem aktiven Produkt, das aktualisiert wurde (productId).
updated_idlePasste zu einem archivierten Produkt, das an Ort und Stelle aktualisiert wurde und archiviert bleibt.
invalidDie 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

Beispiel: erfundene Datencurl
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

Beispiel: erfundene DatenJSON
{
  "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

  1. Ö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.
  2. Jeder Link hat Kopier-Schaltflächen für CSV, XLSX und JSON.
  3. 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

ParameterBedeutung
formatDas Ausgabeformat: json (Standard), csv oder xlsx.
sharedNur 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

formatBedeutung
jsonEin Array von Objekten, ein Schlüssel je Spaltenname. Strukturierte Spalten sind Arrays und Objekte, Datumsangaben sind ISO 8601, fehlende Werte sind null.
csvUTF-8 mit einer Kopfzeile aus Spaltennamen, durch Kommas getrennt. Zellen mit mehreren Werten werden mit Zeilenumbrüchen verbunden.
xlsxEin 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:

SpalteBedeutung
EAN / GTINDer 14-stellige Barcode.
Commodity CodeDer HS-Code.
Matched RegulationsDie Kurznamen der geltenden Vorschriften.
MarketsDie Märkte, mit Ländercode und Name.
EN StandardsDie empfohlenen Normen (auf der Plattform als „Recommended Standards“ angezeigt; der Feed behält diesen Namen).
Tested forWofür Ihre Dokumente zeigen, dass das Produkt geprüft wurde.
AttributesDie Produktdaten, Bezeichnung, Wert und Einheit.
Attributes on ProductDie Attribute, die auf das Produkt gehören.
Attributes on PackagingDie Attribute, die auf die Verpackung gehören.
Attributes in DocumentationDie Attribute, die in die Dokumentation gehören.
Attributes in Online ListingDie Attribute, die in das Online-Angebot gehören.
Document LinksEin 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 URLDer 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.
CreatedWann das Produkt angelegt wurde.
UpdatedWann 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

Beispiel: erfundene Datencurl
curl "https://documents.conphora.com/feed/<your-feed-token>?format=json"

Beispielantwort

Beispiel: erfundene DatenJSON
[
  {
    "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.

AnfragenGezählt jeRateBurst
GET /api/v1/products, GET /api/v1/fieldsAPI-Schlüssel600 / Minute120
GET /api/v1/products, GET /api/v1/fieldsOrganisation3,000 / Minute500
POST /api/v1/intakeAPI-Schlüssel120 / Minute30
POST /api/v1/intakeOrganisation600 / Minute100

Ü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.

Beispiel: erfundene DatenHTTP
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.

StatuserrorWannZusätzliche FelderEndpunkte
400missing_parameterKeine profileId, keine Werte oder kein products / ein leeres Array.alle
400too_many_valuesMehr als 100 verschiedene Werte.maxValuesGET /api/v1/products
400unknown_fieldfield ist nicht identifier, name oder gtin.supportedFieldsGET /api/v1/products
400invalid_profile_idprofileId ist keine wohlgeformte ID.alle
400invalid_jsonDer Anfragekörper ist kein JSON.POST /api/v1/intake
400invalid_payloadDer Anfragekörper ist kein Objekt, oder products ist kein Array.POST /api/v1/intake
400too_many_productsMehr als 100 Produkte.maxProductsPOST /api/v1/intake
401missing_api_keyEs wurde kein Schlüssel gesendet.alle
401invalid_api_keyDer Schlüssel ist unbekannt.alle
401revoked_api_keyDer Schlüssel wurde widerrufen.alle
403insufficient_scopeEin read-Schlüssel hat die Übertragung aufgerufen.POST /api/v1/intake
403profile_not_allowedDer Schlüssel ist an ein anderes Profil gebunden.alle
403membership_requiredDie Organisation hat keinen aktiven Self-Service-Tarif.POST /api/v1/intake
404profile_not_foundDas Profil existiert nicht oder gehört zu einer anderen Organisation.alle
413response_too_largeDas Ergebnis wäre größer als etwa 18 MB. Fragen Sie weniger Werte ab.GET /api/v1/products
413payload_too_largeDer Anfragekörper ist größer als 1 MB.maxBodyBytesPOST /api/v1/intake
429rate_limitedEin Ratenlimit wurde erreicht.retryAfterMs + Retry-After headeralle
429intake_fullDer Posteingang des Profils würde 50.000 wartende Zeilen überschreiten.POST /api/v1/intake
500intake_failedDie Anfrage ist mittendrin fehlgeschlagen; die Produkte vor dem Index completed wurden gespeichert.completed, resultsPOST /api/v1/intake
503rate_limiter_unavailableSchreibzugriffe sind kurzzeitig nicht verfügbar. Versuchen Sie es nach dem Retry-After-Header erneut.Retry-After headerPOST /api/v1/intake

Versionierung

  • Die Version steht im Pfad (/api/v1) und in jedem Antwortkörper als meta.apiVersion.
  • Felder können jederzeit hinzukommen. Bauen Sie Clients, die unbekannte Felder ignorieren.
  • Eine inkompatible Änderung ändert die Version.

meta.apiVersion: "2026-09-10"

Bereit zur Anbindung?

Erstellen Sie unter Einstellungen → API-Schlüssel auf der Plattform einen Schlüssel und führen Sie Ihre erste Abfrage aus.

API-Schlüssel erstellen