API PDWD - dokumentacja

Zanim zaczniesz

Ekorejestr nie ma gotowych integracji z konkretnymi systemami. To aplikacja urzędu, działająca lokalnie lub w innym portalu, łączy się z API Ekorejestr. Każda integracja wymaga indywidualnych ustaleń: urząd zamawia dostęp, a my wydajemy klucz API przypisany do tego urzędu.

Kontakt w sprawie integracji: kontakt@ekorejestr.pl.

• API publiczne (tylko odczyt, bez klucza) - karty opublikowane w wykazie i słowniki.
• API integracyjne (klucz API) - odczyt, dodawanie i edycja kart jednego urzędu, także kart jeszcze nieopublikowanych.

Adres bazowy: http://13.140.161.151/api/v1. Format: JSON w UTF-8, daty w formacie RRRR-MM-DD.

Klucz API i bezpieczeństwo

Klucz ma postać ekr_… i przesyła się go w nagłówku każdego zapytania:

Authorization: Bearer ekr_TWOJ_KLUCZ
Content-Type: application/json
Accept: application/json

• Klucz działa wyłącznie na kartach jednego urzędu. Karty innych urzędów są dla niego niewidoczne: odpowiedź to 404, tak jak dla karty, która nie istnieje.
• Klucz ma uprawnienia cards:read (odczyt) i/lub cards:write (dodawanie i edycja). Może mieć datę ważności i listę dozwolonych adresów IP.
• API nie pozwala usuwać ani wykreślać kart. Te operacje wykonuje urzędnik w panelu.
• Każda zmiana z API trafia do historii karty i dziennika zdarzeń jako zmiana konta przypisanego do klucza.
• Klucz przechowuj jak hasło: nie umieszczaj go w kodzie strony WWW ani w repozytorium.
• Wyciek klucza: administrator urzędu może sam natychmiast unieważnić klucz w panelu Ekorejestr (Ustawienia → Moja organizacja → Klucze API), bez czekania na nas. Nowy klucz wydajemy na prośbę urzędu wysłaną na kontakt@ekorejestr.pl; do czasu wpisania nowego klucza integracja nie działa.
• Komunikacja wyłącznie przez HTTPS.

Limity

• API integracyjne: 60 zapytań na minutę na klucz.
• API publiczne: 60 zapytań na minutę na adres IP.
• Po przekroczeniu limitu: odpowiedź 429 z nagłówkiem Retry-After (sekundy).
• Listy: maksymalnie 100 pozycji na stronę (per_page).

API integracyjne - endpointy

Numer karty, rok i urząd nadaje system. Karta bez listed_at jest szkicem: widzi ją tylko urząd w panelu, nie ma jej w publicznym wykazie. Ustawienie listed_at publikuje kartę z tą datą zamieszczenia (pole 16).

Pole external_id to identyfikator dokumentu w Twoim systemie. Ponowne wysłanie POST z tym samym external_id nie tworzy duplikatu, tylko zwraca 409 z numerem istniejącej karty. Dzięki temu bezpiecznie ponowisz zapytanie po błędzie sieci.

Pola karty

Pola odpowiadają 18 polom karty informacyjnej z Rozporządzenia Ministra Środowiska z 22.09.2010 (Dz.U. Nr 186, poz. 1249). Nieznane pola są odrzucane (422), żeby literówka w nazwie nie przepadła po cichu.

Odpowiedź zawiera dodatkowo: id, card_number (np. „12/2026”), status (draft, listed lub struck_off), deadline_at (termin zamieszczenia), public_url (dla kart opublikowanych) i updated_at.

Przykłady

Sprawdzenie klucza:

curl -H "Authorization: Bearer ekr_TWOJ_KLUCZ" http://13.140.161.151/api/v1/integration/me

Dodanie szkicu karty:

curl -X POST http://13.140.161.151/api/v1/integration/cards \
  -H "Authorization: Bearer ekr_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "KANC/2026/0153",
    "document_type": "d",
    "document_topic": "b",
    "document_name": "Decyzja o środowiskowych uwarunkowaniach dla przedsięwzięcia X",
    "document_description": "Decyzja określa środowiskowe uwarunkowania realizacji przedsięwzięcia X.",
    "case_reference": "OŚ.6220.12.2026",
    "document_date": "2026-10-20",
    "is_final": false
  }'

Odpowiedź (201, skrócona):

{
  "data": {
    "id": 4812,
    "external_id": "KANC/2026/0153",
    "card_number": "153/2026",
    "status": "draft",
    "document_type": "d",
    "document_date": "2026-10-20",
    "deadline_at": "2026-11-03",
    "public_url": null
  }
}

Publikacja karty w wykazie:

curl -X PATCH http://13.140.161.151/api/v1/integration/cards/4812 \
  -H "Authorization: Bearer ekr_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{"listed_at": "2026-10-28"}'

Kody odpowiedzi

API publiczne (bez klucza)

Tylko karty opublikowane w wykazie, bez szkiców i kart wykreślonych.