DLA FIRM I TWÓRCÓW INTEGRACJI · WERSJA 1

Twoje realizacje.
Prosto z Twojego systemu.

Przesyłaj tytuły, opisy i zdjęcia do portfolio firmy. Ten sam wpis możesz później edytować w panelu lub przez API. Szkic jest prywatny, a publikacja jest osobnym krokiem.

1. Utwórz klucz firmy

W panelu wybierz firmę, następnie API → Utwórz klucz API. Potrzebujesz potwierdzonego konta, zatwierdzonego prawa do reprezentacji firmy i zatwierdzonego zakresu usług. Klucz jest przypisany do jednego NIP-u. Pełną wartość zobaczysz tylko raz.

Wybierz dostęp do odczytu albo odczytu, edycji i publikacji. Klucz wygasa najpóźniej po 365 dniach; można go wcześniej unieważnić. Cofnięcie uprawnień, zawieszenie firmy lub blokada konta zatrzymuje API również dla istniejącego klucza.

Authorization: Bearer $GZ_API_TOKEN
Accept: application/json

Łącz się wyłącznie przez HTTPS. Klucz przechowuj na serwerze integracji, poza publicznym JavaScriptem i adresami URL. API nie korzysta z ciasteczek logowania.

2. Sprawdź firmę i dozwolone branże

curl --fail-with-body \
  -H "Authorization: Bearer $GZ_API_TOKEN" \
  "https://godny-zaufania.pl/api/v1/companies/$NIP"

Odpowiedź zawiera data.branches, czyli wartości do pola branch, zakres klucza i limity. NIP przekazuj jako tekst złożony z 10 cyfr.

3. Wyślij treść realizacji

Zapisz poniższy obiekt jako realizacja.json. Treść ma te same części co kreator portfolio: potrzeba klienta, uzgodniony zakres, wykonana praca i rezultat. Na początek szkicu wystarczą title oraz branch.

{
  "title": "Sprawdzenie hamulców przed dalszą trasą",
  "branch": "mechanik",
  "problem": "Klient chciał ustalić przyczynę hałasu podczas hamowania.",
  "scope": "Uzgodniliśmy oględziny układu bez wymiany części.",
  "work": "Sprawdziliśmy elementy układu i zapisaliśmy wyniki kontroli.",
  "result": "Omówiliśmy wyniki i uzgodniliśmy dalszy zakres naprawy.",
  "date": "2026-09-20",
  "duration": "2 godziny"
}

curl --fail-with-body -D odpowiedz.headers \
  -H "Authorization: Bearer $GZ_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $UNIKALNY_KLUCZ_ZADANIA" \
  --data-binary @realizacja.json \
  "https://godny-zaufania.pl/api/v1/companies/$NIP/portfolio"

Odpowiedź 201 zawiera identyfikator data.id, numer data.version, nagłówek ETag i Location. Wszystkie daty odpowiedzi są w UTC. Pola tekstowe są zwykłym tekstem, bez formatowania HTML.

4. Dodaj zdjęcia

Przesyłaj po jednym zdjęciu w polu photo, kolejno, używając ETag z ostatniej odpowiedzi. Wybierz stage: before (przed), during (w trakcie) albo after (efekt). Podpis caption ma od 8 do 180 znaków.

curl --fail-with-body \
  -H "Authorization: Bearer $GZ_API_TOKEN" \
  -H 'If-Match: "2"' \
  -H "Idempotency-Key: $UNIKALNY_KLUCZ_ZDJECIA" \
  -F 'photo=@efekt.jpg' -F 'stage=after' \
  -F 'caption=Elementy układu po zakończonej kontroli.' \
  "https://godny-zaufania.pl/api/v1/companies/$NIP/portfolio/$ID/photos"

Do 12 zdjęć na realizację, każde JPG, PNG lub WebP do 2 MiB i 20 megapikseli; najmniejszy wymiar to 16 pikseli. Serwer tworzy WebP do 1600 px i usuwa metadane. Limity firmy: 100 MiB oraz 600 zachowanych zdjęć. Nie pobieramy zdjęć ze zdalnych adresów URL. Po każdym zdjęciu odpowiedź zawiera pełne data.photos i nowy ETag.

5. Opublikuj na wizytówce

curl --fail-with-body \
  -H "Authorization: Bearer $GZ_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: $UNIKALNY_KLUCZ_PUBLIKACJI" \
  --data '{"rights_confirmed":true,"privacy_confirmed":true}' \
  "https://godny-zaufania.pl/api/v1/companies/$NIP/portfolio/$ID/publish"

Wymagane są prawa do materiałów i sprawdzenie prywatności. Publikacja wymaga kompletnego opisu i podpisów zdjęć. Odpowiedź zawiera działający data.public_url. Branże poufne i publikacje wstrzymane przez moderację zachowują dotychczasowe ograniczenia.

Wszystkie operacje

Adresy poniżej poprzedź /api/v1/companies/{nip}.

Przesunięcie zdjęcia: {"move":"up"} lub {"move":"down"}. Okładka: PATCH /portfolio/{id} z {"cover":"ID_ZDJECIA"}. Prywatne zdjęcia wymagają nagłówka Authorization. Publikowanie i wycofanie nie wysyła wiadomości do klientów.

Pola opisu

JSON do 32 KiB. Nieznane pola, tablice zamiast tekstu i przekroczenia długości są odrzucane. Pola opcjonalne czyści się pustym tekstem, a nie wartością null.

Ponowienia i równoczesna edycja

Każdy zapis wymaga Idempotency-Key: 16–128 znaków, litery, cyfry, kropka, podkreślenie, dwukropek lub myślnik. Użyj UUID osobnego dla każdej operacji. Przy błędzie sieci ponów tę samą operację z tym samym kluczem, danymi i If-Match. Przez 24 godziny zwrócimy pierwotny wynik bez ponownego zapisu. Nagłówek Idempotency-Replayed: true oznacza takie ponowienie. Klucze ponowień są wspólne dla integracji jednej firmy. Po 24 godzinach nie ma gwarancji usunięcia duplikatów; nowa operacja wymaga nowego klucza.

Każda zmiana istniejącej realizacji wymaga If-Match z jej aktualnym ETag, łącznie z uploadem, usunięciem i publikacją. 412 oznacza zmianę wpisu przez inną operację. Odczytaj bieżący wpis, porównaj zmiany i wykonaj nową operację z nowym kluczem ponowienia. Wynik ponowionego żądania może opisywać starszą wersję; aktualny stan zawsze daje GET.

Limity i błędy

120 żądań na minutę na klucz, 300 na firmę i adres IP; 30 uploadów na minutę na firmę; 1000 udanych zapisów firmy w ciągu 24 godzin. Przy 429 respektuj nagłówek Retry-After. Wysyłaj zdjęcia kolejno. Rotację klucza wykonasz, tworząc nowy, przełączając integrację i unieważniając poprzedni.

{"error":{"code":"version_conflict","message":"Realizacja została zmieniona…","fields":[]},"request_id":"…"}

400 — format żądania; 401 — brak lub nieaktywny klucz; 403 — uprawnienia lub weryfikacja; 404 — brak zasobu; 409 — konflikt ponowienia lub stan publikacji; 412 — nieaktualna wersja; 413 — za duży plik lub JSON; 415 — format treści; 422 — walidacja; 428 — brak If-Match; 429 — limit. Przy zgłoszeniu błędu podaj X-Request-Id, bez klucza API.