Dokumentacja API

Klucz API tworzysz w „Konto i faktury” (plan Pro albo Biuro BHP). Klucz identyfikuje konto — odpowiedzi obejmują tylko firmy tego konta. Wszystkie odpowiedzi są w JSON, daty w formacie RRRR-MM-DD.

Uwierzytelnianie

Nagłówek Authorization: Bearer bhp_… w każdym zapytaniu.

curl -H "Authorization: Bearer bhp_TWOJ_KLUCZ" \
  https://behapro.pl/api/v1/organizations

Endpointy

Metoda i ścieżka	Zakres	Co zwraca / przyjmuje
`GET /organizations`	read	firmy konta: id, name, nip, city
`GET /employees?organization_id=`	read	kartoteka bez PESEL i adresu; opcjonalnie `&status=zatrudniony`
`POST /employees`	write	upsert pracowników (dopasowanie: employee_number, e-mail, imię i nazwisko); stanowisko po nazwie
`GET /trainings?organization_id=`	read	rejestr szkoleń BHP
`GET /medical?organization_id=`	read	badania: typ, daty, status (bez treści orzeczeń)
`GET /deadlines?organization_id=&days=90`	read	terminy z centralnego rejestru

Przykład: dopisanie pracowników

curl -X POST https://behapro.pl/api/v1/employees \
  -H "Authorization: Bearer bhp_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "UUID_FIRMY",
    "employees": [
      { "employee_number": "K-001", "first_name": "Jan", "last_name": "Nowak",
        "position": "Magazynier", "hired_at": "2026-10-01", "email": "jan@firma.pl" }
    ]
  }'
# -> { "created": 1, "updated": 0, "errors": [] }

Webhooki

Zdarzenie deadline.due wysyłamy raz dziennie razem z przypomnieniami e-mail. Ciało to JSON, podpis HMAC-SHA256 sekretu w nagłówku X-Behapro-Signature (format sha256=<hex>) liczony z surowego ciała. Odbiorca powinien odpowiedzieć kodem 2xx w ciągu 8 sekund.

POST https://twoj-system.pl/hook
X-Behapro-Event: deadline.due
X-Behapro-Signature: sha256=3f1a…

{
  "event": "deadline.due",
  "created_at": "2026-10-01T05:00:00.000Z",
  "data": {
    "organizations": [
      { "organization_id": "…", "organization_name": "Bistro Pod Lipą",
        "deadlines": [ { "id": "…", "entity_type": "badanie", "title": "Badanie lekarskie - Jan Nowak",
                         "due_at": "2026-10-15", "days_left": 14 } ] }
    ]
  }
}

Limity: 500 pracowników w jednym POST, brak innych limitów w tej wersji. Klucz można unieważnić w każdej chwili.

Błędy: 401 (brak/zły klucz), 403 (brak zakresu albo firma spoza konta), 400 (niepoprawne dane), 500 (błąd serwera).