Użytkownicy — przebieg integracji¶

Wszystkie ścieżki poniżej są względne wobec /partner/v1/users. Uwierzytelnienie: x-client-id i x-api-key przy każdym wywołaniu, a dodatkowo x-user-id przy wszystkich poza zakładaniem konta.

Zasada ogólna¶

Użytkownik zakładany przez API jest bytem należącym wyłącznie do integracji. Nie ma konta logowania i nie może zalogować się do aplikacji PetAssist — dostęp do jego danych odbywa się tylko przez to API, w oparciu o klucz integracji.

Zwrócony id jest jedynym identyfikatorem potrzebnym później: trafia do nagłówka x-user-id przy każdym kolejnym wywołaniu i to on decyduje, czyje dane są odczytywane i modyfikowane.

Krok 1 — założenie użytkownika¶

POST /partner/v1/users
{ "email": "anna.kowalska@example.com", "name": "Anna", "surname": "Kowalska" }

surname jest opcjonalne. To jedyny endpoint, który nie wymaga x-user-id — w tym momencie użytkownik jeszcze nie istnieje.

Odpowiedź:

{
  "id": "3f2b…",
  "email": "anna.kowalska@example.com",
  "name": "Anna",
  "surname": "Kowalska",
  "language": "pl",
  "marketId": "fca4…",
  "birth_date": null,
  "phone_code": null,
  "phone": null,
  "country_id": null,
  "address": null,
  "image_id": null,
  "image_src": null,
  "createdAt": "2026-09-08T10:15:00.000Z",
  "alreadyExisted": false
}

language i marketId biorą się z konfiguracji integracji, nie z żądania. Pozostałe pola profilu są puste przy zakładaniu konta — uzupełnia się je aktualizacją.

Język użytkownika¶

language to język ustawiony na integracji, ten sam dla wszystkich zakładanych przez nią użytkowników. Nie przyjmujemy go w ciele żądania i nie da się go później zmienić — PATCH /users/me nie ma takiego pola, a nieznane pole kończy się 400.

Ma to znaczenie tylko wtedy, gdy partner obsługuje użytkowników mówiących różnymi językami. W takim wypadku jedynym mechanizmem jest nagłówek x-language, przesyłany przy każdym wywołaniu — profil pozostaje wtedy bez znaczenia.

Język integracji ustawiamy przy jej zakładaniu; do wyboru są pl i en.

Wywołanie jest idempotentne¶

Ponowne wysłanie tego samego adresu nie tworzy duplikatu — zwracany jest istniejący użytkownik z alreadyExisted: true. Dzięki temu ponowienie żądania po przerwanym połączeniu jest bezpieczne.

Ten sam adres może istnieć w PetAssist niezależnie¶

Jeśli pod tym adresem istnieje już samodzielne konto PetAssist, nie jest ono przejmowane ani łączone. Powstaje osobny użytkownik należący do integracji, a oba byty pozostają niezależne: mają osobne zwierzaki, osobną historię i osobne dane. Właściciel konta PetAssist nie zobaczy danych wprowadzonych przez integrację i odwrotnie.

Krok 2 — odczyt profilu¶

GET /partner/v1/users/me

Zwraca ten sam kształt co zakładanie konta, dla użytkownika wskazanego w x-user-id. Przydatne do sprawdzenia, czy identyfikator jest nadal aktywny.

Krok 3 — aktualizacja profilu¶

PATCH /partner/v1/users/me
{ "name": "Anna", "surname": "Nowak", "phone_code": "+48", "phone": "600100200" }

Pola do aktualizacji: name (wymagane), surname, birth_date, phone_code, phone, country_id, address, image_id, image_src.

Wszystkie wracają też w odpowiedzi i w GET /me, więc formularz edycji można wypełnić danymi z odczytu, a zapis potwierdzić bez dodatkowego wywołania.

email nie podlega zmianie — jest ustalany przy zakładaniu konta.
image_src przyjmuje ścieżkę zwróconą przy wgrywaniu pliku (patrz dokumentacja plików); zdjęcie profilowe jest publiczne.

Odpowiedź ma ten sam kształt co GET /me.

Krok 4 — usunięcie danych¶

DELETE /partner/v1/users/me

{ "id": "3f2b…", "erased": true }

Służy do realizacji żądania usunięcia danych. Usuwa wszystkie pola identyfikujące użytkownika — adres e-mail, imię, nazwisko, telefon, adres, datę urodzenia, zdjęcie — i zamyka konto.

Operacja jest nieodwracalna. Po jej wykonaniu każde wywołanie z tym x-user-id zostanie odrzucone kodem 401. Jeśli ten sam użytkownik ma wrócić, trzeba założyć go od nowa — otrzyma nowy identyfikator i nie odzyska poprzednich danych.

Czego to API nie robi¶

Nie wysyłamy żadnych powiadomień do użytkowników integracji. Ani e-maili, ani SMS-ów, ani powiadomień push. Wszystkie zdarzenia, które w aplikacji PetAssist skutkowałyby powiadomieniem, trafiają wyłącznie na webhook — treść, kanał i preferencje użytkownika pozostają po stronie partnera.

Z tego powodu API nie udostępnia ustawień powiadomień: nasze kanały nie są używane, a kanałów partnera nie znamy.

Nie ma limitów wynikających z abonamentu. Użytkownicy integracji mają pełny i nieograniczony dostęp do udostępnionego zakresu funkcji. Decyzja o tym, kto może korzystać z usługi, zapada po stronie partnera — wywołanie naszego API z danym identyfikatorem traktujemy jako potwierdzenie uprawnienia.

Najczęstsze przyczyny błędów¶

Objaw	Przyczyna
`401` przy wywołaniu z `x-user-id`	Użytkownik nie należy do tej integracji albo został usunięty
`401` bez `x-user-id`	Nagłówek pominięty — wymagany wszędzie poza zakładaniem konta
Powstał duplikat użytkownika	Ten sam adres wysłany z innej integracji — użytkownicy nie są współdzieleni między integracjami
Zmiana `email` nie działa	Adres jest niezmienny po założeniu konta

Przykładowa sekwencja¶

POST   /partner/v1/users        { "email": "...", "name": "..." }   → zapamiętaj `id`
GET    /partner/v1/users/me     (x-user-id: <id>)
PATCH  /partner/v1/users/me     { "name": "...", "phone": "..." }

… dalsza praca: zwierzaki, książeczka zdrowia, prediagnoza, żywienie, czat …

DELETE /partner/v1/users/me     — na żądanie usunięcia danych