Dokumentace API – Validace jmen

Webová služba pro validaci jmen je k dispozici na adrese:

  • https://secure.smartform.cz/smartform-ws/validatePerson/v2

Dokumentaci starších verzí služby najdete na stránce Dokumentace API – Seznam verzí.

Autentizace

Služba využívá autentizační metodu Basic authentication. Jako jméno použijte uživatelské ID (clientId), které získáte po přihlášení do administrace v pravém horním rohu. Heslo si můžete zobrazit v administraci na záložce „Smartform Web Services“.

Při neúspěšné autentizaci vrací služba HTTP kód 401.

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

Změny oproti předchozím verzím

Novinky ve verzi 2

  • K autentizaci se používá metoda Basic authentication (viz výše). Z těla dotazu byla odstraněna property password.

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 validatePerson */
class ValidatePersonRequest 
{
    /** Identifikace dotazu, slouží jen pro spárování dotazu a odpovědi, pro validaci není důležité. */    
    int id;
    
    /** Seznam vstupních hodnot */
    List<InputPersonField> inputFields;
    
    /** Seznam požadovaných výstupních hodnot */
    List<OutputPersonFieldRequest> requestedFields;
    
}

Odpověď

/** Odpověď služby validatePerson */
class ValidatePersonResponse 
{
    /** Identifikace odpovědi, odpovídá id dotazu. */    
    int id;
    
    /** Zdali vůbec došlo k validaci a zda validace proběhla v pořádku. */
    ResultCode resultCode;

    /** Pokud došlo k nějaké chybě, popisuje k jaké. */
    string errorMessage;
    
    /** Seznam výstupních políček */
    List<OutputPersonField> outputFields;

}

Další objekty

/** Vstupní políčko */
class InputPersonField 
{
    /** Typ políčka */
    ValidatePersonFieldType fieldType;
    
    /** Hodnota */
    tring value;

}
/** Typ vstupních i výstupních polí */ 
enum ValidatePersonFieldType 
{
    /** Křestní jméno */
    FIRSTNAME,
    
    /** Křestní jméno v 5. pádě. */
    FIRSTNAME_VOCATIVE,
    
    /** Příjmení */
    LASTNAME,
    
    /** Příjmení v 5.pádě */
    LASTNAME_VOCATIVE,
    
    /** Celé jméno */
    FULLNAME,

    /** Všechny tituly */
    TITLE,
    
    /** Tituly před jménem */
    TITLE_BEFORE,
    
    /** Tituly za jménem */
    TITLE_AFTER,
    
    /** Oslovení (pan, paní) */
    SALUTATION,
    
    /** Oslovení 5.pád - (vážený pane, vážená paní) */
    SALUTATION_VOCATIVE, 
    
    /** Pohlaví */
    SEX 

}
/** Požadavek na výstupní pole */
class OutputPersonFieldRequest 
{
    /** Požadovaný typ výstupního pole */
    ValidatePersonFieldType fieldType;

}
/** Výstupní políčko */
class OutputPersonField 
{
    /** Typ políčka */
    ValidatePersonFieldType fieldType;
    
    /** Hodnota */
    string value;
    
    /** Typ výsledku */
    OutputPersonFieldResultType result;
    
    /** Doplňující informace k validaci */
    string hint;

}
/** Typ výsledku validace jednoho pole */
enum OutputPersonFieldResultType 
{
    /** Na výstupu je stejná hodnota jako na vstupu. */
    HIT,
	
    /** Výstupní hodnota byla oproti vstupu upravena. */
    REPAIRED,
	
    /** Vstupní hodnota byla prazdná, byl doplněn validní výsledek. */
    FILLEDIN,
    
    /** Prohození políček (prohození křestního jména a příjmení). */
    SWAPPED,

    /** Neodpovídá pohlaví vůči ostatním polím. */
    SEX_MISMATCH,
    
    /** Na vstupu nebylo dostatek dat. */
    INSUFFICIENT_DATA,

    /** Existuje vice možností. */
    MANY,
	
    /** Vstupní hodnotu se nepodařilo zvalidovat. */
    NOTHING
	
}
/** 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


Hlavní navigace: