Dokumentace API – Validace jmen

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

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

Služba využívá protokolu HTTP, dotazy musí být posílány metodou POST. Data komunikace mezi klientem a serverem 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ázevhodnota
Content-typeapplication/json
Acceptapplication/json

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;

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

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ódutyp v JSON
třída (class)vnořený objekt
výčet (enum)řetězec se jménem vybrané položky
Listpole
Mapobjekt – klíče a hodnoty se stanou položkami objektu
stringřetězec
intčíslo
doublečíslo
booleanboolean
char (jeden znak)řetězec


Hlavní navigace: