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
- Na platformie proszę otworzyć Ustawienia → Klucze API i utworzyć klucz, nadając mu nazwę do własnego użytku.
- 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ć. - Jeśli organizacja ma dwa lub więcej profili zgodności, klucz można powiązać z jednym z nich.
- 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.
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
| Zakres klucza | Znaczenie |
|---|---|
read | GET /api/v1/products i GET /api/v1/fields. Ustawienie domyślne. |
read_write | Wszystko, 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
profileIdkoń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
| Parametr | Typ | Wymagany | Domyślnie | Znaczenie |
|---|---|---|---|---|
profileId | string | tak | Profil 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. | |
values | string (comma-separated or repeated) | tak | Wartoś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. | |
value | string | alias | Akceptowany jako alias values i łączony z nim. | |
field | identifier | name | gtin | nie | identifier | Czym 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. |
includeArchived | true | nie | false | Uwzglę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 jakovalue_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 tonot_a_gtin.name: najpierw dokładna nazwa, potem wyszukiwanie ignorujące wielkość liter i interpunkcję.- Gdy pasuje więcej niż jeden produkt, wynikiem jest
ambiguouswraz z kandydatami. API nigdy nie zgaduje: należy ponowić zapytanie zidentifierwybranego kandydata. - Przy
field=identifierwartość, która nie jest jeszcze produktem, ale czeka w Skrzynce odbiorczej, wraca jakostaged.
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
status | Pole | Znaczenie |
|---|---|---|
found | value, matchedVia, product | Dopasowano dokładnie jeden produkt. |
not_found | value, archivedMatchCount (only when > 0) | Brak dopasowania. |
staged | value, inbox { status: pending | dismissed, receivedAt } | Czeka w Skrzynce odbiorczej, nie jest jeszcze śledzony, więc nie ma jeszcze stanu zgodności. |
ambiguous | value, matches [{ id, identifier, name }] | Dopasowano kilka produktów. |
ambiguous_truncated | value | Wyszukiwanie osiągnęło limit kandydatów. Należy zawęzić wartość lub użyć identifier. Nie może wystąpić przy field=gtin. |
invalid_value | value, reason: empty_value | value_too_long | value_precision_unsupported | not_a_gtin | Wartoś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.
| Pole | Typ | Znaczenie |
|---|---|---|
id | string | Stały identyfikator produktu w Conphora. Nie jest wartością do wyszukiwania. |
profileId | string | Profil zgodności. |
identifier | string | Własny identyfikator produktu. |
identifierField | string | null | Nazwa kolumny identyfikatora w imporcie. |
gtin | string | null | Kod kreskowy jako 14 cyfr, uzupełniony zerami; null, gdy import nie zawierał prawidłowego kodu kreskowego. |
name | string | Nazwa produktu. |
imageUrl | string | null | Adres URL obrazu z importu. |
hsCode | string | null | Kod HS / kod towarowy. |
archived | boolean | True dla produktu zarchiwizowanego. |
status.classification | in_progress | awaiting_clarification | completed | failed | null | Na jakim etapie jest klasyfikacja; null, gdy jeszcze się nie rozpoczęła. |
status.compliance | not_checked | compliant | requires_compliance | Stan zgodności. Nigdy null: not_checked, gdy produkt nigdy nie był oceniany. |
compliance.lastCheckedAt | number (ms epoch) | null | Kiedy produkt był ostatnio oceniany. |
compliance.summary.matchedCount | number | Ile wymagań ma zastosowanie. |
compliance.summary.fulfilledCount | number | Ile 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. |
riskScore | integer 0–100 | null | Risk Score Conphora: priorytet, a nie werdykt. Null, dopóki produkt nie zostanie oceniony. |
riskBand | low | watch | high | critical | null | Pasmo wyniku. Null, gdy nie ma wyniku. |
nextAction | object | null | Jedno kolejne działanie. Null, gdy nie ma wyniku lub nie ma nic do zrobienia. |
nextAction.kind | string (see the list below) | Co zrobić. |
nextAction.who | you | supplier | Do kogo należy ruch. |
nextAction.href | string (relative platform path) | Względna ścieżka na platformie, która otwiera działanie. Należy ją otwierać na hoście platformy. |
nextAction.after | number | Risk Score po wykonaniu tego działania. |
customerPack | object | null | Pakiet 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.ready | integer 0–10 | Ile z dziesięciu pozycji jest gotowych. |
customerPack.total | 10 | Zawsze 10. |
customerPack.items | object: item id → ready | missing | waiting | not-needed | Status każdej pozycji, w kolejności pakietu. not-needed = żadna część pozycji nie dotyczy produktu. |
customerPack.url | string | null | Peł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.path | string | null | Ten sam link jako ścieżka /p/<token> na hoście dokumentów. |
createdAt | number (ms epoch) | Kiedy produkt został utworzony w Conphora. |
updatedAt | number (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.
riskBand | Wynik | Znaczenie |
|---|---|---|
low | 0-24 | Monitorowane, nic do zrobienia |
watch | 25-49 | Coś się zbliża |
high | 50-74 | Do poprawy w tym miesiącu |
critical | 75-100 | Dział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.
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
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ź
{
"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
| Parametr | Typ | Wymagany | Znaczenie |
|---|---|---|---|
profileId | string | tak | Profil zgodności. |
Odpowiedź
| Pole | Typ | Znaczenie |
|---|---|---|
profile.id | string | Identyfikator profilu. |
profile.name | string | Nazwa profilu. |
identifierField | string | null | Jak najnowszy import nazywa kolumnę identyfikatora. |
supportedFields | string[] | Zawsze ["identifier", "name", "gtin"]. |
meta.apiVersion | string | Wersja API. |
Przykładowe żądanie
curl "https://documents.conphora.com/api/v1/fields?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c" \
-H "x-api-key: cfa_live_…" Przykładowa odpowiedź
{
"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
| Pole | Typ | Wymagany | Znaczenie |
|---|---|---|---|
profileId | string | tak | Docelowy profil zgodności. |
products | array (1–100) | tak | Produkty. Późniejszy duplikat uniqueId jest odrzucany (wygrywa pierwszy) i liczony. |
products[].uniqueId | string | number | tak | Własny identyfikator produktu, najwyżej 512 znaków po przycięciu. |
products[].name | string | tak | Nazwa produktu (najwyżej 10 000 znaków). |
products[].description | string | tak | Opis produktu. Klasyfikacja Conphora go potrzebuje. |
products[].gtin | string | number | nie | Kod kreskowy. Jeśli jest podany, musi być prawidłowym GTIN, w przeciwnym razie wiersz jest odrzucany z not_a_gtin. |
products[].imageUrl | string | nie | Adres URL obrazu. |
products[].attributes | object of string | number | boolean | null | nie | Wszystkie 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[].hints | object: category → attribute keys | nie | Wskazuje 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
status | Znaczenie |
|---|---|
staged | Nowy: czeka teraz w Skrzynce odbiorczej (intakeId). |
refreshed | Już czekał; jego treść została zaktualizowana. |
resurfaced | Został odrzucony ze Skrzynki odbiorczej i wrócił jako oczekujący, ponieważ jego treść się zmieniła. |
unchanged | Już znany i nic się nie zmieniło. |
updated | Pasował do aktywnego produktu, który został zaktualizowany (productId). |
updated_idle | Pasował do produktu zarchiwizowanego, który został zaktualizowany w miejscu i pozostaje zarchiwizowany. |
invalid | Wiersz 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
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ź
{
"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
- 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ę.
- Każdy link ma przyciski kopiowania dla CSV, XLSX i JSON.
- 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
| Parametr | Znaczenie |
|---|---|
format | Format wyjściowy: json (domyślny), csv lub xlsx. |
shared | Zachowuje 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
format | Znaczenie |
|---|---|
json | Tablica 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. |
csv | UTF-8 z wierszem nagłówka z nazwami kolumn, rozdzielane przecinkami. Komórki z kilkoma wartościami są łączone podziałami wiersza. |
xlsx | Jeden 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:
| Kolumna | Znaczenie |
|---|---|
EAN / GTIN | 14-cyfrowy kod kreskowy. |
Commodity Code | Kod HS. |
Matched Regulations | Krótkie nazwy przepisów, które mają zastosowanie. |
Markets | Rynki, z kodem i nazwą kraju. |
EN Standards | Zalecane normy (na platformie wyświetlane jako „Recommended Standards”; feed zachowuje tę nazwę). |
Tested for | Pod kątem czego według dokumentów badano produkt. |
Attributes | Dane produktu, etykieta, wartość i jednostka. |
Attributes on Product | Atrybuty umieszczane na produkcie. |
Attributes on Packaging | Atrybuty umieszczane na opakowaniu. |
Attributes in Documentation | Atrybuty umieszczane w dokumentacji. |
Attributes in Online Listing | Atrybuty umieszczane w ofercie online. |
Document Links | Jeden 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 URL | Link do strony pakietu dla klienta: stały link produktu lub udostępnienie klienta shared, gdy filtrują Państwo. Puste przy bezpłatnym sprawdzeniu. |
Created | Kiedy produkt został utworzony. |
Updated | Kiedy 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
curl "https://documents.conphora.com/feed/<your-feed-token>?format=json" Przykładowa odpowiedź
[
{
"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.
| Żądania | Liczone na | Tempo | Seria |
|---|---|---|---|
GET /api/v1/products, GET /api/v1/fields | klucz API | 600 / min | 120 |
GET /api/v1/products, GET /api/v1/fields | organizację | 3,000 / min | 500 |
POST /api/v1/intake | klucz API | 120 / min | 30 |
POST /api/v1/intake | organizację | 600 / min | 100 |
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.
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.
| Status | error | Kiedy | Dodatkowe pola | Endpointy |
|---|---|---|---|---|
| 400 | missing_parameter | Brak profileId, brak wartości albo brak products / pusta tablica. | wszystkie | |
| 400 | too_many_values | Więcej niż 100 odrębnych wartości. | maxValues | GET /api/v1/products |
| 400 | unknown_field | field nie jest identifier, name ani gtin. | supportedFields | GET /api/v1/products |
| 400 | invalid_profile_id | profileId nie jest poprawnie zbudowanym identyfikatorem. | wszystkie | |
| 400 | invalid_json | Treść nie jest JSON. | POST /api/v1/intake | |
| 400 | invalid_payload | Treść nie jest obiektem lub products nie jest tablicą. | POST /api/v1/intake | |
| 400 | too_many_products | Więcej niż 100 produktów. | maxProducts | POST /api/v1/intake |
| 401 | missing_api_key | Nie wysłano klucza. | wszystkie | |
| 401 | invalid_api_key | Klucz jest nieznany. | wszystkie | |
| 401 | revoked_api_key | Klucz został unieważniony. | wszystkie | |
| 403 | insufficient_scope | Klucz read wywołał intake. | POST /api/v1/intake | |
| 403 | profile_not_allowed | Klucz jest powiązany z innym profilem. | wszystkie | |
| 403 | membership_required | Organizacja nie ma aktywnego planu samoobsługowego. | POST /api/v1/intake | |
| 404 | profile_not_found | Profil nie istnieje lub należy do innej organizacji. | wszystkie | |
| 413 | response_too_large | Wynik byłby większy niż około 18 MB. Należy poprosić o mniej wartości. | GET /api/v1/products | |
| 413 | payload_too_large | Treść jest większa niż 1 MB. | maxBodyBytes | POST /api/v1/intake |
| 429 | rate_limited | Osiągnięto limit zapytań. | retryAfterMs + Retry-After header | wszystkie |
| 429 | intake_full | Skrzynka odbiorcza profilu przekroczyłaby 50 000 oczekujących wierszy. | POST /api/v1/intake | |
| 500 | intake_failed | Żądanie nie powiodło się w połowie; produkty przed indeksem completed zostały zapisane. | completed, results | POST /api/v1/intake |
| 503 | rate_limiter_unavailable | Zapisy są chwilowo niedostępne. Należy ponowić próbę po czasie z nagłówka Retry-After. | Retry-After header | POST /api/v1/intake |
Wersjonowanie
- Wersja jest w ścieżce (
/api/v1) i w treści każdej odpowiedzi jakometa.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"