Dokumenty w Codenica API

W publicznym API techniczna nazwa dokumentów to documents. Pojedynczy dokument może przedstawiać fakturę, zamówienie, umowę, protokół albo inny dokument przechowywany w Twojej bazie. W przykładach używamy dokumentu typu invoice i danych faktury przesłanych z zewnętrznego systemu.

Zanim wykonasz pierwsze żądanie, przygotuj klucz opisany w artykule Codenica API - wprowadzenie. Dalej znajdziesz kompletny przebieg pracy z dokumentami: od sprawdzenia schematu i listowania, przez utworzenie i edycję, aż po relacje, pliki, operacje batch i usunięcie rekordu.

  • pobieranie list dokumentów z paginacją, sortowaniem i filtrami;
  • odczyt danych faktur i innych typów dokumentów;
  • tworzenie i częściowa edycja rekordów;
  • ochrona zmian przez ETag i If-Match;
  • bezpieczne ponawianie operacji dzięki Idempotency-Key;
  • relacje między dokumentami oraz powiązania z innymi obiektami;
  • przesyłanie, pobieranie, podpinanie i usuwanie plików;
  • statystyki, wartości pól i operacje zbiorcze.

Wymagane pola i dostępne wartości mogą zależeć od konfiguracji Twojej bazy. Przed zapisem pobierz aktualny schemat dla typu dokumentu, z którym pracujesz.

Dokumenty - 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 dokumentów zaczynają się od:

{BASE_URL}/api/v1/documents

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

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

W domyślnej instalacji On-Premise adres lokalnie rejestrowany przez Codenica Discovery to:

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

Jeśli administrator wystawił instalację On-Premise przez firmową domenę, reverse proxy, HTTPS albo inny port zewnętrzny, 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 próbuj wskazywać 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. W produkcji korzystaj z HTTPS, gdy instalacja jest opublikowana z certyfikatem.

Dokumenty - zakresy klucza API

Klucz API utwórz w systemie Codenica w Ustawienia - API - API Keys. Nadaj mu nazwę opisującą aplikację i środowisko, a następnie wybierz tylko zakresy potrzebne do obsługi dokumentów.

Pełny przebieg z tego artykułu wymaga:

  • documents:read - listowania i odczytu dokumentów;
  • documents:write - tworzenia i edycji;
  • documents:delete - usuwania dokumentów;
  • documents:schema - odczytu pól i celów relacji;
  • documents:stats - statystyk i wartości pól;
  • documents:relationships:read i documents:relationships:write - odczytu oraz zmian relacji;
  • documents:files:read i documents:files:write - obsługi plików.

Dla integracji tylko odczytującej zwykle wystarczą documents:read i documents:schema. Zakresy statystyk, relacji i plików dodaj wtedy, gdy są potrzebne.

Pola techniczne mogą wymagać documents:technical:read, a pola sekretowe zapisu documents:secrets:write. Po utworzeniu zapisz Client ID i Client Secret w bezpiecznym magazynie. Sekret jest pokazywany tylko przy utworzeniu lub rotacji.

Dokumenty - nagłówki uwierzytelniające

Zewnętrzna aplikacja wykonuje żądania serwer-serwer przy użyciu dwóch nagłówków:

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

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

Nie używaj w integracji Bearer JWT administratora ani sesji panelu. JWT służy do logowania użytkownika do Codenica, a klucz API do połączenia zewnętrznej aplikacji z wybraną bazą. Poza środowiskiem testowym używaj HTTPS.

Nie zapisuj sekretu w repozytorium, adresie URL, logach, historii poleceń ani w kodzie wysyłanym do przeglądarki. W przykładach używamy wartości zastępczych.

Dokumenty - sprawdzenie kontekstu instalacji

Przed wykonaniem właściwych operacji 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 documents w capabilities.resources. Odczytaj także limity stron, uploadu i liczby żądań.

Zachowuj meta.requestId. Jeżeli kontekst wskazuje niewłaściwą instalację albo brakuje zakresu, zatrzymaj synchronizację i popraw adres lub klucz. Nie próbuj zmieniać bazy w body żądania.

Dokumenty - schemat pól i typów

Schemat pokazuje, które pola można odczytać i zapisać oraz jakie wartości są akceptowane w Twojej bazie:

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

W przypadku itemType=invoice sprawdź przede wszystkim wymagane pola:

Pole
Typ
Znaczenie
date
dateTime
data dokumentu
docNumber
string
numer faktury lub dokumentu

Oprócz tego schemat opisuje readable, writable, required, technical, secretWriteOnly, opcje, maksymalną długość, unikalność i reguły autogenerowania. Nie każda baza ma taki sam zestaw pól.

Pola key i keyType są sekretowe. Nie są zwracane w zwykłych odpowiedziach i nie można używać ich w filtrach, sortowaniu, statystykach ani wartościach pól. Przed wysłaniem body porównaj je ze schematem.

Dokumenty - dostępne endpointy

Poniższa mapa obejmuje główne operacje. W miejsce wartości w nawiasach wstaw identyfikatory z odpowiedzi API.

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

Odpowiedź 403 oznacza zwykle brak zakresu albo brak uprawnienia użytkownika przypisanego do klucza.

Dokumenty - listowanie i paginacja

Listę pobieraj stronicami. Przykład zwraca pierwsze dziesięć dokumentów typu invoice:

curl --request GET --url "$BASE_URL/api/v1/documents?itemType=invoice&page=1&pageSize=10&sort=date&direction=desc" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

W odpowiedzi kolekcji znajdziesz items, page, pageSize, totalItems, totalPages i hasNextPage. Kontynuuj pobieranie, dopóki hasNextPage ma wartość true. Jeżeli kolejność ma znaczenie dla synchronizacji, zawsze ustaw sortowanie.

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

Dokumenty - wyszukiwanie i filtrowanie

Przykład z testu wyszukuje dokument po własnym identyfikatorze, typie i statusie:

curl --request GET --url "$BASE_URL/api/v1/documents?itemType=invoice&customId=PUBLIC-API-DOC-20260905101715-SOURCE&status=Draft&sort=customId&direction=asc&page=1&pageSize=10" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

W zależności od schematu używaj między innymi parametrów itemType, ids, search, customId, docNumber, name, status, category, currency, createdAfter, createdBefore, updatedAfter i updatedBefore.

Do precyzyjnych warunków użyj filter:

filter=status:eq:Draft
filter=docNumber:contains:2026
filter=category:in:Procurement,Sales
filter=description:notEmpty:

Operatory obejmują eq, ne, in, contains, startsWith, endsWith, empty, notEmpty, gt, gte, lt i lte. Wartości ze spacjami i znakami specjalnymi zakoduj zgodnie z zasadami URL.

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

Parametr fields ogranicza odpowiedź do potrzebnych pól:

curl --request GET --url "$BASE_URL/api/v1/documents?itemType=invoice&fields=id,itemType,customId,docNumber,name,status,total" \
  --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/documents/$DOCUMENT_ID?include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Zakres odczytu danych dołączonych musi być przyznany osobno. Brak documents:files:read albo documents:relationships:read nie może być obchodzony przez fields=*. Pola techniczne i sekretowe są zwracane tylko wtedy, gdy pozwalają na to zakresy i schema.

Dokumenty - utworzenie rekordu

Do utworzenia dokumentu użyj POST /api/v1/documents. Typ podaj w itemType, a zapisywalne pola umieść w attributes. Poniższy przykład przedstawia fakturę przekazaną z systemu księgowego:

export IDEMPOTENCY_KEY="documents-create-20260905-0001"

curl --request POST --url "$BASE_URL/api/v1/documents" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-raw '{
    "itemType": "invoice",
    "attributes": {
      "customId": "PUBLIC-API-DOC-20260905101715-SOURCE",
      "date": "2026-09-05T10:17:15Z",
      "docNumber": "FV/2026/0001",
      "name": "Invoice from ERP",
      "category": "Procurement",
      "type": "invoice",
      "status": "Draft",
      "currency": "PLN",
      "paymentMethod": "bank_transfer",
      "total": 1250.50,
      "description": "Document imported from the external accounting system."
    }
  }'

Dla typu invoice w sprawdzonym schemacie wymagane były date i docNumber. Twoja baza może wymagać dodatkowych pól lub innych wartości. Nie wysyłaj pól tylko do odczytu ani identyfikatora id, jeśli nie wynikają ze schematu.

Poprawna odpowiedź ma status 201 Created. Zapisz data.id, ETag z nagłówka HTTP i data.meta.etag. customId ułatwia późniejsze wyszukanie dokumentu w systemie zewnętrznym.

Dokumenty - bezpieczne ponowienie utworzenia

Jeżeli po wysłaniu faktury wystąpi timeout, nie wiesz jeszcze, czy rekord został zapisany. Wyślij dokładnie to samo żądanie z tym samym Idempotency-Key i identycznym body. Nie twórz nowego klucza tylko dlatego, że pierwsza odpowiedź nie dotarła:

curl --request POST --url "$BASE_URL/api/v1/documents" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-raw '{
    "itemType": "invoice",
    "attributes": {
      "customId": "PUBLIC-API-DOC-20260905101715-SOURCE",
      "date": "2026-09-05T10:17:15Z",
      "docNumber": "FV/2026/0001",
      "name": "Invoice from ERP",
      "category": "Procurement",
      "type": "invoice",
      "status": "Draft",
      "currency": "PLN",
      "paymentMethod": "bank_transfer",
      "total": 1250.50,
      "description": "Document imported from the external accounting system."
    }
  }'

Idempotentne ponowienie zwróci ten sam dokument zamiast utworzyć duplikat. Ten sam klucz nie może później opisywać innego body, endpointu ani celu. Taka próba zwróci 422 idempotency_key_reused. Dla każdej nowej intencji użyj nowej wartości.

Dokumenty - odczyt pojedynczego rekordu

Po utworzeniu lub znalezieniu dokumentu pobierz go po UUID:

export DOCUMENT_ID="11111111-1111-1111-1111-111111111111"

curl --request GET --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID?include=files,relationships" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Odpowiedź zawiera id, itemType, pola w attributes i metadane w meta. Aktualny ETag znajdziesz w nagłówku HTTP i zwykle także w data.meta.etag oraz w kopercie meta.etag.

Przed każdą zmianą dokumentu, relacji albo pliku pobierz świeży ETag. Nie używaj wartości zapisanej wcześniej, jeżeli rekord mógł zostać zmieniony przez inną osobę lub integrację.

Dokumenty - częściowa edycja z ETagiem

PATCH zmienia wyłącznie pola przesłane w body. Wymaga aktualnej wartości If-Match i nowego Idempotency-Key:

export CURRENT_ETAG='"etag-v1"'
export UPDATE_IDEMPOTENCY_KEY="documents-update-20260905-0001"

curl --request PATCH --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID" \
  --header "Accept: application/json" \
  --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: $UPDATE_IDEMPOTENCY_KEY" \
  --data-raw '{
    "attributes": {
      "status": "Approved",
      "total": 1350.75,
      "description": "Invoice approved after verification in the accounting system."
    }
  }'

Nie musisz wysyłać całego dokumentu. Pola pominięte w body pozostają bez zmian. Po udanej operacji zapisz nowy ETag zwrócony przez API.

Dokumenty - ochrona przed nieaktualną zmianą

API odrzuca zmianę bez aktualnego ETagu. Brak nagłówka If-Match zwraca 428 if_match_required:

curl --request PATCH --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: documents-update-without-etag-0001" \
  --data-raw '{"attributes":{"status":"Approved"}}'

Jeżeli podasz stary ETag, otrzymasz 412 if_match_failed. Rekord nie zostanie zmieniony. Odczytaj dokument ponownie, sprawdź nową wersję i dopiero wtedy zdecyduj, czy ponowić własną zmianę.

{
  "status": 412,
  "code": "if_match_failed",
  "detail": "The supplied ETag is not the current document version.",
  "requestId": "request-id-from-response"
}

Ta sama zasada obowiązuje przy usuwaniu dokumentu, zmianach relacji i operacjach na plikach, jeżeli dana ścieżka zmienia rekord.

Dokumenty - relacje i zgodne cele

Dokument może być powiązany z innymi obiektami, jeżeli cel jest widoczny dla klucza i dopuszczony przez schemat. Przed wysłaniem relacji sprawdź relationshipTargets w odpowiedzi ze schematem.

W relacji podaj targetId, targetDataSet, opcjonalny targetItemType i relationshipType, jeżeli wybrany cel go obsługuje. Przykład bezpośredniego połączenia dwóch faktur:

curl --request POST --url "$BASE_URL/api/v1/documents/$DOCUMENT_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: documents-relationship-add-0001" \
  --data-raw '{
    "targetId": "22222222-2222-2222-2222-222222222222",
    "targetDataSet": "documents",
    "targetItemType": "invoice",
    "relationshipType": "related"
  }'

Nie wysyłaj targetItemType, którego rzeczywisty typ nie zgadza się z celem. Nie twórz relacji z samym sobą ani z rekordem niewidocznym dla klucza.

Dokumenty - odczyt i usunięcie relacji

Listę bieżących relacji pobierz osobno albo razem z dokumentem:

curl --request GET --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/relationships?targetDataSet=documents&targetItemType=invoice&relationshipType=related&page=1&pageSize=50" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Jeżeli chcesz usunąć jedną relację, pobierz świeży ETag dokumentu i wykonaj:

curl --request DELETE --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/relationships/documents/$TARGET_DOCUMENT_ID?relationshipType=related&targetItemType=invoice" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: documents-relationship-delete-0001"

Udane usunięcie zwraca 200 z data=true. Po operacji odczytaj listę ponownie i zapisz nowy ETag dokumentu.

Dokumenty - grupowa zmiana relacji

Jeżeli chcesz dodać i usunąć kilka relacji w jednym żądaniu, użyj relationships:batch:

curl --request POST --url "$BASE_URL/api/v1/documents/$DOCUMENT_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: documents-relationship-batch-0001" \
  --data-raw '{
    "add": [
      {
        "targetId": "33333333-3333-3333-3333-333333333333",
        "targetDataSet": "documents",
        "targetItemType": "invoice",
        "relationshipType": "related"
      }
    ],
    "remove": [
      {
        "targetId": "22222222-2222-2222-2222-222222222222",
        "targetDataSet": "documents",
        "targetItemType": "invoice",
        "relationshipType": "related"
      }
    ]
  }'

Odpowiedź podaje liczbę elementów added, removed i skipped. Używaj aktualnego ETagu także wtedy, gdy batch zawiera tylko jedną zmianę. Przy częściowym powodzeniu sprawdź wynik każdego elementu przed kolejną próbą.

Dokumenty - lista i upload pliku

Pliki są obsługiwane osobno od pól dokumentu. Najpierw odczytaj aktualną listę:

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

Prześlij plik jako multipart/form-data. Przykład tworzy plik tekstowy i ustawia go jako główny:

printf 'Invoice attachment created by the ERP integration.\n' > invoice-primary.txt
export FILE_UPLOAD_ETAG='"etag-v1"'

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

Odpowiedź zawiera id, fileName, contentType, size, relationshipType, isMain i downloadUrl. Ten URL jest ścieżką względem BASE_URL.

Dokumenty - pobranie pliku i zmiana pliku głównego

Treść pliku pobierz przez endpoint content. Użyj zapisu binarnego:

curl --request GET --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output downloaded-invoice-file

Drugi plik możesz przesłać z makeMain=false. Aby zmienić plik główny, pobierz aktualny ETag dokumentu i wywołaj:

curl --request PUT --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/files/$FILE_ID/main" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: documents-file-main-0001"

Po zmianie sprawdź listę plików. Tylko jeden plik powinien mieć isMain=true. Po tej operacji zapisz nowy ETag.

Dokumenty - podpięcie istniejącego pliku

Jeżeli plik jest już zapisany przy innym dokumencie, możesz podpiąć go do kolejnego rekordu bez ponownego uploadu:

export TARGET_DOCUMENT_ID="11111111-1111-1111-1111-111111111111"
export EXISTING_FILE_ID="44444444-4444-4444-4444-444444444444"

curl --request POST --url "$BASE_URL/api/v1/documents/$TARGET_DOCUMENT_ID/files/$EXISTING_FILE_ID?makeMain=true&relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: documents-file-attach-0001"

Podpięcie tworzy relację dokumentu z plikiem. Odpięcie przez DELETE /documents/{id}/files/{fileId} usuwa relację z tego dokumentu, ale nie kasuje pliku należącego do innego dokumentu. Usunięcie pliku z dokumentu właściciela jest osobną operacją.

Dokumenty - usunięcie pliku

Przed usunięciem pliku pobierz świeżą listę i ETag dokumentu. Jeżeli usuwasz bieżący plik główny, system może automatycznie wybrać inny plik jako główny:

curl --request DELETE --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/files/$FILE_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: documents-file-delete-0001"

Po odpowiedzi 200 zaktualizuj ETag i sprawdź listę. Usunięcie ostatniego pliku nie usuwa dokumentu, tylko pozostawia pustą kolekcję plików. Jeżeli plik był jedynie podpięty do dokumentu, usuń relację, a dopiero potem rozważ usunięcie pliku w miejscu, w którym został zapisany.

Dokumenty - statystyki i wartości pól

Statystyki pokazują rozkład danych, a endpoint values zwraca wartości przydatne do budowania filtrów:

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

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

Przykładowa odpowiedź wartości:

{
  "data": {
    "field": "status",
    "values": ["Draft", "Approved", "Paid"]
  },
  "meta": {
    "requestId": "request-id-from-response"
  }
}

Statystyki i wartości nie zmieniają danych. Nie używaj ich dla pól sekretowych ani technicznych bez odpowiedniego zakresu.

Dokumenty - operacje batch

Endpoint documents:batch pozwala utworzyć, zaktualizować i usunąć wiele dokumentów w jednym żądaniu. Operacje update i delete wymagają własnego ETag-u dla każdego elementu:

curl --request POST --url "$BASE_URL/api/v1/documents:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: documents-batch-0001" \
  --data-raw '{
    "items": [
      {
        "operation": "create",
        "create": {
          "itemType": "invoice",
          "attributes": {
            "customId": "PUBLIC-API-DOC-20260905101715-TARGET-A",
            "date": "2026-09-05T10:18:00Z",
            "docNumber": "FV/2026/0002",
            "name": "Related invoice",
            "category": "Procurement",
            "type": "invoice",
            "status": "Draft",
            "currency": "PLN",
            "paymentMethod": "bank_transfer",
            "total": 510.00
          }
        }
      },
      {
        "operation": "update",
        "id": "11111111-1111-1111-1111-111111111111",
        "ifMatch": "\"etag-v1\"",
        "update": {
          "attributes": {
            "status": "Approved"
          }
        }
      },
      {
        "operation": "delete",
        "id": "22222222-2222-2222-2222-222222222222",
        "ifMatch": "\"etag-v3\""
      }
    ]
  }'

Przy pełnym powodzeniu otrzymasz 200, a przy częściowym 207. Batch nie jest transakcją all-or-nothing. Zapisz identyfikatory, ETagi i statusy poszczególnych operacji.

Dokumenty - usunięcie rekordu

Usunięcie dokumentu jest operacją nieodwracalną z poziomu API. Pobierz aktualny ETag i sprawdź, czy UUID oraz adres bazy są prawidłowe:

curl --request DELETE --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: documents-delete-0001"

Poprawna odpowiedź zwraca 200 i data=true. Po usunięciu kolejne pobranie dokumentu zwróci 404 document_not_found. Jeżeli rekord ma relacje lub pliki, przed usunięciem zachowaj potrzebne dane poza systemem.

Dokumenty - błędy, limity i bezpieczeństwo

Błędy zwracane są w formacie Problem Details. Najważniejsze pola to status, code, detail i requestId. Logikę aplikacji opieraj na stabilnym polu code.

  • 400 - niepoprawne pola, typ dokumentu albo relacja;
  • 401 - brak lub nieprawidłowe poświadczenia;
  • 403 - brak zakresu albo uprawnienia;
  • 404 - dokument lub cel nie istnieje albo nie jest widoczny;
  • 409 - konflikt danych;
  • 412 - nieaktualny ETag;
  • 413 - plik przekracza limit;
  • 428 - brakuje If-Match lub Idempotency-Key;
  • 429 - przekroczony limit żądań;
  • 503 - usługa chwilowo niedostępna.

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. Maskuj Client Secret, sekrety dokumentów i treść plików w logach.

Dokumenty - pełny przebieg integracji

  1. Utwórz klucz w Ustawienia - API - API Keys i nadaj mu tylko zakresy potrzebne integracji.
  2. Ustaw BASE_URL na publiczny adres Codenica Cloud albo adres instalacji On-Premise przekazany przez administratora.
  3. Wyślij GET /api/v1/context i potwierdź właściwą bazę, caller, zakresy oraz limity.
  4. Pobierz GET /api/v1/documents/schema i wybierz typ dokumentu, wymagane pola oraz dopuszczalne wartości.
  5. Pobierz listę z paginacją i filtrami albo odczytaj dokument po UUID.
  6. Utwórz fakturę z unikalnym Idempotency-Key, zapisz UUID i ETag, a po timeoutcie powtórz identyczne żądanie.
  7. Aktualizuj rekord tylko z aktualnym If-Match i zapisuj nowy ETag po każdej zmianie.
  8. Dodawaj, odczytuj i usuwaj relacje zgodne ze schematem.
  9. Obsługuj pliki przez dedykowane endpointy, pamiętając o aktualnym ETagu i rozróżnieniu podpięcia od usunięcia pliku.
  10. Dla większych partii korzystaj z stats, values i documents:batch, a następnie sprawdzaj wynik każdej operacji.
  11. Przed usunięciem pobierz rekord ponownie, potwierdź właściwy ETag i użyj nowego klucza idempotencji.

Ten układ pozwala bezpiecznie przenieść obsługę faktur i pozostałych dokumentów do systemu księgowego, obiegu dokumentów, ERP albo własnej aplikacji integrującej.