API EZD RP pozwala systemom zewnętrznym uzyskiwać dostęp do zasobów EZD RP oraz korzystać z jego modułów i funkcji. W tej instrukcji przedstawione są metody API wykorzystywane do realizacji konkretnego celu biznesowego – dodania adresata. Opisana jest także zalecana kolejność wywoływania metod.
Aby dodać adresata w systemie EZD RP, należy wywołać metodę:
POST /ezdrp/integrator/v2/adresaci
Podczas dodawania adresata trzeba przekazać co najmniej jeden adres z jednej z poniższych grup:
- listaAdresow
- listaAdresowEPUAP
- listaAdresowEmail
- ListaAdresowEDoreczenia
Poniżej znajduje się przykład dodania adresata (osoby fizycznej) z adresem z grupy listaAdresow. Jeśli dodajemy adres w Polsce, przed wysłaniem żądania musimy najpierw wyszukać identyfikatory idMiejscowosc oraz idUlica. Do tego służy metoda:
POST /teryt/miejscowosci/_search
Przykład zapytania dla miejscowości Warszawa:
{
"nazwaMiejscowosci": "Warszawa",
"page": 0,
"pageSize": 25
}
Odpowiedź zawiera listę miejscowości o podanej nazwie. Interesujący nas wynik to Warszawa w województwie mazowieckim:
{
"idMiejscowosci": 192263,
"nazwa": "Warszawa",
"idWojewodztwo": 10,
"nazwaWojewodztwo": "MAZOWIECKIE",
"czyPosiadaUlice": true,
"powiat": "Warszawa",
"idPowiat": 18,
"gmina": "Warszawa",
"idGmina": 436,
"rodzajMiejscowosci": "miasto",
"idRodzajMiejscowosci": 3
}
Następnie należy wyszukać ulicę za pomocą metody:
POST /teryt/ulice/_search
W naszym przykładzie szukamy ulicy Kolska. Metoda zwraca wszystkie ulice zawierające to wyrażenie w nazwie. Przykładowa odpowiedź:
{
"lista": [
{
"idUlica": 536742,
"nazwa": "ul. Kolska",
"miejscowosc": {
"idMiejscowosci": 192263,
"idWojewodztwo": 0,
"czyPosiadaUlice": false,
"idPowiat": 0,
"idGmina": 0,
"idRodzajMiejscowosci": 0,
"czyUsunieta": false
}
},
{
"idUlica": 534834,
"nazwa": "ul. Okolska",
"miejscowosc": {
"idMiejscowosci": 192263,
"idWojewodztwo": 0,
"czyPosiadaUlice": false,
"idPowiat": 0,
"idGmina": 0,
"idRodzajMiejscowosci": 0,
"czyUsunieta": false
}
}
]
}
Spośród wyników wybieramy właściwą ulicę – w tym przypadku ul. Kolska o identyfikatorze 536742.
Mając idMiejscowosc oraz idUlica możemy wywołać metodę:
POST /ezdrp/integrator/v2/adresaci
Poniżej przykład dodania osoby fizycznej jako adresata:
{
"prefix": "",
"sufix": "",
"imie": "Jan",
"nazwisko": "Naskowski",
"typAdresata": 3,
"czyZbiorczy": true,
"typKomunikacjiEpuap": 2,
"listaAdresow": [
{
"idMiejscowosc": 192263,
"idUlica": 536742,
"dzielnica": "",
"prowincja": "",
"idKraj": "PL",
"kodPocztowy": "01-045",
"numerDomu": "12",
"typAdresu": 2
}
],
"listaAdresowEmail": [],
"listaAdresowEPUAP": [],
"listaAdresowEDoreczenia": [],
"listaPodadresaci": [],
"metadaneAdresata": []
}
Wartości dostępne dla typAdresata:
- 1 – Podmiot/Instytucja
- 3 – Osoba fizyczna
Wartości dostępne dla typKomunikacjiEpuap:
- 1 – Podmiot/Instytucja
- 2 – Osoba fizyczna
Wartości dostępne dla typAdresu:
- 1 – Adres zameldowania
- 2 – Adres korespondencyjny
- 8 – Adres zamieszkania
- 16 – Adres siedziby
Dla osób fizycznych dostępne są wartości: 1, 2, 8
Dla podmiotów/instytucji dostępne są wartości: 2, 16
Po poprawnym wywołaniu metody otrzymamy w odpowiedzi identyfikator nowo dodanego adresata:
{
"idAdresat": "408aab9ea6e640f5aadd39e2c0c8b8db"
}
W systemie zostanie dodany adresat, co jest widoczne na poniższym zrzucie ekranu.
W zakładce Adresy widoczny będzie podany przez nas adres.
W przypadku, gdy chcemy dodać adresatowi dodatkowy adres np. ePUAP, korzystamy z odpowiedniej metody POST:
- /ezdrp/integrator/v2/adresaci/{idAdresat}/adresy
- /ezdrp/integrator/v2/adresaci/{idAdresat}/epuap
- /ezdrp/integrator/v2/adresaci/{idAdresat}/email
- /ezdrp/integrator/v2/adresaci/{idAdresat}/edoreczenia
Wartość /idAdresat została nam zwrócone wcześniej, jeżeli jej nie mamy, to możemy wyszukać adresata przy użyciu metody:
POST /ezdrp/integrator/v2/adresaci/_search
Przykład dla wcześniej dodawanego adresata:
{
"imie": "Jan",
"drugieImie": "",
"nazwisko": "Naskowski",
"nazwaPodmiotu": "",
"miejscowosc": "Warszawa",
"ulica": "ul. Kolska",
"kodPocztowy": "01-045",
"kraj": "POLSKA",
"numerBudynku": "12",
"numerLokalu": "",
"email": "",
"pesel": "",
"typAdresata": 3,
"page": 0,
"pageSize": 25
}
W odpowiedzi uzyskamy listę wszystkich pasujących do kryteriów adresatów wraz z ich idAdresata:
{
"lista": [
{
"idAdresat": "408aab9ea6e640f5aadd39e2c0c8b8db",
"imie": "Jan",
"nazwisko": "Naskowski",
"pelnaNazwa": "Jan Naskowski",
"typAdresata": 3,
"metadane": [],
"listaAdresow": [
{
"idAdresat": "408aab9ea6e640f5aadd39e2c0c8b8db",
"idAdresWersja": "7fa13910435e49c1907f5ec29dbc22f0",
"idAdresWersjaAktualna": "8ccf1acb68014430a1542bc56ea83e70",
"miejscowosc": {
"id": 192263,
"nazwa": "Warszawa",
"idRodzajMiejscowosci": 0
},
"ulica": {
"id": 536742,
"nazwa": "ul. Kolska"
},
"kraj": {
"id": "PL"
},
"numerDomu": "12",
"kodPocztowy": "01-045",
"typAdresu": 3,
"czyAdresSpozaTerytu": false,
"czyAdresZagraniczny": false,
"czyNiepelnyAdres": false,
"czyUsuniety": false
}
],
"listaAdresowEmail": [],
"listaAdresowEPUAP": [],
"listaAdresowEDoreczenia": [],
"listaPodadresaci": [],
"czyZbiorczy": true,
"czyBrakDostepuDoDanych": false,
"typKomunikacjiEpuap": 2
}
],
"pageInfo": {
"indexEnd": 0,
"indexStart": 0,
"pageNumber": 0,
"pageSize": 25,
"isNextPageExists": false
}
}
Mając identyfikator adresata (idAdresat=408aab9ea6e640f5aadd39e2c0c8b8db), możemy dodać mu adres ePUAP. W tym celu wywołujemy metodę:
POST /ezdrp/integrator/v2/adresaci/408aab9ea6e640f5aadd39e2c0c8b8db/epuap
Przykładowe żądanie:
{
"identyfikator": "JanNaskowski",
"skrytka": "domyslna",
"czyDomyslny": false
}
W odpowiedzi otrzymamy identyfikator dodanego adresu ePUAP:
{
"idAdresEpuap": "0f78219d0faf42a8826cbe51485f076d"
}
Adres ePUAP zostanie przypisany do wskazanego adresata i będzie widoczny w systemie:
Do edycji lub usuwania adresata oraz jego adresów służą metody:
- PATCH – do wprowadzania zmian,
- DELETE – do usuwania danych.