Dokumentace - API

Smartform pro desktop je webová služba postavená na protokolu HTTP, je podporovaná metoda POST. Data komunikace mezi klientem a serverem jsou posílána ve formátu JSON s kódováním UTF-8.

Webová služba je k dispozici na adresách:

  • https://secure.smartform.cz/smartform-ws/v1/ (šifrovaně)
  • http://smartform.cz/smartform-ws/v1/ (nešifrovaně)
Na konec zvoleného URL je třeba ještě připojit název služby (malými písmeny). V provozu jsou dvě služby: Oracle a Announce. Výsledné URL bude tedy vypadat např. takto: 
https://secure.smartform.cz/smartform-ws/v1/oracle

Následuje referenční struktura posílaných dat v dotazech a odpovědích obou služeb. Objekty jsou zachyceny ve formě pseudokódu pro lepší pochopení struktury. Přepis do formátu JSON a zpět se zkonstruuje podle těchto pravidel:

typ v pseudokódutyp v JSON
třída (class)vnořený objekt
výčet (enum)řetězec podle nastavené hodnoty
Listpole
Mapobjekt - klíče a indexy se stanou položkami objektu
stringřetězec
int (32 bitů)číslo
long (64 bitů)číslo
boolboolean
char (jeden znak)řetězec

Oracle service

Našeptávací služba - pro daný aktuální stav vyplnění formuláře nabízí vyhovující doplnění políček pro jednotlivé části adresy.

Schémata objektů

Dotaz

class OracleRequest
{
	// Identifikace dotazu
	long id;

	// Obsah formulářových políček
	Map<OracleFieldType, string> values;

	// Které políčko se právě edituje
	OracleFieldType fieldType;

	// Kolik maximálně našeptaváných možností se má vrátit
	int limit;

	// Heslo - identifikace uživatele
	string password;
}

Odpověď

class OracleResponse
{
	// Výsledek dotazu
	ResultCode resultCode;
	
	// Detailní popis chyby (pokud je resultCode == FAIL)
	string errorMessage;

	// Identifikace dotazu - pro kontrolu (mělo by být shodné s číslem v dotazu)
	long id;

	// Seznam návrhů našeptávače
	List<AddressSuggestion> suggestions;
}

Další objekty

// Typy políček ve formuláři
enum OracleFieldType
{
	NUMBER,
	STREET_AND_NUMBER,
	STREET,
	CITY,
	ZIP
}

// Jedna položka nabídky pro našeptávač.
public class AddressSuggestion
{
	// Pro které políčko je návrh určen
	OracleFieldType fieldType;

	// Příznak, zda návrh obsahuje celou adresu
	bool wholeAddress;

	// Hodnoty určené všem čtyřem formulářovým políčkům.
	Map<OracleFieldType, String> values;
}

Announce service

Validační služba - zkontroluje správnost adresy zadané ve formuláři a vrátí adresu opravenou a v oficiální podobě, případně seznam dalších vyhovujících adres při nejednoznačnosti zadání.

Schémata objektů

Dotaz

class AnnounceRequest
{
	// Identifikace dotazu
	long id;

	// Obsah formulářových políček
	Map<OracleFieldType, string> values;

	// Heslo - identifikace uživatele
	string password;
}

Odpověď

class AnnounceResponse
{
	// Výsledek dotazu
	ResultCode resultCode;
	
	// Detailní popis chyby (pokud je resultCode == FAIL)
	string errorMessage;

	// Identifikace dotazu - pro kontrolu (mělo by být shodné s číslem v dotazu)
	long id;

	// Samotný výsledek validace
	AnnounceValidationResult result;
}

Další objekty

class AnnounceValidationResult
{
	// Kód výsledku validace
	ValidationType type;
	
	// Seznam vyhovujících adres - jedna pokud je type == HIT,
	// více adres pokud type == MANY nebo TOOMANY
	List<AnnounceAddress> addresses;
	
	// Doplňující informace k validaci (nápověda k optimálnímu zadání adresy) 
	string hint;
}    

enum ValidationType
{
	// Byla nalezena právě jedna adresa.
	HIT,
	/** Bylo nalezeno více adres, všechny tyto adresy jsou obsaženy ve výsledku validace. */
	MANY,
	/** Bylo nalezeno více adres, ve výsledku validace jsou jen některé. */
	TOOMANY,
	/** Nebyla nalezena žádná adresa. */
	NOTHING,
	/** Bylo zadáno příliš málo vstupních parametrů. */
	INSUFFICIENT_DATA,
}

// Jedna zvalidovaná adresa
class AnnounceAddress
{
	// Ulice
	AddressEntity street;
	
	// Část obce
	AddressEntity part;
	
	// Obec
	AddressEntity city;
	
	// Pošta + PSČ
	AddressEntity post;
	
	// Mestská část
	AddressEntity mcast;

	// Pražský obvod (Praha 1-10)
	AddressEntity pobvod;
	
	// Správní obvod Prahy (Praha 1-22)
	AddressEntity sobvod;
	
	// Okres
	string district;
	
	// Kraj
	string region;
	
	// Příznak, jestli je PSČ v adrese speciální
	bool isPscSpecial;
	
	// Číslo objektu (popisné/evidenční, orientační)
	AnnounceNumber number;

	// Kód adresy v databázi UIR-ADR
	long uiradrCode;
	
	// X-souřadnice adresy v systému S-JTSK v metrech. 
	long coordX;
	
	// Y-souřadnice adresy v systému S-JTSK v metrech.
	long coordY;
}

// Reprezentace části zvalidované adresy.
class AddressEntity
{
	// Typ entity
	AddressEntityType type;

	// Název entity
	string name;

	// Referenční ID entity v UIR-ADR (pro poštu je to PSČ)
	long id;
}

enum AddressEntityType
{
	// ulice
	STREET,

	// část obce
	PART,

	// obec
	CITY,

	// pošta
	POST,

	// PSČ
	ZIP,

	// městská část
	MCAST,

	// správní obvod
	SOBVOD,

	// pražský obvod
	POBVOD
}

// Číslo ve zvalidované adrese
class AnnounceNumber
{
	// Číslo domu (popisné/evidenční)
	long cisloDomu;

	// Typ čísla domu (popisné/evidenční)	
	NumberType type;
	
	// Orientační číslo
	long cisloOrient;
	
	// Orientační písmeno
	char pismenoOrient;
	
	// Pokud je true, musí se pro jednoznačnost této adresy označit čísla svým typem.
	// (např. když existuje Vodičkova čp.35 a Vodičkova or.č.35)
	bool showNumberType;
	
	// Pokud je true, musí se pro jednoznačnost této adresy uvést část obce, do které náleží.
	// (např. když existují dvě adresy Vodičkova 35, každá v jiné části obce)	
	bool showPart;
}

// Typ čísla ve zvalidované adrese
enum NumberType
{
	// popisné
	POPIS,
	
	// evidenční
	EVIDENT
}

Hlavní navigace: