Integracje przez API
Dla działów IT i dostawców oprogramowania: wysyłka dokumentów prosto z Waszego systemu, np. programu kadrowego, księgowego, do zarządzania nieruchomościami albo własnej aplikacji. Bez ręcznego eksportu do folderu i bez logowania do panelu.
API włączamy na zapytanie. Szyfrowanie zostaje po Waszej stronie: dostarczamy bibliotekę, która szyfruje pliki w Waszym systemie, zanim trafią do nas.
Co można zrobić
- Wysłać przesyłkę do jednego albo kilku odbiorców: pliki i wiadomość są zaszyfrowane, link idzie mailem, a kod dostępu SMS-em albo drugim mailem, tak jak przy wysyłce z panelu. Możecie ustawić jawny temat, ważność i limit otwarć.
- Wysłać serię z listy CSV (do 500 wierszy): każdy odbiorca dostaje osobną przesyłkę z własnym kodem SMS. Seria zapisuje dziennik, więc po przerwaniu, np. restarcie serwera, uruchamiacie ją jeszcze raz i nikt nie dostaje przesyłki drugi raz.
- Oznaczyć przesyłkę Waszym numerem, np. numerem sprawy albo lokalu. Odbiorca go nie widzi, a Wy znajdziecie po nim przesyłkę w API i w panelu („nr w systemie”).
- Sprawdzić stan przesyłki dla każdego odbiorcy:
sent(wysłana),opened(odbiorca otworzył stronę z linku, jeszcze bez kodu),unlocked(odbiorca wpisał poprawny kod),downloaded(pliki pobrane),locked(blokada po błędnych kodach),exhausted(wykorzystany limit otwarć),expired(przesyłka wygasła),revoked(przesyłka cofnięta). - Dostawać zdarzenia na Wasz adres (webhooki) zamiast odpytywać o stan: zakończenie wysyłki, wysłanie linku i kodu albo błąd ich wysyłki, otwarcie strony, wpisanie kodu, pobranie, blokada, wygaśnięcie i inne. Każde zdarzenie jest podpisane sekretem (HMAC-SHA256) i nie zawiera adresów, nazwisk ani numerów odbiorców, tylko identyfikatory przesyłki i odbiorcy oraz Wasz numer. Gdy Wasz serwer nie odpowiada, ponawiamy przez około 3 dni.
- Wysłać link z własnej poczty: narzędzie samo wysyła mail z linkiem przez Wasz serwer poczty (SMTP z TLS, także Microsoft 365 i Google Workspace przez OAuth), z tą samą treścią co mail od nas, a kod wysyłamy dopiero po tym mailu. Może też oddać linki, które przekazujecie sami, np. z portalu. Część klucza z linku nie trafia wtedy do nas wcale.
Nowy kod, przedłużenie i cofnięcie przesyłki robi się w panelu. Przesyłki wysłane przez API widać w historii firmy razem z pozostałymi.
Szyfrowanie po Waszej stronie
API nie przyjmuje plików w postaci jawnej. Szyfruje je nasze narzędzie wb, uruchomione w
Waszym systemie, tym samym kodem co przeglądarka w panelu (format WB1, opisany publicznie). Do nas trafia tylko szyfrogram, tak jak przy
wysyłce z przeglądarki.
Narzędzie ma dwie formy:
- plik wykonywalny dla Linuksa i Windows: bez instalowania czegokolwiek, wywoływany z eksportu, skryptu albo harmonogramu zadań;
- biblioteka Node.js (od wersji 20): do wywołania z Waszego kodu.
Oba na licencji Apache-2.0, z instrukcją i sumami SHA-256 do sprawdzenia przed uruchomieniem.
Jak to wygląda
Jedna przesyłka z wiersza poleceń, z kodem SMS i Waszym numerem:
wb send umowa.pdf --to anna@example.com --name "Anna Nowak" --sms +48600100200 \
--subject "Umowa najmu" --ref najem/2026/117 Seria z listy CSV (kolumny: plik, e-mail, telefon, opcjonalnie imię i nazwisko, temat i Wasz numer).
Lista podaje nazwy plików, a --files wskazuje folder, w którym one leżą:
wb batch lista.csv --files ./wydruki --subject "Rozliczenie za listopad" Z kodu, przez bibliotekę:
import { connect, fsSource } from '@wyslijbezpiecznie/wb';
const wb = connect({ apiKey: process.env.WB_API_KEY });
const sent = await wb.send({
files: [await fsSource('wydruki/lokal-12.pdf')],
recipients: [{ name: 'Anna Nowak', email: 'anna@example.com', codeChannel: 'sms', phone: '+48600100200' }],
externalRef: 'lokal-12/2026-11',
}); Narzędzie samo ponawia żądania przy zerwanym połączeniu i nie tworzy przy tym drugiej przesyłki. Wynik w formacie JSON i kody wyjścia ułatwiają użycie w skryptach.
Klucze API i bezpieczeństwo
- System wysyła przez konto techniczne, które zakłada administrator firmy w panelu (Zespół → Integracje). Konto nie ma hasła, nie loguje się do panelu i nie zajmuje płatnego miejsca użytkownika.
- Klucz wydaje administrator po potwierdzeniu swoim hasłem i kodem weryfikacji dwuetapowej. Panel pokazuje klucz raz, a my przechowujemy tylko jego skrót.
- Klucz ma zakresy (wysyłka przesyłek, odczyt przesyłek i ich stanu, odczyt kontaktów), ważność od 30 dni do roku i opcjonalną listę adresów IP, z których działa. Przed końcem ważności administratorzy dostają przypomnienie.
- Klucz można odwołać w każdej chwili. Utworzenie i odwołanie klucza trafia do dziennika firmy, a właściciel i administratorzy dostają o nim maila.
- Ustawień firmy, zespołu, kluczy ani webhooków nie da się zmienić kluczem: zmienia je tylko administrator zalogowany do panelu.
Więcej o zabezpieczeniach serwisu: Bezpieczeństwo dla działów IT.
Co widzi odbiorca
To samo co przy wysyłce z panelu: mail z linkiem i kod. Jako nadawcę widzi Waszą firmę z rejestru i nazwę konta technicznego, np. „Dział kadr”. Odpowiedzi odbiorców i powiadomienia o przesyłkach konta (np. o blokadzie kodu) dostaje osoba z Waszego zespołu, którą wskażecie w panelu.
Warunki
- API włączamy na zapytanie, dla firmy potwierdzonej w WyślijBezpiecznie.
- We wszystkich planach, także w okresie próbnym. SMS-y z kodami liczą się do puli planu tak jak przy wysyłce z panelu (cennik).
- Zasady korzystania z API, w tym odpowiedzialność za klucze i webhooki, są w regulaminie (§ 5).
Jak zacząć
- Napiszcie do nas na kontakt@wyslijbezpiecznie.pl: krótko, z jakiego systemu chcecie wysyłać.
- Potwierdźcie firmę w panelu (zakładka Weryfikacja), jeśli jeszcze nie jest potwierdzona.
- Włączamy API i przekazujemy narzędzie z instrukcją. Administrator zakłada konto techniczne i wydaje klucz.
- Wpisujecie klucz w konfiguracji Waszego systemu i wysyłacie.
Dokumentacja
- Opis tras dostępnych kluczem API (OpenAPI): jak wygląda wysyłka bez naszego narzędzia i jakie pola zwraca odczyt przesyłek.
- Specyfikacja szyfrowania WB1 z wektorami testowymi.
- Instrukcja narzędzia
wb(polecenia, lista CSV, biblioteka, webhooki ze sprawdzaniem podpisu): przekazujemy razem z narzędziem.
Kontakt
Napiszcie na kontakt@wyslijbezpiecznie.pl albo zadzwońcie: +48 601 654 072.