--- title: "Profil konta — API v1 i MCP | Dokumentacja Nodea" description: "Pełny reference profilu konta: endpointy REST API v1 (GET/PATCH /profile — dane, adres, VAT z re-walidacją VIES), zakres account:read/write, narzędzia MCP profile-get/profile-update i przykłady curl oraz JSON-RPC." url: "https://nodea.pl/pl/dokumentacja-api/profile" lang: "pl" updated: "2026-07-16" --- # Profil konta — API v1 i MCP | Dokumentacja Nodea > Reference profilu konta — endpointy API v1 (GET/PATCH /profile: dane, firma, adres, VAT z re-walidacją VIES, strefa czasowa), zakresy account:read/write, narzędzia MCP profile-get/profile-update i przykłady. Moduł **Profil konta** obejmuje odczyt i częściową aktualizację profilu użytkownika tokenu: dane identyfikacyjne, firmę i adres rozliczeniowy, profil VAT (kraj, status firmy, numer VAT z walidacją VIES), numer podatkowy oraz strefę czasową. Dokument opisuje warstwę REST API v1 (/api/v1/profile) oraz narzędzia MCP profile-get i profile-update. ## Uwierzytelnianie i zakresy (scopes) API v1 uwierzytelnia się osobistym tokenem Passport przez nagłówek Authorization: Bearer \. Profil operuje **wyłącznie na użytkowniku tokenu** — nie przyjmuje żadnych identyfikatorów, więc nie istnieje powierzchnia cross-tenant. - account:read — odczyt profilu (GET /profile). - account:write — częściowa aktualizacja (PATCH /profile). Profil jest **niebramkowany żadną flagą Pennant** — dostęp do konta nigdy nie jest feature-flagowany (tak samo jak w web UI). Limit zapytań: throttle:api-v1 = 240/min na użytkownika tokenu. ## Co jest świadomie pominięte (web-only) Wrażliwe, wymagające potwierdzenia operacje pozostają wyłącznie w web UI i **nie są** eksponowane przez API v1: - zmiana adresu **e-mail**, - zmiana **hasła**, - zarządzanie **2FA** (dwuskładnikowe uwierzytelnianie), - odłączenie dostawcy **OAuth**, - upload **awatara**, - zmiana **waluty rozliczeniowej** (w web zablokowana blokadą zerowego salda portfeli). Pole email jest zwracane w odczycie, ale PATCH /profile nie posiada dla niego reguły — jego przesłanie jest ignorowane (pole nie jest częścią validated()). W odróżnieniu od tego narzędzie MCP profile-update **jawnie odrzuca** email i password błędem walidacji (patrz sekcja MCP) oraz — inaczej niż API — potrafi zmienić walutę. ## Profil a konto osobiste (dane rozliczeniowe) Profil pozostaje **profilem użytkownika** — endpointy nie zależą od kontekstu konta (nagłówek X-Account-Id ich nie zmienia) i nie wymagają uprawnienia konta. Nabywcą na fakturach jest jednak **konto klienta** (patrz [Konta klientów](https://nodea.pl/pl/dokumentacja-api/accounts)), dlatego po każdym zapisie PATCH /profile pola rozliczeniowe, które się zmieniły (imię i nazwisko, firma, adres, kraj, status firmy, numer VAT / NIP i wynik walidacji VIES), są kopiowane na **konto osobiste** użytkownika — konto, którego jest właścicielem, rozliczane przez Nodea (najpierw konto domyślne, w przeciwnym razie najstarsze). Kopiowane są tylko pola zmienione w danym zapisie, więc np. zmiana strefy czasowej nie nadpisze danych edytowanych w profilu konta. Synchronizacja **nigdy** nie zapisuje konta zaimportowanego z WHMCS (źródłem prawdy jest tam WHMCS) ani konta, w którym użytkownik jest tylko członkiem. Docelowym miejscem edycji danych do faktury jest profil konta w panelu. ## API v1 — endpointy MetodaŚcieżkaScopeOpisGET/api/v1/profileaccount:readProfil użytkownika tokenu (dane, firma, adres, VAT, strefa czasowa, język locale, waluta). PATCH/api/v1/profileaccount:writeCzęściowa aktualizacja dowolnego podzbioru pól ogólnych i VAT. Zwraca zaktualizowany profil. ### GET /profile — odpowiedź Zwraca ProfileResource — pola: id, name, email, company\_name, address, country, is\_company (bool), vat\_number, vat\_validated (bool), vat\_validated\_at (ISO 8601 lub null), tax\_number, timezone, locale (pl|en lub null — preferowany język użytkownika: interfejsu web oraz wszystkich wysyłanych do niego e-maili i powiadomień, także wywołanych przez inną osobę lub przez API), currency (PLN|EUR), created\_at. **Nigdy** nie zwraca sekretów, stanu 2FA, hashy hasła/remember, wierszy dostawców OAuth ani flag administracyjnych. ### PATCH /profile — parametry ciała Każda reguła nosi sometimes — klient może wysłać dowolny podzbiór pól; pominięte pola pozostają nietknięte (partial update). - name (string, sometimes|required, max 255) — przesłana nazwa nie może być pusta. - company\_name (string|null, max 255). - address (string|null, max 1000). - tax\_number (string|null, max 64). - timezone (string|null, reguła timezone — identyfikator IANA). - locale (string|null, in:pl,en — preferowany język interfejsu oraz e-maili i powiadomień; null usuwa preferencję). - country (string|null, size:2 — ISO 3166-1 alpha-2). - is\_company (boolean). - vat\_number (string|null, max 32). **Waluta nie jest przyjmowana przez API** — zmiana currency jest web-only (i dostępna w MCP). Pola ogólne (name, company\_name, address, tax\_number, timezone, locale) są zapisywane tylko, gdy obecne w ładunku. ### Profil VAT i re-walidacja VIES Przesłanie **któregokolwiek** z pól country / is\_company / vat\_number unieważnia poprzednią walidację VIES: vat\_validated jest ustawiane na false, a vat\_validated\_at na null. Następnie, gdy efektywny profil (przesłane wartości nałożone na zapisane) jest firmą (is\_company = true) z jednocześnie ustawionym krajem i numerem VAT, wykonywany jest round-trip do **VIES** (ViesValidator). Kraj i numer VAT są normalizowane (upper-case, trim). Jak w web: nieudany lookup VIES **i tak zapisuje** przesłane wartości — pole vat\_validated pozostaje po prostu false (brak gałęzi odwrotnego obciążenia). VIES używa SOAP (nie fasady Http) i poza produkcją domyślnie działa w trybie sandbox (billing.vies.sandbox). ### Kody błędów - 401 — brak/niepoprawny token. - 403 — brak wymaganego scope (account:read przy GET, account:write przy PATCH). - 422 — walidacja (np. pusty name, country spoza size:2, nieprawidłowa strefa czasowa, locale inne niż pl/en). ## Przykłady — API ### Odczyt profilu curl -s https://app.nodea.io/api/v1/profile \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Aktualizacja danych ogólnych i strefy czasowej curl -s -X PATCH https://app.nodea.io/api/v1/profile \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "name": "Jan Kowalski", "company\_name": "Kowalski sp. z o.o.", "address": "ul. Przykładowa 1, 00-001 Warszawa", "timezone": "Europe/Warsaw" }' ### Ustawienie profilu VAT (wyzwala re-walidację VIES) curl -s -X PATCH https://app.nodea.io/api/v1/profile \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "is\_company": true, "country": "PL", "vat\_number": "PL1234567890" }' ## MCP — narzędzia Narzędzia MCP dzielą model uwierzytelniania i zakresów z API v1 (Bearer + scope sprawdzany w ensureScope). Profil jest niebramkowany flagą, więc oba narzędzia są zawsze widoczne w tools/list. Operują wyłącznie na użytkowniku tokenu. NarzędzieScopeTrybOpisprofile-getaccount:readread-onlyZwraca profil: name, email, company\_name, adres, country, status firmy/VAT, tax\_number, strefę czasową, preferowany język (locale: pl|en lub null) i walutę. Bez poświadczeń i stanu 2FA. profile-updateaccount:writeidempotentneCzęściowa aktualizacja; tylko przesłane pola się zmieniają. Dodatkowo obsługuje currency. Odrzuca email/password. Zmienione pola rozliczeniowe kopiuje na konto osobiste (jak API). ### profile-get Bez parametrów. Odpowiedź jest nadzbiorem ProfileResource — te same pola plus effective\_timezone (rozwiązana strefa czasowa użytkownika, gdy timezone jest null). ### profile-update — parametry Wszystkie opcjonalne; zmieniają się tylko przesłane. Puste stringi / null czyszczą pole (blank → null), kraj i numer VAT są upper-case. - name (string, max 255). - company\_name (string, max 255; null/pusty czyści). - address (string, max 1000; null/pusty czyści). - tax\_number (string, max 64; null/pusty czyści). - timezone (string — identyfikator IANA; null czyści). - locale (enum pl|en — preferowany język interfejsu oraz e-maili i powiadomień; null czyści). - country (string — ISO 3166-1 alpha-2; null czyści). - is\_company (boolean). - vat\_number (string, max 32; null/pusty czyści). - currency (enum PLN|EUR) — **zablokowana**, gdy którykolwiek portfel ma niezerowe saldo (zwraca błąd narzędzia); zmiana jest logowana do dziennika aktywności. **Różnice względem API:** zmiana pól VAT (country/is\_company/vat\_number) na wartość różną od zapisanej resetuje vat\_validated (i vat\_validated\_at), ale to narzędzie **nie wykonuje** round-tripu do VIES — ponowną walidację przeprowadza web UI. Przesłanie email lub password kończy się błędem walidacji (reguła prohibited: „The email address / password can only be changed in the web UI.”), a nie cichym zignorowaniem jak w API. Tak jak PATCH /profile, narzędzie po zapisie kopiuje zmienione pola rozliczeniowe na konto osobiste użytkownika — nigdy na konto WHMCS ani konto, w którym użytkownik jest tylko członkiem. ### Przykład — MCP (JSON-RPC) { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "profile-get", "arguments": {} } } { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "profile-update", "arguments": { "is\_company": true, "country": "PL", "vat\_number": "PL1234567890", "timezone": "Europe/Warsaw" } } } ## Powiązane - [Zgłoszenia (tickets) — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/tickets) - [Rozliczenia (billing) — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/billing) - [Konta klientów — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/accounts) --- Wersje językowe: [en](https://nodea.io/en/api-docs/profile.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)