Dla programistów

Dokumentacja API Conphora

Interfejs pozwala odczytywać status zgodności, Risk Score i pakiet dla klienta produktów z własnych systemów, przesyłać nowe produkty do Conphora i pobierać cały katalog jako aktualny feed. API jest przeznaczone do wywoływania z serwera.

Utwórz klucz API
Bazowy adres URL
https://documents.conphora.com
Bieżąca wersja
/api/v1 · meta.apiVersion: "2026-09-10"

Interfejs odczytu (GET /api/v1/products, GET /api/v1/fields) i feed produktów są dostępne w każdym planie. POST /api/v1/intake wymaga planu samoobsługowego i klucza read_write.

Na początek

Uwierzytelnianie

Każde żądanie API zawiera klucz API. Klucz należy do jednej organizacji i może odczytywać wyłącznie profile zgodności tej organizacji.

Utworzenie klucza

  1. Na platformie proszę otworzyć Ustawienia → Klucze API i utworzyć klucz, nadając mu nazwę do własnego użytku.
  2. Proszę wybrać zakres: aby uzyskać klucz tylko do odczytu, należy pozostawić niezaznaczoną opcję „Zezwól temu kluczowi na przesyłanie produktów do Skrzynki odbiorczej”; aby uzyskać klucz read_write, należy ją zaznaczyć.
  3. Jeśli organizacja ma dwa lub więcej profili zgodności, klucz można powiązać z jednym z nich.
  4. Proszę skopiować klucz. Zaczyna się od cfa_live_ i jest wyświetlany tylko raz: Conphora nie może pokazać go ponownie. W razie utraty należy go unieważnić i utworzyć nowy.

Lista kluczy pokazuje pierwsze znaki każdego klucza, jego nazwę, zakres, powiązanie z profilem, datę utworzenia i datę ostatniego użycia. Unieważnienie klucza działa natychmiast; klucz otrzymuje wtedy 401 revoked_api_key. Klucz można przemianować, ale nie można zmienić jego zakresu ani powiązania, zamiast tego należy utworzyć nowy klucz.

Wysyłanie klucza

Klucz wysyła się w nagłówku x-api-key. Akceptowany jest też Authorization: Bearer <key>; gdy wysłano oba, pierwszeństwo ma x-api-key.

Przykład: dane zmyśloneHTTP
x-api-key: cfa_live_…
# or
Authorization: Bearer cfa_live_…

Klucza należy używać wyłącznie na serwerze, nigdy w JavaScript sklepu ani przeglądarki. Bezpośrednie wywołania API z przeglądarek nie są obsługiwane.

Zakresy

Zakresy
Zakres kluczaZnaczenie
readGET /api/v1/products i GET /api/v1/fields. Ustawienie domyślne.
read_writeWszystko, co może wywołać read, oraz POST /api/v1/intake.

Zakres jest ustalany w chwili utworzenia klucza.

Powiązanie z profilem

  • Klucz powiązany z profilem może wskazywać wyłącznie ten profil. Każdy inny profileId kończy się odpowiedzią 403 profile_not_allowed.
  • Klucz niepowiązany może wskazywać dowolny profil w swojej organizacji. Profil, który nie istnieje lub należy do innej organizacji, kończy się odpowiedzią 404 profile_not_found.

Gdzie znaleźć identyfikator profilu

Każdy endpoint wymaga profileId: identyfikatora profilu zgodności na platformie. Ustawienia → Klucze API pokazują przykładowe żądanie, które już go zawiera. GET /api/v1/fields zwraca identyfikator i nazwę profilu, więc można sprawdzić, czy to właściwy profil.

GET/api/v1/products

Wyszukiwanie produktów

Pozwala wyszukać od 1 do 100 produktów według własnego identyfikatora, nazwy lub kodu kreskowego i uzyskać ich status zgodności, Risk Score, kolejne działanie i pakiet dla klienta. Nie ma endpointu, który wyświetla cały katalog; do tego służy feed produktów.

Zakres klucza: readPlan: każdy plan

Parametry zapytania

ParametrTypWymaganyDomyślnieZnaczenie
profileIdstringtakProfil zgodności, w którym prowadzone jest wyszukiwanie. Musi należeć do organizacji klucza i odpowiadać powiązaniu klucza, jeśli klucz jest powiązany.
valuesstring (comma-separated or repeated)takWartości do wyszukania. values=A,B,C i values=A&values=B działają jednakowo; gdy wartość zawiera przecinek, należy użyć formy powtarzanej. Wartości są przycinane, puste są pomijane, a dokładne duplikaty są usuwane i liczone. Po usunięciu duplikatów najwyżej 100.
valuestringaliasAkceptowany jako alias values i łączony z nim.
fieldidentifier | name | gtinnieidentifierCzym są wartości: identifier = własny identyfikator produktu (kolumna, którą import zmapował jako identyfikator, na przykład „SKU”), name = nazwa produktu, gtin = kod kreskowy EAN / UPC / GTIN. Wielkość liter nie ma znaczenia. Żadne inne nazwy nie są akceptowane.
includeArchivedtrueniefalseUwzględnia produkty zarchiwizowane. Bez tego zarchiwizowane dopasowania są pomijane, a wynik not_found podaje archivedMatchCount, gdy dopasowano produkty zarchiwizowane.

Jak działa dopasowanie

  • identifier: najpierw dokładne dopasowanie, potem warianty tolerancyjne, wiodące zera w wartościach złożonych wyłącznie z cyfr są pomijane („0012345” znajduje „12345”), następnie interpunkcja, potem wielkość liter. Wartości złożone wyłącznie z cyfr i dłuższe niż 15 cyfr są odrzucane jako value_precision_unsupported. Wartość może mieć najwyżej 512 znaków.
  • gtin: kod kreskowy jest normalizowany do 14-cyfrowej formy GS1 i dopasowywany dokładnie. 8, 12, 13 i 14 cyfr oraz separatory są dopuszczalne; wszystko inne to not_a_gtin.
  • name: najpierw dokładna nazwa, potem wyszukiwanie ignorujące wielkość liter i interpunkcję.
  • Gdy pasuje więcej niż jeden produkt, wynikiem jest ambiguous wraz z kandydatami. API nigdy nie zgaduje: należy ponowić zapytanie z identifier wybranego kandydata.
  • Przy field=identifier wartość, która nie jest jeszcze produktem, ale czeka w Skrzynce odbiorczej, wraca jako staged.

Odpowiedź

Odpowiedź zawiera results (po jednym dla każdej odrębnej wartości, w kolejności żądania), summary i meta. Wartość nieznaleziona, niejednoznaczna lub nieprawidłowa nie jest błędem HTTP: wraca w odpowiedzi 200 jako osobny wynik.

Wyniki według statusu

statusPoleZnaczenie
foundvalue, matchedVia, productDopasowano dokładnie jeden produkt.
not_foundvalue, archivedMatchCount (only when > 0)Brak dopasowania.
stagedvalue, inbox { status: pending | dismissed, receivedAt }Czeka w Skrzynce odbiorczej, nie jest jeszcze śledzony, więc nie ma jeszcze stanu zgodności.
ambiguousvalue, matches [{ id, identifier, name }]Dopasowano kilka produktów.
ambiguous_truncatedvalueWyszukiwanie osiągnęło limit kandydatów. Należy zawęzić wartość lub użyć identifier. Nie może wystąpić przy field=gtin.
invalid_valuevalue, reason: empty_value | value_too_long | value_precision_unsupported | not_a_gtinWartości nie można wyszukać.

matchedVia mówi, jak dopasowano produkt o statusie found: identifier_exact, identifier_numeric_zerostrip, identifier_numeric_roundtrip, identifier_alnum, identifier_normalized, name_exact, name_normalized, gtin_exact, gtin_canonical.

summary zlicza wyniki: requested, found, notFound, staged, ambiguous, invalid, duplicatesDropped. ambiguous obejmuje ambiguous_truncated; duplicatesDropped pojawia się tylko wtedy, gdy usunięto wartości.

meta zawiera resolvedField (użyte pole), identifierField (jak import nazwał kolumnę identyfikatora, informacyjnie) i apiVersion.

Obiekt produktu

Każdy klucz jest zawsze obecny, w tej kolejności. Kolumny zaimportowanego arkusza nigdy nie są zwracane przez API.

PoleTypZnaczenie
idstringStały identyfikator produktu w Conphora. Nie jest wartością do wyszukiwania.
profileIdstringProfil zgodności.
identifierstringWłasny identyfikator produktu.
identifierFieldstring | nullNazwa kolumny identyfikatora w imporcie.
gtinstring | nullKod kreskowy jako 14 cyfr, uzupełniony zerami; null, gdy import nie zawierał prawidłowego kodu kreskowego.
namestringNazwa produktu.
imageUrlstring | nullAdres URL obrazu z importu.
hsCodestring | nullKod HS / kod towarowy.
archivedbooleanTrue dla produktu zarchiwizowanego.
status.classificationin_progress | awaiting_clarification | completed | failed | nullNa jakim etapie jest klasyfikacja; null, gdy jeszcze się nie rozpoczęła.
status.compliancenot_checked | compliant | requires_complianceStan zgodności. Nigdy null: not_checked, gdy produkt nigdy nie był oceniany.
compliance.lastCheckedAtnumber (ms epoch) | nullKiedy produkt był ostatnio oceniany.
compliance.summary.matchedCountnumberIle wymagań ma zastosowanie.
compliance.summary.fulfilledCountnumberIle z nich jest spełnionych.
compliance.progress{ compliance, attributes, documents }: { filled, total }Pary wypełnione / ogółem dla wymagań, danych produktu i dokumentów; {0, 0}, gdy ich nie ma.
compliance.matchedRegulations[]{ id, shortName, fullTitle | null, eurLexUrl | null }Przepisy, które mają zastosowanie.
compliance.missingRequirements[]{ key, kind, regulation, requirementId, domain | null, label, deferred }Otwarte wymagania. kind to doc, attr, symbol lub checkpoint. deferred = oznaczone jako „Nie mam jeszcze tych danych”; nadal liczy się jako brakujące.
riskScoreinteger 0–100 | nullRisk Score Conphora: priorytet, a nie werdykt. Null, dopóki produkt nie zostanie oceniony.
riskBandlow | watch | high | critical | nullPasmo wyniku. Null, gdy nie ma wyniku.
nextActionobject | nullJedno kolejne działanie. Null, gdy nie ma wyniku lub nie ma nic do zrobienia.
nextAction.kindstring (see the list below)Co zrobić.
nextAction.whoyou | supplierDo kogo należy ruch.
nextAction.hrefstring (relative platform path)Względna ścieżka na platformie, która otwiera działanie. Należy ją otwierać na hoście platformy.
nextAction.afternumberRisk Score po wykonaniu tego działania.
customerPackobject | nullPakiet dla klienta ze wszystkimi dziesięcioma pozycjami i ich statusem, Państwa widok roboczy, taki sam jak na stronie produktu. Wypełniany w planie samoobsługowym; null przy bezpłatnym sprawdzeniu oraz null, gdy profil nie ma jeszcze danych firmy.
customerPack.readyinteger 0–10Ile z dziesięciu pozycji jest gotowych.
customerPack.total10Zawsze 10.
customerPack.itemsobject: item id → ready | missing | waiting | not-neededStatus każdej pozycji, w kolejności pakietu. not-needed = żadna część pozycji nie dotyczy produktu.
customerPack.urlstring | nullPełny link do publicznej strony pakietu dla klienta: stały link produktu (ten sam, który niosą eksport i feed). null, gdy go nie ma, oraz przy bezpłatnym sprawdzeniu.
customerPack.pathstring | nullTen sam link jako ścieżka /p/<token> na hoście dokumentów.
createdAtnumber (ms epoch)Kiedy produkt został utworzony w Conphora.
updatedAtnumber (ms epoch)Kiedy produkt ostatnio się zmienił.

Risk Score, pasmo i kolejne działanie

riskScore, riskBand i nextAction są takie same w każdym planie. Wynik mówi, które produkty poprawić w pierwszej kolejności; nigdy nie nazywa produktu zgodnym ani niezgodnym. Znana niezgodność umieszcza produkt w paśmie critical niezależnie od wyniku.

Pasma ryzyka
riskBandWynikZnaczenie
low0-24Monitorowane, nic do zrobienia
watch25-49Coś się zbliża
high50-74Do poprawy w tym miesiącu
critical75-100Działać natychmiast

nextAction.kind jest jedną z ustalonego zbioru wartości: clearNonCompliance, reEvaluate, uploadDocument, confirmRequirement, fillProductData, askSupplier, issueDeclaration, runProcedure, registerProduct, assembleTechnicalFile, renewDocument, reconfirmRuleChange, meetKeyDate, submitReport, chaseSupplier, reviewSupplierAnswer.

Jak działa Risk Score

Pozycje pakietu dla klienta

Klucze customerPack.items, w kolejności pakietu. Każdy status to ready, missing, waiting lub not-needed. identity, contact, declaration, standards-tests, safety-information, instructions, substances, packaging-epr, technical-file, recall-contact.

API zachowuje wszystkie dziesięć statusów. Publiczna strona pakietu, którą otwiera klient, pokazuje Państwa klientowi dwie grupy: identity, contact, declaration, safety-information i instructions od początku, liczone jako „n z 5 gotowych do wystawienia”; standards-tests, substances, packaging-epr i recall-contact na żądanie, każde z przyciskiem, który wysyła do Państwa prośbę; technical-file nie ma na stronie.

Przykładowe żądanie

Przykład: dane zmyślonecurl
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_…"

Przykładowa odpowiedź

Przykład: dane zmyśloneJSON
{
  "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"
  }
}

Błędy

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 — Błędy

GET/api/v1/fields

Odkrywanie pól

Pokazuje, jakie wartości `field` akceptuje wyszukiwanie i jak import profilu nazywa kolumnę identyfikatora. Dowolny zakres klucza; te same zasady dotyczące profilu co wyżej.

Zakres klucza: readPlan: każdy plan

Parametry zapytania

ParametrTypWymaganyZnaczenie
profileIdstringtakProfil zgodności.

Odpowiedź

PoleTypZnaczenie
profile.idstringIdentyfikator profilu.
profile.namestringNazwa profilu.
identifierFieldstring | nullJak najnowszy import nazywa kolumnę identyfikatora.
supportedFieldsstring[]Zawsze ["identifier", "name", "gtin"].
meta.apiVersionstringWersja API.

Przykładowe żądanie

Przykład: dane zmyślonecurl
curl "https://documents.conphora.com/api/v1/fields?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c" \
  -H "x-api-key: cfa_live_…"

Przykładowa odpowiedź

Przykład: dane zmyśloneJSON
{
  "profile": {
    "id": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
    "name": "Nordbirk ApS"
  },
  "identifierField": "SKU",
  "supportedFields": [
    "identifier",
    "name",
    "gtin"
  ],
  "meta": {
    "apiVersion": "2026-09-10"
  }
}

Błędy

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 — Błędy

POST/api/v1/intake

Przesyłanie produktów

Pozwala przesłać do 100 produktów na żądanie do Skrzynki odbiorczej profilu. Nowe identyfikatory czekają w Skrzynce odbiorczej, aż ktoś z zespołu przeniesie je do śledzenia; produkt, którego identyfikator pasuje do istniejącego produktu, aktualizuje ten produkt w miejscu. Samo przesłanie nie jest rozliczane, a ponowne wysłanie tego samego produktu niczego nie zmienia.

Zakres klucza: read_writePlan: plan samoobsługowy

Wymaga klucza z zakresem read_write (w przeciwnym razie 403 insufficient_scope) i planu samoobsługowego (w przeciwnym razie 403 membership_required). Treść to JSON, najwyżej 1 MB.

Treść żądania

PoleTypWymaganyZnaczenie
profileIdstringtakDocelowy profil zgodności.
productsarray (1–100)takProdukty. Późniejszy duplikat uniqueId jest odrzucany (wygrywa pierwszy) i liczony.
products[].uniqueIdstring | numbertakWłasny identyfikator produktu, najwyżej 512 znaków po przycięciu.
products[].namestringtakNazwa produktu (najwyżej 10 000 znaków).
products[].descriptionstringtakOpis produktu. Klasyfikacja Conphora go potrzebuje.
products[].gtinstring | numbernieKod kreskowy. Jeśli jest podany, musi być prawidłowym GTIN, w przeciwnym razie wiersz jest odrzucany z not_a_gtin.
products[].imageUrlstringnieAdres URL obrazu.
products[].attributesobject of string | number | boolean | nullnieWszystkie pozostałe kolumny jako płaski obiekt. Najwyżej 300 kluczy po najwyżej 200 znaków; długie ciągi są ucinane do 10 000 znaków; wartości zagnieżdżone są odrzucane. Klucz nazwany jak pole najwyższego poziomu jest nadpisywany wartością z najwyższego poziomu.
products[].hintsobject: category → attribute keysnieWskazuje klasyfikacji, które atrybuty opisują co. Każdy klucz musi istnieć w attributes i może występować tylko w jednej kategorii.

Kategorie wskazówek: productDescription, material, productCategory, packaging, supplierInfo, other.

Skrzynka odbiorcza profilu mieści najwyżej 50 000 oczekujących wierszy; przesłanie ponad ten limit kończy się odpowiedzią 429 intake_full.

Odpowiedź

results są w kolejności żądania, po jednym dla produktu: uniqueId, status oraz intakeId, productId lub errors, tam gdzie mają zastosowanie.

Wyniki według statusu

statusZnaczenie
stagedNowy: czeka teraz w Skrzynce odbiorczej (intakeId).
refreshedJuż czekał; jego treść została zaktualizowana.
resurfacedZostał odrzucony ze Skrzynki odbiorczej i wrócił jako oczekujący, ponieważ jego treść się zmieniła.
unchangedJuż znany i nic się nie zmieniło.
updatedPasował do aktywnego produktu, który został zaktualizowany (productId).
updated_idlePasował do produktu zarchiwizowanego, który został zaktualizowany w miejscu i pozostaje zarchiwizowany.
invalidWiersz został odrzucony: errors zawiera listę { field, reason }.

Przyczyny invalid: required, invalid_type, too_long, not_a_gtin, too_many_attributes, unknown_category, reserved_key, unknown_attribute, assigned_twice.

summary zlicza wyniki: received, staged, refreshed, unchanged, updated, updatedIdle, archivedSkipped, invalid, duplicatesDropped. received zlicza produkty po usunięciu duplikatów; refreshed obejmuje resurfaced; archivedSkipped jest zawsze 0 i pozostawione dla starszych klientów.

Jeśli żądanie kończy się w połowie błędem 500 intake_failed, produkty przed indeksem completed zostały zapisane, a results je wymienia; pozostałe należy wysłać ponownie.

Przykładowe żądanie

Przykład: dane zmyślonecurl
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"
    }
  ]
}'

Przykładowa odpowiedź

Przykład: dane zmyśloneJSON
{
  "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"
  }
}

Błędy

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 — Błędy

GET/feed/{token}

Feed produktów

Feed produktów to stały adres URL, który zawsze udostępnia najnowsze dane aktywnych produktów jednego profilu zgodności, jako JSON, CSV lub Excel. Nie wymaga klucza API: poświadczeniem jest token w adresie URL, więc każdy, kto ma ten adres, może czytać feed, dopóki go Państwo nie unieważnią.

Tworzenie i unieważnianie linku do feedu

  1. Na platformie proszę otworzyć Tabele, wybrać „Feed” na pasku narzędzi i utworzyć link. Link przejmuje kolumny widoczne w tabeli w tej chwili; jego kolumny można później zmienić i nadać mu etykietę.
  2. Każdy link ma przyciski kopiowania dla CSV, XLSX i JSON.
  3. Unieważnienie linku działa natychmiast: następne żądanie otrzymuje 404.

Linki do feedu są dostępne w każdym planie. Dwie kolumny pakietu dla klienta są wypełniane wyłącznie w planie samoobsługowym.

Parametry zapytania

ParametrZnaczenie
formatFormat wyjściowy: json (domyślny), csv lub xlsx.
sharedZachowuje tylko produkty, które mają otwarty link udostępniający pakiet dla klienta z tą etykietą (nazwa klienta, wielkość liter bez znaczenia), i kieruje „Customer pack URL” w każdym wierszu na to udostępnienie zamiast na stały link produktu. Daje to jednemu klientowi pakiet na poziomie katalogu. Puste w bezpłatnym sprawdzeniu, które nie ma linków udostępniających.

Formaty

formatZnaczenie
jsonTablica obiektów, jeden klucz na nazwę kolumny. Kolumny strukturalne to tablice i obiekty, daty są w formacie ISO 8601, brakujące wartości to null.
csvUTF-8 z wierszem nagłówka z nazwami kolumn, rozdzielane przecinkami. Komórki z kilkoma wartościami są łączone podziałami wiersza.
xlsxJeden arkusz z tymi samymi komórkami co CSV.

Kolumny

Link udostępnia wybrane dla niego kolumny, w tej kolejności: najpierw własne zaimportowane kolumny pod ich własnymi nazwami (identyfikator, nazwa, reszta), w przeciwieństwie do API feed zawiera zaimportowane dane, a następnie kolumny Conphora:

KolumnaZnaczenie
EAN / GTIN14-cyfrowy kod kreskowy.
Commodity CodeKod HS.
Matched RegulationsKrótkie nazwy przepisów, które mają zastosowanie.
MarketsRynki, z kodem i nazwą kraju.
EN StandardsZalecane normy (na platformie wyświetlane jako „Recommended Standards”; feed zachowuje tę nazwę).
Tested forPod kątem czego według dokumentów badano produkt.
AttributesDane produktu, etykieta, wartość i jednostka.
Attributes on ProductAtrybuty umieszczane na produkcie.
Attributes on PackagingAtrybuty umieszczane na opakowaniu.
Attributes in DocumentationAtrybuty umieszczane w dokumentacji.
Attributes in Online ListingAtrybuty umieszczane w ofercie online.
Document LinksJeden wpis na dokument: tytuł, typ, obszary zgodności i link do dokumentu.
Customer pack„6 z 10 gotowych” i status każdej z dziesięciu pozycji (feed zachowuje wszystkie dziesięć; strona pakietu pokazuje pięć od początku i cztery na żądanie) (w JSON: { ready, total, items }). Puste lub null w JSON przy bezpłatnym sprawdzeniu.
Customer pack URLLink do strony pakietu dla klienta: stały link produktu lub udostępnienie klienta shared, gdy filtrują Państwo. Puste przy bezpłatnym sprawdzeniu.
CreatedKiedy produkt został utworzony.
UpdatedKiedy produkt ostatnio się zmienił.

Feed nie ma kolumny statusu zgodności, Risk Score ani kolejnego działania; są one w API. Feed nie ma numeru wersji: jego kontraktem są nazwy kolumn, a nazwy zaimportowanych kolumn odpowiadają Państwa importom.

Przykładowe żądanie

Przykład: dane zmyślonecurl
curl "https://documents.conphora.com/feed/<your-feed-token>?format=json"

Przykładowa odpowiedź

Przykład: dane zmyśloneJSON
[
  {
    "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"
  }
]

Błędy feedu to zwykły tekst, a nie JSON: 404, gdy link jest nieprawidłowy lub unieważniony, 413, gdy eksport byłby zbyt duży (CSV jest najbardziej zwartym formatem).

Limity zapytań

Odczyty i zapisy mają osobne limity, każdy liczony na klucz API i na organizację (wszystkie klucze razem). Żądanie musi spełnić oba. Podane wartości są dzisiejszymi wartościami, ustawionymi po to, by zatrzymać skrypty wymykające się spod kontroli, a nie by dławić normalne użycie.

ŻądaniaLiczone naTempoSeria
GET /api/v1/products, GET /api/v1/fieldsklucz API600 / min120
GET /api/v1/products, GET /api/v1/fieldsorganizację3,000 / min500
POST /api/v1/intakeklucz API120 / min30
POST /api/v1/intakeorganizację600 / min100

Po przekroczeniu limitu API odpowiada 429 z błędem rate_limited, polem retryAfterMs i nagłówkiem Retry-After w sekundach (co najmniej 1). Przed ponowną próbą należy odczekać tyle czasu.

Przykład: dane zmyśloneHTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 2

{
  "error": "rate_limited",
  "message": "Too many requests. Slow down and retry.",
  "retryAfterMs": 1800
}

Błędy

Każdy błąd z endpointu `/api/v1` to JSON o kształcie `{ "error": "<code>", "message": "<text>" }`, czasem z dodatkowymi polami, wysyłany ze statusem HTTP. Logikę należy opierać na `error`, nigdy na `message`. Błędna metoda lub nieznana ścieżka nie należy do tych endpointów i nie odpowiada w tym kształcie.

StatuserrorKiedyDodatkowe polaEndpointy
400missing_parameterBrak profileId, brak wartości albo brak products / pusta tablica.wszystkie
400too_many_valuesWięcej niż 100 odrębnych wartości.maxValuesGET /api/v1/products
400unknown_fieldfield nie jest identifier, name ani gtin.supportedFieldsGET /api/v1/products
400invalid_profile_idprofileId nie jest poprawnie zbudowanym identyfikatorem.wszystkie
400invalid_jsonTreść nie jest JSON.POST /api/v1/intake
400invalid_payloadTreść nie jest obiektem lub products nie jest tablicą.POST /api/v1/intake
400too_many_productsWięcej niż 100 produktów.maxProductsPOST /api/v1/intake
401missing_api_keyNie wysłano klucza.wszystkie
401invalid_api_keyKlucz jest nieznany.wszystkie
401revoked_api_keyKlucz został unieważniony.wszystkie
403insufficient_scopeKlucz read wywołał intake.POST /api/v1/intake
403profile_not_allowedKlucz jest powiązany z innym profilem.wszystkie
403membership_requiredOrganizacja nie ma aktywnego planu samoobsługowego.POST /api/v1/intake
404profile_not_foundProfil nie istnieje lub należy do innej organizacji.wszystkie
413response_too_largeWynik byłby większy niż około 18 MB. Należy poprosić o mniej wartości.GET /api/v1/products
413payload_too_largeTreść jest większa niż 1 MB.maxBodyBytesPOST /api/v1/intake
429rate_limitedOsiągnięto limit zapytań.retryAfterMs + Retry-After headerwszystkie
429intake_fullSkrzynka odbiorcza profilu przekroczyłaby 50 000 oczekujących wierszy.POST /api/v1/intake
500intake_failedŻądanie nie powiodło się w połowie; produkty przed indeksem completed zostały zapisane.completed, resultsPOST /api/v1/intake
503rate_limiter_unavailableZapisy są chwilowo niedostępne. Należy ponowić próbę po czasie z nagłówka Retry-After.Retry-After headerPOST /api/v1/intake

Wersjonowanie

  • Wersja jest w ścieżce (/api/v1) i w treści każdej odpowiedzi jako meta.apiVersion.
  • Pola mogą być dodawane w dowolnym momencie. Klienci powinni ignorować pola, których nie znają.
  • Zmiana łamiąca zgodność zmienia wersję.

meta.apiVersion: "2026-09-10"

Gotowi do połączenia?

Proszę utworzyć klucz w Ustawienia → Klucze API na platformie i wykonać pierwsze wyszukiwanie.

Utwórz klucz API