AXIOS API

V systému lze pro volání API třetích stran používat knihovnu curl, a nově od verze TAS 5.7 také knihovnu axios.

✅ Výhody použití AXIOS oproti CURL

1. Přehlednější zápis
   Axios používá jednoduchý a čitelný zápis (např. axios.get(url) místo několika setOpt volání).
2. Méně kódu
   Pro běžné operace (GET, POST, PATCH…) není třeba ručně nastavovat typ požadavku, hlavičky nebo formátování těla.
3. Lepší práce s odpovědí
   Axios automaticky převádí odpovědi na JSON (pokud Content-Type odpovídá) a poskytuje přístup k res.data, res.status, atd.
4. Snazší údržba a čitelnost pro ostatní
   Konzultanti a vývojáři rychleji pochopí, co kód dělá, protože struktura odpovídá běžnému zápisu v moderním JavaScriptu.

❗ Kdy nelze použít AXIOS

1. Axios funguje pouze pro HTTP/HTTPS požadavky. Nelze jej použít pro jiné protokoly jako např.:
   1. SMTP (např. odesílání e-mailů)
   2. FTP
   3. IMAP/POP3

V těchto případech je třeba nadále používat knihovnu curl.

🔧 Možnosti použití axios

Axios podporuje všechny běžné HTTP metody:

✅ GET

Slouží k načtení dat z API (např. seznam položek).

axios.getAxios().get('https://api.example.com/items');

✅ POST

Slouží k odeslání dat na server (např. vytvoření nové položky).

axios.getAxios().post('https://api.example.com/items', {
  name: 'Nová položka'
});

✅ PUT

Slouží k plné aktualizaci existující položky.

axios.getAxios().put('https://api.example.com/items/123', {
  name: 'Aktualizovaná položka'
});

✅ PATCH

Slouží k částečné aktualizaci položky (např. jen jedno pole).

axios.getAxios().patch('https://api.example.com/items/123', {
  status: 'aktivní'
});

✅ DELETE

Slouží ke smazání položky.

axios.getAxios().delete('https://api.example.com/items/123');

✅ request – obecné volání (např. pro PATCH, když potřebuješ vlastní metodu)

axios.getAxios().request({
  method: 'patch',
  url: 'https://api.example.com/items/123',
  data: { status: 'hotovo' }
});

✅ requestRaw – obecné volání (možnost získání header, status, statusText, data)

Ukázka použití

const config = {
        method: "get",
        url: `https://api.example.com/items/123`}

const request = axios.getAxios().requestRaw(config);

Typická odpověď

{
  "data": {
    // Obsah vrácený serverem (např. JSON data)
  },
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json",
    "date": "Mon, 22 Jul 2025 09:44:24 GMT"
  }
}

📤 Odeslání jednoho souboru (sendFile)

const file = lib.getFileContents('/cesta/k/souboru.txt');

axios.getAxios().sendFile('https://api.example.com/upload', file, {
  headers: {
    'Content-Type': 'application/octet-stream'
  }
});

📤 Odeslání jednoho souboru (sendFileRaw) (možnost získání header, status, statusText, data)

const file = lib.getFileContents('/cesta/k/souboru.txt');

axios.getAxios().sendFileRaw('https://api.example.com/upload', file, {
  headers: {
    'Content-Type': 'application/octet-stream'
  }
});

Typická odpověď

{
  "data": {
    // Obsah vrácený serverem (např. JSON data)
  },
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json",
    "date": "Mon, 22 Jul 2025 09:44:24 GMT"
  }
}

Příklad odeslání souboru do systému s API klíčem

const URL = 'https://api.example.com/123';
const ocpKey = 'xxxxx';
const documentName = vars['attachedInvPDF'].getValue();
const invNumber = vars['internalNumber'].getValue() + path.extname(documentName[0]);
const dmsEntity = storage.getDmsEntity(documentName);
const path = exportDmsFile(dmsEntity, invNumber)

    const result = axios.getAxios({
        headers: {
            'Ocp-Apim-Subscription-Key': ocpKey
        }
    }).sendFileRaw(URL, path);

Ukázka odpovědi

{
    "data": "",
    "headers": {
        "content-length": "0",
        "operation-location": "https://api.example.com/123",
        "x-envoy-upstream-service-time": "109",
        "apim-request-id": "xxx-abfd-xx-a820-xxxx",
        "strict-transport-security": "max-age=31536000; includeSubDomains; preload",
        "x-content-type-options": "nosniff",
        "x-ms-region": "West Europe",
        "date": "Thu, 24 Jul 2025 09:43:36 GMT"
    },
    "status": 202,
    "statusText": "Accepted"
}

📤 Odeslání více souborů (sendFiles/sendFilesRaw) přes FormData

const FormData = require('form-data');
const form = new FormData();

form.append('file1', lib.getFileContents('/cesta/k/soubor1.jpg'));
form.append('file2', lib.getFileContents('/cesta/k/soubor2.jpg'));

axios.getAxios().sendFiles('https://api.example.com/upload', form, {
  headers: form.getHeaders()
});

📝 Odeslání formulářových dat (sendFormData)

const FormData = require('form-data');
const form = new FormData();

form.append('name', 'Test');
form.append('email', 'test@example.com');

axios.getAxios().post('https://api.example.com/form', form, {
  headers: form.getHeaders()
});

➕ Přidání souboru do FormData (addFileToFormData)

form.append('file', lib.getFileContents('/cesta/k/souboru.pdf'));

➕ Přidání textového pole do FormData (addFieldToFormData)

form.append('description', 'Nahrávám soubor k článku');

🔄 Zpracování odpovědi

Axios vrací odpověď jako objekt, např.:

const response = axios.getAxios().get(url);
proc.warn(response.data); // data z API

Vlastnosti AXIOS

• Timeout - default timeout je 0, v tomto případě pak přichází na řadu timeout calculations (default 120 s)
• Throw error - v případě jiného response status než 200 se throwne odpovídající error.
• Buffer.from

Tato funkce převádí běžný textový řetězec (string) na binární data (Buffer) v kódování UTF-8. Používá se pro správné odesílání XML nebo jiných textových dat přes AXIOS.

Příklad:

const xml = '<soap>...</soap>';
const payload = Buffer.from(xml, 'utf-8');

Příklady použití AXIOS

Použití GET pro získání dat z ČNB

function axiosGetDataByURL(requestURL) {
    try {
        const response = axios.getAxios().get(requestURL);
        return response;
    } catch (error) {
        return {
            error: true,
            fullError: error,
            statusCode: error?.response?.status,
            statusText: error?.response?.statusText
        };
    }
}

try {
    const cnbExchangeRatesURL = `https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/denni_kurz.xml`;
    const requestResponse = axiosGetDataByURL(cnbExchangeRatesURL);

    if (requestResponse?.error) {
        throw new Error(`[CNB][Response][Error] ${requestResponse?.statusText}`, {
            cause: requestResponse?.fullError
        });
    }

    proc.warn(`[CNB][ResponseData]`, { requestResponse });

} catch (error) {
    proc.warn(
        `Během stažení informací z ČNB nastal problém: ${error?.message || `Neznámá chyba`} (rozklikněte log pro další detaily)`,
        { cause: error?.cause }
    );
}

Použití PATCH pro update dat na docs.teamassistant.app

function patchMainBody(articleId, newBody) {
    const url = `https://api.helpdocs.io/v1/article/${articleId}`;
    const payload = { body: newBody };

    const requester = axios.getAxios({
        timeout: 10000,
        headers: {
            'Authorization': 'Bearer xxxxxxxx'
        }
    });

    return requester.patch(url, payload);
}

🔍Rozdíly mezi použitím CURL a AXIOS - příklady

Volání kurzů ČNB

CURL

function rateCNB(exchangeRateDate, currency, reportingCurrency) {    
    let formatDate = lib.format(exchangeRateDate, "d.m.Y");

    curl.start();
    curl.setOpt('CUSTOMREQUEST', 'GET');
    curl.setOpt('FOLLOWLOCATION', true);
    curl.setOpt('FAILONERROR', false);
    curl.setOpt('SSL_VERIFYPEER', false);
    curl.setOpt('SSL_VERIFYHOST', false);
    curl.setOpt('TIMEOUT', 30);
    curl.setOpt('HTTPHEADER', [
        'Content-Type: application/json',
        'Accept: application/json'
    ]);

    curl.setOpt('URL', `https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/denni_kurz.txt?date=${formatDate}`);
    var crossRate = curl.perform();
    //search for specific currency
    try {
        const body = crossRate.data;
...

AXIOS

function rateCNB(exchangeRateDate, currency, reportingCurrency) {
    let formatDate = lib.format(exchangeRateDate, "d.m.Y");

    const url = `https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/denni_kurz.txt?date=${formatDate}`;

    const body = axios.getAxios().get(url);
    //search for specific currency
    try {
        const rows = body.split('\n');
...