Příklady a reference Web API

Příklady volání s Postmanem

Příklad 1: Ověření připojení - test

Nejjednoduší příklad pro ověření, že API funguje:

GET /test HTTP/1.1
Host: wiki2.test:8080
x-api-key: demo-key-12345

Odpověď:

{
  "version": "4.0.0.0",
  "database": "connected",
  "authorized": true,
  "message": "API je aktivní a připojeno k databázi"
}

Příklad 2: Získání subjektů (XML)

Volání pro získání seznamu subjektů v XML formátu:

POST /getData HTTP/1.1
Host: wiki2.test:8080
Content-Type: application/xml
x-api-key: demo-key-12345

<?xml version="1.0" encoding="utf-8"?>
<request>
  <vltyp>1</vltyp>
  <conditions>
    <condition>
      <field>IDSubjekt</field>
      <operator>></operator>
      <value>0</value>
    </condition>
  </conditions>
</request>

Odpověď (XML):

<?xml version="1.0" encoding="utf-8"?>
<response>
  <state>0</state>
  <data>
    <row>
      <IDSubjekt>1</IDSubjekt>
      <NazevSubjekt>Eso9 International a.s.</NazevSubjekt>
      <ICO>123456789</ICO>
      <DIC>CZ123456789</DIC>
    </row>
    <row>
      <IDSubjekt>2</IDSubjekt>
      <NazevSubjekt>Příklad s.r.o.</NazevSubjekt>
      <ICO>987654321</ICO>
      <DIC>CZ987654321</DIC>
    </row>
  </data>
</response>

Příklad 3: Získání subjektů (JSON)

Stejné volání v JSON formátu:

POST /getData HTTP/1.1
Host: wiki2.test:8080
Content-Type: application/json
x-api-key: demo-key-12345

{
  "vltyp": 1,
  "conditions": [
    {
      "field": "IDSubjekt",
      "operator": ">",
      "value": 0
    }
  ]
}

Odpověď (JSON):

{
  "state": 0,
  "data": [
    {
      "IDSubjekt": 1,
      "NazevSubjekt": "Eso9 International a.s.",
      "ICO": "123456789",
      "DIC": "CZ123456789"
    },
    {
      "IDSubjekt": 2,
      "NazevSubjekt": "Příklad s.r.o.",
      "ICO": "987654321",
      "DIC": "CZ987654321"
    }
  ]
}

Příklad 4: Asynchronní volání

Pro dlouhodobě běžící dotaz:

POST /getDataAsync HTTP/1.1
Host: wiki2.test:8080
Content-Type: application/json
x-api-key: demo-key-12345

{
  "vltyp": 7,
  "conditions": [
    {
      "field": "CTUCET_CISLO",
      "operator": "=",
      "value": "0001"
    }
  ]
}

Odpověď (v průběhu zpracování):

{
  "status": "processing",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Dotaz je zpracováván na serveru"
}

Později přidat dotaz na výsledek (s vltyp = 997):

POST /getData HTTP/1.1
Host: wiki2.test:8080
Content-Type: application/json
x-api-key: demo-key-12345

{
  "vltyp": 997,
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Operátory podmínek

Při specifikaci podmínek lze používat následující operátory:

Operátor	Popis	Příklad
=	Rovnost	IDSubjekt = 5
<>	Nerovnost	ICO <> ""
>	Větší než	IDSubjekt > 0
<	Menší než	IDSubjekt < 100
>=	Větší nebo rovno	DatumZalozeni >= "2020-01-01"
<=	Menší nebo rovno	DatumZalozeni <= "2025-12-31"
LIKE	Obsahuje (textu)	NazevSubjekt LIKE "%eso9%"
IN	Jedna z hodnot	IDSubjekt IN (1,2,3)
IS NULL	Prázdné pole	DatumZruseni IS NULL

Kódy chyb

Web API vrací následující stavové kódy:

Kód	Popis
0	Úspěšné zpracování
-1	Chyba v dotazu
-2	Neautorizovaný přístup
-3	Procedura neexistuje
-4	Chyba databáze
-5	Timeout

Bezpečnosť a osvědčené postupy

1. API klíč: Uchovávejte API klíč v bezpečí, neposílejte jej nešifrovaným kanálem
2. HTTPS: V produkčním prostředí vždy používejte HTTPS
3. Timeout: Pro dlouhé dotazy používejte asynchronní metodu
4. Logování: Povolte logování a pravidelně kontrolujte logy
5. Pravidla volání: Dodržujte pravidla pro specifikaci parametrů
6. Ověření dat: Vždy ověřte data, která vám API vrátí

Integrace s Excel

Můžete vytvořit makro v Excel sešitu, které bude volat Web API:

Function GetDataFromAPI(apiKey As String) As String
    Dim http As Object
    Set http = CreateObject("MSXML2.XMLHTTP")
    
    Dim url As String
    url = "http://wiki2.test:8080/getData"
    
    Dim payload As String
    payload = "{""vltyp"": 1}"
    
    http.Open "POST", url, False
    http.setRequestHeader "Content-Type", "application/json"
    http.setRequestHeader "x-api-key", apiKey
    http.Send payload
    
    GetDataFromAPI = http.responseText
End Function

Řešení problémů

Chyba: "Neautorizovaný přístup" (-2)

Zkontrolujte:

• Je x-api-key správně nastavený?
• Je API klíč v konfiguraci Web API?
• Není klíč vypršelý?

Chyba: "Timeout" (-5)

Řešení:

• Zkuste zvýšit CommandTimeout v web.configu
• Pro dlouhé dotazy použijte getDataAsync
• Zkontrolujte výkonnost databázového serveru

Chyba: "Procedura neexistuje" (-3)

Zkontrolujte:

• Je vltyp správně zadaný?
• Je procedura nasazena v databázi?

Kontakt a podpora

Pokud máte otázky nebo problemy s ESO9 Web API, kontaktujte:

ESO9 international a.s.

• Web: https://www.eso9.cz
• Email: info@eso9.cz
• Tel.: +420 585 203 370-2