Integracja z SaldeoSMART przez API - warto wiedzieć – Centrum pomocy SaldeoSMART

Dla kogo dostępne jest API SaldeoSMART

Jeśli Twoje biuro rachunkowe lub firma korzysta z własnych systemów lub chce zautomatyzować wymianę danych z SaldeoSMART, możesz to zrobić za pomocą API. Ten artykuł opisuje, jak zacząć: gdzie znaleźć token, jak zbudować adres żądania i na co zwrócić uwagę przy uprawnieniach.

Korzystanie z API jest całkowicie bezpłatne.
Dostęp mają wyłącznie użytkownicy kont typu biuro.

⚠️ Dostępność API jest ograniczona do określonych pakietów Saldeo (Specjalista, Ekspert) i nie jest dostępna dla pakietu Asystent Firmy.

Jak zacząć

Zapoznaj się z dokumentacją API – pełny opis poleceń znajdziesz w dokumentacji: aby przejść do dokumentacji kliknij w link 👉 Dokumentacja API SaldeoSMART.
Wygeneruj lub odczytaj token API – zaloguj się na konto biura, przejdź do zakładki Konfiguracja → Konto → API. Token znajdziesz w polu "Token".

Jak zbudować adres żądania

Adres, na który wysyłasz polecenie, składa się z trzech elementów:

Adres serwera Saldeo – Saldeo udostępnia kilka serwerów: produkcyjny, testowy i prezentacyjny.
Ścieżka polecenia – znajdziesz ją w opisie danego polecenia w dokumentacji.
Numer wersji polecenia – umieszczony w ścieżce.

⚠️ Uwaga zmiana: od 2026 roku minimalna obsługiwana wersja API to 2.0. Zalecamy jednak od razu korzystać z wersji 3.0.

Przykład: dodanie firmy na serwerze produkcyjnym

Polecenie z dokumentacji:

SS01. Dodanie firmy do Saldeo, dana COMPANY (S)

POST /api/xml/1.0/company/create

Budowa adresu:

Adres serwera produkcyjnego: https://saldeo.brainshare.pl
Ścieżka polecenia z właściwą wersją: /api/xml/3.0/company/create
Pełny adres żądania: https://saldeo.brainshare.pl/api/xml/3.0/company/create

Uprawnienia

Do wykonania większości poleceń API wystarczy login "zwykłego" użytkownika.
Dwa polecenia wymagają użycia loginu i tokena administratora:
- company/create (SS01)
- company/synchronize (SS15)
Uprawnienia przypisane do danego loginu w aplikacji webowej działają analogicznie w API.

⚠️ Jeśli integracja ma służyć do generowania lub wystawiania faktur sprzedaży, administrator firmy musi dodatkowo włączyć taką możliwość w aplikacji webowej: Konfiguracja → Konfiguracja faktur → Możliwość wystawiania faktur przez API poprzez Biuro Rachunkowe.

Częste pytania

1. Jak wyliczyć parametr "req_sig" (sumę kontrolną)?

Zbierz wszystkie parametry żądania (w tym command oraz ewentualny załącznik, przekonwertowany zgodnie z dokumentacją) i posortuj je alfabetycznie według nazwy parametru.
Połącz je w jeden ciąg w formacie nazwa=wartość, bez żadnych łączników między elementami (np. command=123company_program_id=456...).
Zakoduj cały ciąg funkcją urlEncode. Zwróć uwagę, żeby znak = był zamieniany na %3D (wielkie litery), a nie na %3d.
Na końcu zakodowanego ciągu dopisz token API (samą wartość tokena).
Wylicz hash MD5 z całego ciągu – to jest szukany req_sig.

Przykład dla polecenia document/list:

Polecenie przyjmuje dwa parametry: req_id i username.

Po posortowaniu i połączeniu:

req_id=20260420095123username=michals-odczyt

Token API można dopisać teraz albo już po urlEncode – token zawiera tylko litery i cyfry, więc urlEncode nie zmieni jego zapisu. Zakładając, że token to Je1:

req_id=20260420095123username=michals-odczytJe1

Po urlEncode:

req_id%3D20260420095123username%3Dmichals-odczytJe1

Po MD5:

29383449b4fc7c2f38fa4e8d36b9c54f

To jest oczekiwana wartość req_sig dla tego żądania.