Verze 1.1

API Dokumentace

Průvodce integrací externích systémů se systémem ETIS pomocí rozhraní API

Úvod

Tento dokument slouží jako průvodce integrací externích systémů se systémem ETIS pomocí rozhraní API. Systém ETIS je robustní nástroj pro správu a evidenci firemních procesů, který umožňuje efektivní zpracování dat z různých zdrojů.

Co API umožňuje

Importovat data ze systémů třetích stran do ETIS
Získávat data z ETIS prostřednictvím API
Iniciovat a zpracovat pravidelné stahování dat z externích systémů
Provádět automatizované volání API na základě předem definovaných situací v Workflow

Bezpečnost komunikace: Veškerá komunikace mezi systémem ETIS a systémem třetí strany probíhá pomocí SSL protokolu s minimálně 128bitovým šifrováním.

Zápis dat do ETIS

Externí systém chce zapisovat do ETIS

Automatizace rozhraní do systému ETIS vám umožní importovat libovolné záznamy ze systémů a aplikací třetích stran.

Importovaná data mohou vytvářet hromadně nové záznamy, nebo editovat existující

Rozlišení mezi vznikem nových záznamů a editací je řešeno automaticky na straně ETIS

Importovaná data budou automaticky procesně zpracována dle nastavení Workflow

Získání autorizačního tokenu

Token může vygenerovat oprávněná osoba s oprávněním administrátora.

Přihlaste se do systému ETIS

Přejděte do Nastavení → Import → API klíče pro import

Vyberte 'Přidat token' a nastavte pojmenování, oprávnění a platnost

Zkopírujte vygenerovaný token a použijte ve struktuře požadavku

Při generování tokenu se zadává jeho platnost, která limituje dobu použitelnosti.

Každý API požadavek musí obsahovat autorizační hlavičku:

http

Authorization: Bearer YOUR_TOKEN

Struktura požadavku

Požadavky k importu dat musí být zasílány metodou POST na URL serveru v následující struktuře:

url

https://{váš_ETIS}/api/3p/import/{ID_typu_záznamů}

Příklad:

url

https://encore.cz/api/3p/import/50758

Požadavek musí obsahovat

Metoda: POST
Hlavička s platným tokenem ETIS
JSON data záznamů k importu

http

POST /api/3p/import/50758 HTTP/1.1
Host: encore.cz
Authorization: Bearer ZW123456789
Content-Type: application/json

{
  "data": [
    { ... }
  ]
}

Struktura dat JSON

Veškerá vkládaná data musí být ve formátu JSON. Jednotlivé záznamy k importu jsou uvedeny jako položky v poli 'data'.

json

{
  "data": [
    {
      "Název": "test1",
      "Zadal": "Administrátor",
      "Zpracovatel": "Jakub Novák"
    },
    {
      "Název": "ukol2",
      "Zadal": "Jakub Novák",
      "Zpracovatel": "František Pokorný"
    },
    {
      "Název": "ukol3",
      "Zadal": "Jakub Novák",
      "Zpracovatel": "Alena Nováková"
    }
  ]
}

Klíče hodnot ("Název", "Zpracovatel" atd.) musí odpovídat názvu polí v systému ETIS. Mapování polí je často individuální podle nastavení administrátora.

Příklad importu nákladů

Kompletní příklad importu přijaté faktury (nákladu) do systému ETIS.

json

{
  "data": [
    {
      "Interní číslo": "N-20190066",
      "Číslo dokladu": "",
      "Partner": "",
      "Pracovník": "",
      "Vystavil": "Aleš Procházka",
      "Stav": "Uhrazeno",
      "Popis": "Tankování vozidla Felda",
      "Způsob platby": "Bankovním převodem",
      "Kategorie nákladu": "",
      "Typ": "Přijatá faktura",
      "Datum splatnosti": "28.6.2019",
      "DUZP": "28.6.2019",
      "Datum přijetí": "28.6.2019",
      "Datum vystavení": "",
      "Datum uhrazení": "",
      "Variabilní symbol": "",
      "Konstantní symbol": "",
      "Specifický symbol": "",
      "Číslo objednávky": "",
      "Projekt": "",
      "Kolik to stálo": "1 500,00",
      "Sazba DPH": "DPH 21%"
    }
  ]
}

Získání dat z ETIS

Externí systém chce získat data z ETIS

Data z ETIS lze získávat přes API pomocí předpřipravených datových sestav z modulu Analýzy.

Definujte vlastní datovou sestavu v modulu Analýzy

Uložte sestavu a zpřístupněte ji přes API

Vytvořte autorizační token pro přístup k sestavám

Zavolejte API pro získání dat

Vytvoření podkladové sestavy

Aplikace Analýz umožňuje vytvářet tabulky a kontingenční tabulky z libovolných dat evidovaných v ETIS – včetně vlastních polí, typů záznamů a relačních sestav pro složitější scénáře.

Token pro přístup k sestavám

Přístup k vytvořeným sestavám bude mít pouze požadavek autorizovaný tokenem ETIS.

Přihlaste se do systému ETIS

Přejděte do Nastavení → Import → API klíče pro import

Přidejte token s oprávněním 'analysis' a přiřaďte ho uživateli

Oprávnění uživatele je důležité – API bude vracet pouze data, na která má oprávnění uživatel vedený pod tímto tokenem. Jeden token může být používán pro volání více sestav.

Volání API pro získání dat

Požadavky se zasílají metodou GET na URL ve struktuře:

url

https://{váš_ETIS}/api/analysis/reports/{ID_sestavy}/data/table

Příklad GET požadavku:

http

GET /api/analysis/reports/64c7ab1c/data/table HTTP/1.1
Host: encore.cz
Authorization: Bearer YOUR_TOKEN

Formát odpovědi

Odpověď ve formátu JSON obsahuje dvě hlavní části:

columns

Definuje názvy a ID jednotlivých sloupců v tabulce

rows

Obsahuje samotná data v podobě seznamu řádků

json

{
  "columns": [
    { "id": "col1", "name": "Jméno" },
    { "id": "col2", "name": "Příjmení" },
    { "id": "col3", "name": "Email" }
  ],
  "rows": [
    { "col1": "Jan", "col2": "Novák", "col3": "jan.novak@example.com" },
    { "col1": "Petr", "col2": "Svoboda", "col3": "petr.svoboda@example.com" }
  ]
}

Stránkování

K požadavku se v URL dají připojit parametry pro stránkování:

offset

Určuje, od jakého záznamu má tabulka začít (výchozí: 0)

limit

Určuje počet vrácených záznamů v odpovědi (výchozí: 100)

url

https://nazev.systemetis.cz/api/analysis/reports/{ID_Sestavy}/data/table?limit=60&offset=100

Pokud počet načtených záznamů v poslední odpovědi je menší než limit, stránkování je ukončeno.

API komunikace vyvolaná ETIS

ETIS má zavolat externí systém

Scénář, kdy ETIS iniciuje volání API v různém rozsahu. Nastavuje se v rámci ETIS Workflow – nástroje vizuálního programování pomocí diagramů.

Pravidelné stahování dat

Každých 10 minut zavolej API banky a stáhni bankovní transakce
Každých 30 minut zkontroluj Google tabulku a aktualizuj produkty v ETIS

Reakce na události

Když je faktura po splatnosti, pošli informaci do jiného systému
Když je na úkolu překročen rozpočet, notifikuj jiný systém
Pokud je objednávka schválená, pošli data do systému A; pokud zamítnutá, do systému B

Vytvoření procesu

Vytvořte nový proces v prostředí Workflow. Můžete definovat podmínky, za jakých okolností má záznam volat API – při editaci záznamu, v časových intervalech nebo jiných situacích.

Otevřete Workflow a vytvořte nový proces

V obsahu elementu Operace vyberte 'Přidat operaci'

Zvolte 'Zavolat API'

Workflow se vykonává individuálně pro každý záznam. Pro hromadnou aktualizaci dat volejte API z nadřazeného záznamu.

Nastavení API volání

Akce 'Zavolat API' se konfiguruje ve třech záložkách:

Základní

Definice cílového systému, formátu a autorizace.

methodTyp požadavku: PING, GET, POST, PUT, DELETE

urlCílová URL adresa – podporuje vkládání proměnných z procesu nebo dat ze záznamu

formatFormát dat: JSON / XML

timeoutPočet sekund pro timeout (výchozí: 60s)

scopeRozsah použití: Aktuální záznam / Na vybranou evidenci

loggingLogování historie zpracování API

authZpůsob autorizace: Prázdný, BASIC, OAUTH2

Příklad URL s proměnnými ETIS:

url

#(SERVER_URL)/api/core/ares/#(IČ)

Požadavek

Definice požadavku odesílaného na cílovou službu.

saveToFileUložit do souboru k záznamu

contentTypeFormát požadavku (výchozí: application/json)

headersHlavičky požadavku – název parametru a hodnota

bodyTělo požadavku s podporou proměnných ETIS (pomocí #)

Příklad požadavku na účetní software:

json

{
  "command": {
    "inComm": "FA_IN",
    "inParam": {
      "parameters": {
        "id_fa": null,
        "cis_fa": null,
        "ico_part": null,
        "dat_od": null,
        "dat_do": null,
        "typ_fa": null,
        "timestamp": "fx{new Date().minus(2.days).format('yyyy-MM-dd')}"
      }
    }
  }
}

Zpracování odpovědi

Nastavení způsobu zpracování dat z odpovědi.

saveToFileUložit odpověď jako soubor k záznamu

saveToVariableUložit do proměnné pro další použití ve Workflow

successVariableProměnná pro úspěšnost volání (true/false)

testUrlURL pro testovací volání a získání struktury polí

encodingKódování odpovědi (výchozí: UTF-8)

mappingMapování polí z API na pole v ETIS

Příklad mapování odpovědi z ARES:

json

// Odpověď z ARES API
{
  "entity": {
    "companyName": "Encore Technologies s.r.o.",
    "identificationNumber": "64949681",
    "vatIdentificationNumber": "CZ64949681",
    "companyAddressData": {
      "city": "Praha",
      "street": "Tomíčkova",
      "houseNumber": "2144"
    },
    "employeeCount": 15,
    "establishmentDate": "2021-07-01"
  }
}

// Mapování na pole v ETIS:
// companyName       → Název
// identificationNumber → IČO
// vatIdentificationNumber → DIČ
// companyAddress    → Sídlo

Chybové kódy

API může vracet různé HTTP status kódy indikující stav požadavku.

200

200 OK

Požadavek byl úspěšně zpracován.

401

401 Unauthorized

Neplatný nebo chybějící přístupový token.

404

404 Not Found

Zadaný zdroj neexistuje.

500

500 Internal Server Error

Interní chyba serveru.

Potřebujete pomoct s integrací?

Náš tým vám pomůže s návrhem a implementací API integrace pro váš konkrétní scénář.

API Dokumentace

Úvod

Co API umožňuje

Zápis dat do ETIS

Získání autorizačního tokenu

Struktura požadavku

Požadavek musí obsahovat

Struktura dat JSON

Příklad importu nákladů

Získání dat z ETIS

Vytvoření podkladové sestavy

Nastavení tabulky pro sdílení

Token pro přístup k sestavám

Volání API pro získání dat

Formát odpovědi

Stránkování

API komunikace vyvolaná ETIS

Pravidelné stahování dat

Reakce na události

Vytvoření procesu

Nastavení API volání

Základní

Požadavek

Zpracování odpovědi

Chybové kódy

200 OK

401 Unauthorized

404 Not Found

500 Internal Server Error

Potřebujete pomoct s integrací?