Dostawcy w Codenica API

Techniczna nazwa tego zasobu w Public API to vendors, a typ zwracany przez API to vendor. Kartoteka Dostawcy przechowuje między innymi nazwę firmy, dane kontaktowe, informacje rejestrowe, status oraz opis współpracy.

Zanim wyślesz pierwsze żądanie, przygotuj klucz opisany w artykule Codenica API - wprowadzenie. Dalej znajdziesz pełny przebieg pracy z Dostawcami: od sprawdzenia schematu i listowania, przez utworzenie oraz edycję, aż po ograniczone relacje, pliki, operacje batch i usunięcie rekordu.

  • pobieranie list dostawców z paginacją, sortowaniem i filtrami;
  • odczyt tylko pól potrzebnych integracji;
  • tworzenie kartotek i częściowa edycja danych;
  • ochrona zmian przez ETag i If-Match;
  • bezpieczne ponawianie operacji dzięki Idempotency-Key;
  • relacje z celami udostępnionymi dla Dostawców w schemacie;
  • przesyłanie, pobieranie, podpinanie i usuwanie plików;
  • statystyki, wartości pól oraz operacje zbiorcze.

Wymagane pola i dostępne wartości mogą zależeć od konfiguracji Twojej bazy. Przed zapisem pobierz aktualny schemat.

Dostawcy - adres API i wybór instalacji

Żądania kieruj do publicznego adresu, pod którym dostępna jest Twoja instalacja Codenica. Nie używaj adresu samej bazy danych, kontenera ani portu dostępnego wyłącznie wewnątrz serwera. Ścieżki Dostawców zaczynają się od:

{BASE_URL}/api/v1/vendors

W Codenica Cloud użyj domeny przypisanej do Twojej instalacji:

export BASE_URL="https://twoja-firma.codenica.com"

W On-Premise bez własnej domeny Codenica Discovery zgłasza usługę pod adresem:

export BASE_URL="http://codenica.local:5150"

Jeśli administrator opublikował instalację On-Premise przez firmową domenę, reverse proxy, HTTPS albo inny port, użyj dokładnego adresu przekazanego dla tej instalacji:

export BASE_URL="https://api.twoja-firma.example"

Właściwa baza jest wybierana na podstawie adresu hosta. Nie wskazuj jej przez tenantId, dodatkowe pole w query stringu ani wartość w body. Nie używaj localhost, jeśli program integrujący działa na innym komputerze niż API.

BASE_URL nie powinien zawierać końcowego /api/v1:

# Codenica Cloud:
export BASE_URL="https://twoja-firma.codenica.com"

# Domyślne On-Premise z Codenica Discovery:
# export BASE_URL="http://codenica.local:5150"

# On-Premise z adresem opublikowanym przez administratora:
# export BASE_URL="https://api.twoja-firma.example"

Dostawcy - klucz API i zakresy dostępu

Klucz dla zewnętrznej integracji utwórz w systemie Codenica w Ustawienia - API - API Keys. Nadaj mu nazwę opisującą aplikację, środowisko i przeznaczenie, na przykład Zakupy - Dostawcy - produkcja. Następnie wybierz tylko zakresy potrzebne danej integracji i zapisz jednorazowo pokazany Client ID oraz Client Secret w bezpiecznym magazynie sekretów.

Pełny przebieg opisany w tym artykule wymaga:

  • vendors:read, vendors:write i vendors:delete - odczyt, tworzenie, edycja i usuwanie;
  • vendors:schema - schemat pól i celów relacji;
  • vendors:stats - statystyki i wartości pól;
  • vendors:relationships:read oraz vendors:relationships:write - odczyt i zmiana relacji;
  • vendors:files:read oraz vendors:files:write - obsługa plików.

Jeżeli integracja wyszukuje Dokumenty lub inne cele relacji, dodaj odpowiedni zakres odczytu, na przykład documents:read. Sam zakres relacji Dostawców nie zastępuje dostępu do obiektu docelowego.

Dla integracji tylko odczytującej zwykle wystarczą:

vendors:read
vendors:schema

Limity kluczy wynikają z licencji:

Licencja
Public API
Maksymalna liczba kluczy
Starter
niedostępne
0
Plus
dostępne
50
Enterprise
dostępne
100

Panel API przechowuje klucze utworzone dla Twojej bazy. Oddzielny klucz dla każdej aplikacji i środowiska ułatwia kontrolę dostępu, wymianę sekretu oraz usunięcie jednej integracji bez przerywania pracy pozostałych. Usunięty klucz nie może już uwierzytelniać żądań i nie jest liczony jako aktywny.

Client Secret jest wyświetlany tylko przy utworzeniu lub rotacji. Nie zapisuj go w repozytorium, adresie URL, logach, historii poleceń ani w kodzie działającym w przeglądarce.

Dostawcy - uwierzytelnianie i nagłówki żądań

Połączenie integracji z Dostawcami opiera się na dwóch nagłówkach identyfikujących klucz:

export CLIENT_ID="cna_twoj_client_id"
export CLIENT_SECRET="cns_twoj_client_secret"

curl --request GET --url "$BASE_URL/api/v1/vendors" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

W tym scenariuszu nie przekazuj JWT administratora ani cookies z panelu. Integracja korzysta z klucza API przypisanego do tej bazy, a na publicznym adresie produkcyjnym powinna pracować przez HTTPS.

Każda operacja zmieniająca dane wymaga unikalnego nagłówka:

Idempotency-Key: public-api-vendors-create-20260905111218

Aktualizacje, usuwanie, zmiany relacji i operacje plikowe wymagają bieżącego ETag-u rekordu:

If-Match: "aktualny-etag-dostawcy"

Po każdej udanej zmianie zapisz nowy ETag zwrócony w nagłówku i w data.meta.etag. Przy ponowieniu tej samej logicznej operacji zachowaj ten sam Idempotency-Key i identyczne body.

Dostawcy - sprawdzenie kontekstu instalacji

Przed rozpoczęciem synchronizacji pobierz kontekst:

curl --request GET --url "$BASE_URL/api/v1/context" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Sprawdź w odpowiedzi apiVersion, contractVersion, identyfikator bazy, tenant.resolvedDomain, caller.authentication równe api_key, wymagane zakresy oraz vendors w capabilities.resources. Odczytaj także limity stron, plików, batch i rate limitu.

Przy pełnej obsłudze powinny być dostępne między innymi supportsBatch, supportsRelationships, supportsFiles, supportsETag i supportsIdempotency. Zachowuj meta.requestId z każdej odpowiedzi. Jest potrzebny przy analizie błędu i kontakcie z administratorem.

Jeżeli kontekst wskazuje inną bazę albo brakuje potrzebnego zakresu, zatrzymaj synchronizację i popraw adres lub klucz. Nie próbuj zmieniać bazy w body żądania.

Dostawcy - schemat pól i celów relacji

Pobierz schemat przed pierwszym zapisem:

curl --request GET --url "$BASE_URL/api/v1/vendors/schema" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

W odpowiedzi data.itemType ma wartość vendor. Schemat opisuje typ pola, możliwość odczytu i zapisu, wymagalność, długość maksymalną, unikalność i autogenerowanie. W aktualnym schemacie pole name jest wymagane i może mieć maksymalnie 300 znaków:

Pole
Typ
Wymagane
Limit
Przykładowe znaczenie
name
string
tak
300
nazwa dostawcy

Najczęściej używane pola należą do kilku grup:

  • identyfikacja: customId, name, displayName, type, category, role, status;
  • lokalizacja: location, department, address, city, country, state, zipCode;
  • kontakt: email, phone, phoneWork, phoneMobile, contactName, contactPhone, contactMobile, contactEmail;
  • rejestry i oznaczenia: website, tag, taxId, idNumber, registryNumber, link, number;
  • opis i status: comments, description, notification, value, isLicensed, isVerified.

Schema zwraca także katalog celów relacji. W aktualnym modelu Dostawców są to documents, notes, worktasks i requesteditems. Nie zakładaj, że wszystkie zasoby widoczne w kontekście mogą być celem relacji Dostawcy.

Dostawcy - mapa endpointów

Mapa niżej porządkuje operacje na kartotece Dostawcy. Symbole w nawiasach zastąp UUID-ami zwróconymi przez wcześniejsze odpowiedzi.

  • GET /api/v1/vendors - lista;
  • GET /api/v1/vendors/schema - schemat pól i relacji;
  • GET /api/v1/vendors/stats - statystyki;
  • GET /api/v1/vendors/values - wartości pól;
  • GET /api/v1/vendors/{id} - pojedyncza kartoteka;
  • POST /api/v1/vendors - utworzenie;
  • PATCH /api/v1/vendors/{id} - częściowa edycja;
  • DELETE /api/v1/vendors/{id} - usunięcie;
  • POST /api/v1/vendors:batch - operacje create, update i delete;
  • GET /api/v1/vendors/{id}/relationships - lista relacji;
  • POST /api/v1/vendors/{id}/relationships - dodanie relacji;
  • POST /api/v1/vendors/{id}/relationships:batch - grupowa zmiana relacji;
  • DELETE /api/v1/vendors/{id}/relationships/{targetDataSet}/{targetId} - usunięcie relacji;
  • GET /api/v1/vendors/{id}/files - lista plików;
  • POST /api/v1/vendors/{id}/files - upload pliku;
  • POST /api/v1/vendors/{id}/files/{fileId} - podpięcie istniejącego pliku;
  • PUT /api/v1/vendors/{id}/files/{fileId}/main - ustawienie głównego pliku;
  • DELETE /api/v1/vendors/{id}/files/{fileId} - usunięcie pliku;
  • GET /api/v1/vendors/{id}/files/{fileId}/content - pobranie treści.

Jeśli endpoint zwróci 403, sprawdź najpierw zakres przypisany do klucza, a następnie uprawnienia jego właściciela.

Dostawcy - listowanie, sortowanie i paginacja

Listę pobieraj stronicami. Przykład zwraca pierwsze dwadzieścia kartotek i ustala kolejność po nazwie:

curl --request GET --url "$BASE_URL/api/v1/vendors?page=1&pageSize=20&sort=name&direction=asc" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Koperta kolekcji zwraca items, page, pageSize, totalItems, totalPages oraz hasNextPage. Gdy hasNextPage ma wartość true, pobierz następną stronę; synchronizację powtarzalną wykonuj z jawnym sortowaniem.

Limit pageSize odczytaj z kontekstu. Nie zakładaj, że pierwsza strona zawiera wszystkie rekordy ani że domyślna kolejność pozostanie taka sama.

Dostawcy - wyszukiwanie i filtrowanie

Po utworzeniu rekordu możesz odszukać go po własnym identyfikatorze i statusie:

curl --request GET --url "$BASE_URL/api/v1/vendors?customId=PUBLIC-API-VEN-20260905111218-SOURCE&status=Active&sort=customId&direction=asc&page=1&pageSize=10" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Do wyszukiwania tekstowego użyj search:

curl --request GET --url "$BASE_URL/api/v1/vendors?search=technology&page=1&pageSize=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

W zależności od schematu możesz używać między innymi parametrów ids, search, name, displayName, email, status, category, type, role, location, department, customId, tag, createdAfter, createdBefore, updatedAfter i updatedBefore.

Do dokładniejszych warunków użyj filter:

filter=status:eq:Active
filter=name:contains:Technology
filter=category:in:Technology,Hardware
filter=description:notEmpty:

Dostępne operatory pozwalają porównywać wartości, szukać fragmentów tekstu, wybierać jedną z kilku wartości oraz sprawdzać puste pola. W zapytaniach URL zakoduj spacje i znaki specjalne, zanim przekażesz filtr do API.

Dostawcy - wybór pól i dołączanie danych

Parametr fields ogranicza odpowiedź do potrzebnych pól:

curl --request GET --url "$BASE_URL/api/v1/vendors?fields=id,itemType,customId,displayName,email,status" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Do odczytu plików i relacji razem z rekordem użyj include:

curl --request GET --url "$BASE_URL/api/v1/vendors/a8156781-3b1c-4fa5-9cf2-05077e5d1399?fields=customId,displayName,email,status,description&include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Odpowiedź może zawierać żądane atrybuty oraz kolekcje files i relationships. Zakres odczytu danych dołączonych musi być przyznany osobno. Brak vendors:files:read albo vendors:relationships:read nie może być obchodzony przez fields=*.

Dostawcy - utworzenie kartoteki

Do utworzenia rekordu użyj POST /api/v1/vendors. Zapisywalne pola umieść w attributes. Minimalny zapis wymaga pola name, ale w praktyce warto od razu przekazać identyfikator używany w systemie źródłowym i podstawowe dane kontaktowe:

{
  "attributes": {
    "customId": "ERP-VENDOR-2026-001",
    "name": "Northwind Technology Services",
    "displayName": "Northwind Technology Services",
    "email": "[email protected]",
    "category": "Technology",
    "type": "Supplier",
    "role": "Supplier",
    "status": "Active",
    "description": "Dostawca usług infrastruktury IT."
  }
}
curl --request POST --url "$BASE_URL/api/v1/vendors" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-vendors-create-erp-vendor-2026-001" \
  --data @vendor-create.json

Poprawna odpowiedź ma status 201 Created. Zapisz data.id, data.meta.etag oraz nagłówek HTTP ETag. W przykładzie z demonstracyjnej kartoteki API zwróciło itemType: vendor i identyfikator a8156781-3b1c-4fa5-9cf2-05077e5d1399.

Dostawcy - bezpieczne ponowienie utworzenia

Jeżeli po wysłaniu żądania wystąpi timeout albo utracisz odpowiedź, nie twórz od razu nowej kartoteki. Powtórz dokładnie ten sam request z tym samym kluczem:

Idempotency-Key: public-api-vendors-create-erp-vendor-2026-001

Body musi być identyczne, a klucz powinien należeć tylko do tej jednej logicznej operacji. Powtórzenie z tym samym kluczem nie utworzy drugiego Dostawcy. Nie używaj go do innej kartoteki, aktualizacji ani usunięcia.

Idempotencja dotyczy operacji zmieniających dane. Każdy nowy zapis powinien otrzymać nowy, unikalny klucz.

Dostawcy - odczyt pojedynczej kartoteki

Po utworzeniu odczytaj rekord po UUID zwróconym przez API:

VENDOR_ID="a8156781-3b1c-4fa5-9cf2-05077e5d1399"

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Odpowiedź 200 OK zawiera data.itemType: vendor, a bieżący ETag znajduje się w nagłówku HTTP oraz w data.meta.etag. Identyfikatora z systemu źródłowego nie używaj zamiast UUID, chyba że najpierw wyszukasz po nim rekord.

Dostawcy - częściowa edycja z ETagiem

Najpierw pobierz rekord i użyj zwróconego ETag-u. PATCH zmienia tylko pola przekazane w attributes:

CURRENT_ETAG='"ao_LJiJqs-uhBu9oDENCFJH6JY8qwbl_vt77Gl5cjGQ"'

curl --request PATCH --url "$BASE_URL/api/v1/vendors/$VENDOR_ID" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-update-20260905111218" \
  --data '{"attributes":{"displayName":"Northwind Technology Services - dział zakupów","description":"Dane dostawcy zaktualizowane przez integrację."}}'

Udana odpowiedź ma status 200 OK. Nie zmieniaj pól, których nie chcesz aktualizować. Po sukcesie zastąp zapisany ETag nową wartością, na przykład "ek44P2KnmKSAB1xX4Ycs_NgIn0I3NLoDdqsezEUgBTY".

Dostawcy - ochrona przed nadpisaniem zmian

Jeżeli dwa procesy pobrały tę samą kartotekę, drugi może mieć już nieaktualną wersję. Public API odrzuci taką zmianę kodem if_match_failed i statusem 412 Precondition Failed:

{
  "type": "https://docs.codenica.com/errors/if_match_failed",
  "title": "Precondition failed.",
  "status": 412,
  "detail": "The supplied ETag is not the current vendor version.",
  "code": "if_match_failed"
}

Brak nagłówka If-Match przy aktualizacji albo usuwaniu zwróci 428 Precondition Required z kodem if_match_required. Po 412 lub 428 pobierz rekord ponownie, sprawdź bieżący stan i dopiero wtedy zdecyduj, czy ponowić zmianę. Nie wysyłaj losowego ETag-u.

Dostawcy - ograniczony katalog relacji

Nie każdy obiekt dostępny w systemie może być celem relacji Dostawcy. Źródłem prawdy jest relationshipTargets zwrócone przez /api/v1/vendors/schema. W aktualnym modelu są to:

documents
notes
worktasks
requesteditems

Dostawcy nie łącz z clients ani assets. Nie zakładaj także obsługi innego zbioru tylko dlatego, że pojawia się w capabilities.resources. Lista zasobów dostępnych w instalacji jest szersza niż lista celów relacji konkretnego obiektu.

Relacje obiektowe Dostawców nie używają pola relationshipType. Nie wysyłaj go w body i nie dopisuj relationshipType=related do query stringu. Jeżeli w endpointach plików pojawia się relationshipType=documentation albo relationshipType=manual, jest to wyłącznie metadana pliku i nie oznacza relacji Dostawcy z innym obiektem.

Dostawcy - dodanie i odczyt relacji

Przed zmianą pobierz świeży ETag Dostawcy. Body relacji zawiera cel, zbiór i - gdy wymaga tego obiekt docelowy - jego targetItemType:

{
  "targetId": "31fe2881-6236-4100-9a87-2c018cbaf709",
  "targetDataSet": "documents",
  "targetItemType": "warranty"
}
curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-document-a-20260905111218" \
  --data '{"targetId":"31fe2881-6236-4100-9a87-2c018cbaf709","targetDataSet":"documents","targetItemType":"warranty"}'

Udane dodanie zwraca 201 Created. Relacje odczytasz osobnym żądaniem:

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships?targetDataSet=documents&page=1&pageSize=50" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

W odpowiedzi znajdziesz między innymi targetId, targetDataSet, targetItemType, customId i status. Lista relacji nie zawiera parametru relationshipType.

Dostawcy - relacje batch i usuwanie powiązania

Do jednoczesnego dodania lub usunięcia kilku relacji użyj relationships:batch:

{
  "add": [
    {
      "targetId": "31eed973-79cf-4650-ac0e-1e3ef5513d9f",
      "targetDataSet": "documents",
      "targetItemType": "warranty"
    }
  ],
  "remove": []
}
curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-batch-20260905111218" \
  --data @vendor-relationships-batch.json

Wynik zawiera liczniki added, removed i skipped. Pojedynczą relację usuń przez:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships/documents/31fe2881-6236-4100-9a87-2c018cbaf709" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-delete-20260905111218"

Nie dodawaj relationshipType. Po operacji ponownie pobierz listę, aby potwierdzić stan relacji.

Dostawcy - lista plików

Pliki są osobną kolekcją przypisaną do kartoteki Dostawcy:

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files?page=1&pageSize=50" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Pusta kolekcja zwraca między innymi items: [], totalItems: 0 i hasNextPage: false. Po każdej operacji plikowej warto odczytać listę, ponieważ to ona pokazuje rzeczywiste wartości isMain, relationshipType, rozmiaru i adresu pobierania.

Dostawcy - wysłanie pliku

Przed wysłaniem pobierz bieżący ETag Dostawcy. Upload wykonuje się jako żądanie multipart:

curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files?makeMain=true&relationshipType=documentation" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-upload-20260905111218" \
  --form "[email protected];type=text/plain"

W tym endpointcie relationshipType=documentation opisuje plik, a nie relację obiektową. Odpowiedź 201 Created zawiera między innymi identyfikator pliku, nazwę, typ treści, rozmiar i downloadUrl. Po uploadzie potwierdź przez listę, czy plik ma isMain: true.

Limit wysyłania odczytaj z data.capabilities.limits.maxUploadBytes. W przykładowej instalacji wynosił 20971520 bajtów.

Dostawcy - pobranie pliku i zmiana pliku głównego

Treść pliku pobierzesz przez adres z downloadUrl albo równoważny endpoint:

FILE_ID="025222b9-abef-4bad-a2ba-28229a0d73fb"

curl --request GET --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output vendors-primary-downloaded.txt

Odpowiedź powinna mieć 200 OK, właściwy Content-Type i nagłówek Content-Disposition. Aby dodać drugi plik bez zmiany głównego, użyj makeMain=false i na przykład relationshipType=manual. Następnie ustaw go jako główny:

curl --request PUT --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/cc182dea-47d3-4ca2-818b-c639cde5a124/main" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-set-main-20260905111218"

Po ponownym odczycie listy nowy plik ma isMain: true, a poprzedni isMain: false.

Dostawcy - podpięcie istniejącego pliku

Plik zapisany przy jednym Dostawcy możesz podpiąć do kolejnej kartoteki bez ponownego uploadu. To operacja plikowa, więc parametr relationshipType jest tutaj metadaną pliku:

TARGET_VENDOR_ID="4bfece8f-5bb3-438c-a95b-f14ccf93cce3"
TARGET_ETAG='"l5sRayy308rVRi4PNmUReFFcJGowi0KZUi8-hOGGlr0"'

curl --request POST --url "$BASE_URL/api/v1/vendors/$TARGET_VENDOR_ID/files/2a1f9727-0990-405d-b22c-fbd93273cc6e?makeMain=true&relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TARGET_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-attach-20260905111218"

Odpięcie usuwa podłączenie u Dostawcy docelowego, ale nie usuwa pliku z kartoteki właściciela:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$TARGET_VENDOR_ID/files/2a1f9727-0990-405d-b22c-fbd93273cc6e" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TARGET_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-detach-20260905111218"

Po odpięciu sprawdź listę plików zarówno u Dostawcy docelowego, jak i u właściciela.

Dostawcy - usunięcie pliku

Usunięcie pliku również wymaga aktualnego ETag-u kartoteki:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/cc182dea-47d3-4ca2-818b-c639cde5a124" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-delete-20260905111218"

Jeżeli usuwasz bieżący plik główny, system może automatycznie wybrać inny pozostający plik jako główny. Po odpowiedzi 200 OK ponownie pobierz listę i sprawdź totalItems oraz isMain. Usunięcie podłączenia nie jest tym samym co usunięcie pliku właściciela.

Dostawcy - statystyki i wartości pól

Statystyki pomagają sprawdzić rozkład danych w kartotekach:

curl --request GET --url "$BASE_URL/api/v1/vendors/stats?field=status&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Wynik może zawierać liczbę wszystkich rekordów, nazwę pola i wartości z licznikami. Dane są zwracane zgodnie z zawartością Twojej bazy. Na przykład wartości active, Active i aktywny mogą oznaczać różne wpisy, jeśli pochodzą z różnych źródeł.

Do budowania podpowiedzi filtrów użyj endpointu values:

curl --request GET --url "$BASE_URL/api/v1/vendors/values?field=status&search=Act&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Statystyki i wartości są operacjami tylko do odczytu i nie zmieniają danych.

Dostawcy - batch tworzenia

Batch pozwala utworzyć kilka kartotek w jednym żądaniu. Każdy element zawiera operation: create oraz obiekt create:

{
  "items": [
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "ERP-VENDOR-BATCH-A",
          "name": "Northwind Batch A",
          "email": "[email protected]",
          "category": "Technology",
          "type": "Supplier",
          "role": "Supplier",
          "status": "Active"
        }
      }
    },
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "ERP-VENDOR-BATCH-B",
          "name": "Northwind Batch B",
          "email": "[email protected]",
          "category": "Technology",
          "type": "Supplier",
          "role": "Supplier",
          "status": "Active"
        }
      }
    }
  ]
}
curl --request POST --url "$BASE_URL/api/v1/vendors:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-vendors-batch-create-20260905111218" \
  --data @vendors-batch-create.json

Wynik zawiera status całego żądania oraz status każdej operacji w data.items. Przy udanym batchu odpowiedź może mieć 200 OK, succeeded: 2, failed: 0 i dwa elementy ze statusem 201. Każdy nowy UUID i ETag zachowaj osobno.

Dostawcy - batch aktualizacji, usuwania i częściowego powodzenia

Aktualizacja w batchu wymaga id, bieżącego ifMatch i obiektu update:

{
  "items": [
    {
      "operation": "update",
      "id": "76d1698d-dfdb-47a3-9d84-3e476fa7894c",
      "ifMatch": "ETAG_FROM_GET",
      "update": {
        "attributes": {
          "displayName": "Northwind Batch A - aktualizacja",
          "description": "Zmiana wykonana w operacji batch Dostawców."
        }
      }
    },
    {
      "operation": "invalid"
    }
  ]
}

Jeżeli jedna operacja się powiedzie, a inna będzie niepoprawna, API zwróci 207 Multi-Status. Nie traktuj 207 jako całkowitej porażki ani pełnego sukcesu. Przetwórz każdy element data.items osobno. Usuwanie wymaga tej samej zasady, czyli identyfikatora i aktualnego ifMatch:

{
  "operation": "delete",
  "id": "9462d541-c405-44bf-9c75-000d8b862136",
  "ifMatch": "ETAG_FROM_GET"
}

Po batch delete wykonaj kontrolny GET. Usunięta kartoteka powinna zwrócić 404 z kodem vendor_not_found.

Dostawcy - usunięcie kartoteki

Przed usunięciem pobierz rekord ponownie, aby mieć aktualny ETag:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-delete-20260905111218"

Udane usunięcie zwraca 200 OK i data: true. Kolejne pobranie zwróci 404 Not Found z kodem vendor_not_found. Po usunięciu możesz także wykonać listę filtrowaną po własnym customId i potwierdzić totalItems: 0.

Jeśli odpowiedź DELETE została utracona, nie wysyłaj pochopnie nowej operacji z innym kluczem. Zachowaj pierwotny Idempotency-Key, sprawdź stan rekordu i dopiero potem zdecyduj o dalszym działaniu.

Dostawcy - błędy, limity i pełny przebieg integracji

Błędy Public API mają format Problem Details. Logikę aplikacji opieraj na stabilnym polu code, a przy zgłoszeniu problemu zachowaj requestId.

  • 400 - niepoprawne pole, cel relacji albo element batch;
  • 401 - brak lub nieprawidłowe poświadczenia;
  • 403 - brak zakresu albo uprawnienia;
  • 404 - kartoteka, plik lub cel nie istnieje albo nie jest widoczny;
  • 409 - konflikt danych lub unikalności;
  • 412 - nieaktualny ETag;
  • 413 - plik przekracza limit;
  • 422 - błąd walidacji domenowej;
  • 428 - brak If-Match lub Idempotency-Key;
  • 429 - przekroczony limit żądań;
  • 207 - batch wykonany częściowo.

Odczytuj X-RateLimit-Limit i X-RateLimit-Remaining. Przy 429 zastosuj Retry-After, jeśli został zwrócony, oraz opóźnienie rosnące przy kolejnych próbach. Nie loguj X-Codenica-Client-Secret, sekretów ani wrażliwych treści plików.

Praktyczna kolejność pracy:

  1. Ustaw BASE_URL właściwej instalacji.
  2. Utwórz klucz w Ustawienia - API - API Keys z minimalnymi zakresami.
  3. Pobierz /api/v1/context i /api/v1/vendors/schema.
  4. Utwórz Dostawcę z unikalnym Idempotency-Key, zachowaj UUID i ETag.
  5. Odczytuj listy z paginacją, filtrami i opcjonalnym include.
  6. Aktualizuj rekord wyłącznie z bieżącym If-Match.
  7. Dodawaj relacje tylko do celów zwróconych przez schema i bez relationshipType.
  8. Obsługuj pliki osobnymi endpointami, po każdej zmianie sprawdzając ich listę.
  9. Dla większych partii analizuj wynik każdej operacji batch.
  10. Przed usunięciem pobierz aktualny ETag i wykonaj kontrolny GET po DELETE.

Przykłady używają demonstracyjnego prefiksu PUBLIC-API-VEN-20260905111218. Własna integracja musi korzystać z identyfikatorów otrzymanych z Twojej bazy, a nie z wartości pokazanych na stronie.