Dokumentace API – Hledání úřadů

Toto je popis starší verze služby pro hledání úřadů. Doporučujeme používat aktuální verzi.

Webová služba pro hledání úřadů je k dispozici na adrese:

  • https://secure.smartform.cz/smartform-ws/searchAuthority/v1

Vlastnosti dotazu

Dotazy musí být posílány metodou POST. Data jsou posílána ve formátu JSON s kódováním UTF-8.

Hlavička http requestu musí obsahovat následující položky:

název hodnota
Content-type application/json
Accept application/json

Struktura dotazu a odpovědi

Následuje referenční struktura dotazu a odpovědi. Objekty jsou zachyceny ve formě pseudokódu pro lepší pochopení struktury.

Dotaz

/** Dotaz pro službu searchAuthority */
class SearchAuthorityRequest 
{
    /** Identifikace dotazu, slouží jen pro spárování dotazu a odpovědi. */  
    int id;

    /** Heslo - pokud jej nemáte, získáte ho v administraci na https://admin.smartform.cz */
    string password;

    /** Vstupní data. */
    Map<InputFieldTypeSearchAuthority, string> inputData;
}

Odpověď

/** Odpověď pro službu searchAuthority */
class SearchAuthorityResponse 
{
    /** Identifikace odpovědi, odpovídá id dotazu */
    int id;

    /** Zdali vůbec proběhlo hledání v pořádku */
    ResultCode resultCode;

    /** Pokud došlo k nějaké chybě, popisuje k jaké */
    string errorMessage;

    /** Typ úřadu */
    ResultTypeAuthority typeAuthority;
                            
    /** Informace o úřadu/ůřadech, které vychází z
     *  xml datových schránek.
     *  Konkrétní popis atributů v dokumentaci kapitola 2.1.4. 
     */
    List<AuthorityEntity> authority;
}

Další objekty

/** Typ vstupních dat */
enum InputFieldTypeSearchAuthority 
{
    /**  Kód adresy z registru RUIAN */
    RUIAN_CODE
}

/** Výsledný typ úřadu */
enum ResultTypeAuthority 
{
    /** Obecní úřad */
    LOCAL_AUTHORITY,
                            
    /** Jiný typ úřadu */
    OTHER_AUTHORITY,

    /** Na jedné adrese se nachází více úřadů */
    MANY_AUTHORITIES,
                    
    /** Vstupní adresa není úřadem */
    NO_AUTHORITY
}

/** Výsledek dotazu. */
enum ResultCode 
{
    /** Volání service proběhlo v pořádku. */
    OK,
    
    /** Při volání service došlo k chybě. */
    FAIL
}

Tabulka typů v pseudokódu

typ v pseudokódu typ v JSON
třída (class) vnořený objekt
výčet (enum) řetězec se jménem vybrané položky
List pole
Map objekt – klíče a hodnoty se stanou položkami objektu
string řetězec
int číslo
double číslo
boolean boolean
char (jeden znak) řetězec