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. Tento článek shrnuje, jak axios v TAS používat, kdy je vhodnější než curl a jak zpracovat odpověď včetně chyb.

Kdy použít axios a kdy curl

Pro nová HTTP/HTTPS volání je axios doporučená volba. Přináší proti curl tyto výhody:

1. Přehlednější a kratší zápis — místo několika setOpt volání stačí jediné axios.getAxios().get(url). U běžných operací (GET, POST, PATCH…) není třeba ručně nastavovat typ požadavku, hlavičky ani formátování těla.
2. Lepší práce s odpovědí — axios automaticky parsuje JSON odpověď podle Content-Type. Klasické metody vrací rovnou parsovaná data (viz sekce Zpracování odpovědi).
3. Snazší údržba a čitelnost — struktura odpovídá běžnému zápisu v moderním JavaScriptu, takže konzultanti i vývojáři rychleji pochopí, co kód dělá.

Vstupní bod — axios.getAxios()

Každé volání začíná funkcí axios.getAxios(config?), která vrátí klienta. Na klientovi se pak volají jednotlivé HTTP metody. Volitelný config umožňuje nastavit baseURL, timeout a headers společné pro všechna volání klienta.

const client = axios.getAxios({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  headers: { 'Accept': 'application/json' }
});

const items = client.get('/items');

HTTP metody

axios podporuje všechny běžné HTTP metody.

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

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

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

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

PUT — plná aktualizace existující položky.

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

PATCH — částečná aktualizace položky (např. jen jedno pole).

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

DELETE — smazání položky.

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

request — obecné volání, když potřebuješ metodu určit dynamicky nebo skládat konfiguraci.

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

Zpracování odpovědi a chyb

Chování při chybě:

• Non-2xx status throwne error. Chyba nese vlastnost err.meta s objektem { status, statusText, data }. V catch bloku vždy guarduj — chyba nemusí být HTTP (timeout, DNS), pak err.meta neexistuje:

try {
  const data = axios.getAxios().get('https://api.example.com/items');
  proc.warn('[API][OK]', { data });
} catch (err) {
  const meta = (err && err.meta) || {};
  proc.warn(`[API][Error] ${meta.statusText || err.message}`, { cause: err });
}

Raw varianty — přístup k status a headers

Raw varianty (requestRaw, sendFileRaw, sendFilesRaw) vracejí plný objekt odpovědi { data, status, statusText, headers }. Používej je jen výjimečně — když z úspěšné odpovědi potřebuješ status nebo headers (např. ID dávky z hlavičky). Na rozdíl od klasických metod na non-2xx nethrownou, takže status musíš kontrolovat ručně.

Ukázka použití

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

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

if (result.status !== 200) {
  throw new Error(`[API][Error] ${result.statusText}`);
}

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"
  }
}

XML nebo plain text — Buffer.from

axios nativně předává data jako JSON. Pokud potřebuješ poslat XML, plain text apod., je nutné říct axios, aby data netransformoval — k tomu slouží Buffer.from. Funkce převede textový řetězec na binární data (Buffer) v kódování UTF-8.

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

axios.getAxios().post('https://api.example.com/soap', payload, {
  headers: { 'Content-Type': 'text/xml' }
});

Odesílání souborů a FormData

Jeden soubor — sendFile (raw varianta sendFileRaw od v5.7.37):

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

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

Více souborů přes FormData — sendFiles (raw varianta sendFilesRaw od v5.7.37):

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()
});

Formulářová data — post s FormData:

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říklad — odeslání souboru do systému s API klíčem v hlavičce

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 filePath = exportDmsFile(dmsEntity, invNumber);

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

Ukázka odpovědi

{
  "data": "",
  "status": 202,
  "statusText": "Accepted",
  "headers": {
    "content-length": "0",
    "operation-location": "https://api.example.com/123",
    "apim-request-id": "xxx-abfd-xx-a820-xxxx",
    "x-ms-region": "West Europe",
    "date": "Thu, 24 Jul 2025 09:43:36 GMT"
  }
}

Autentizace: Trezor a certifikáty

Tajemství (API klíče, tokeny, hesla) ani certifikáty se do kódu nikdy nepíšou napřímo — unikaly by v exportu šablony i v logu. TAS pro ně má vyhrazené mechanismy popsané v samostatných článcích:

• Autentizace přes Trezor (Vault) — dosazení tokenů, API klíčů a hesel do hlaviček, query parametrů a těla požadavku bez toho, aby tajemství prošlo kódem:

• Klientské SSL certifikáty (mTLS) — nastavení certifikátů pro vzájemně ověřované HTTPS spojení:

Příklady použití

GET — získání kurzů z ČNB

function axiosGetDataByURL(requestURL) {
  try {
    return axios.getAxios().get(requestURL);
  } catch (error) {
    return {
      error: true,
      fullError: error,
      statusCode: error?.meta?.status,
      statusText: error?.meta?.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 }
  );
}

PATCH — aktualizace dat na docs.syca.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íl mezi curl a axios — porovnání

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/.../denni_kurz.txt?date=${formatDate}`);

  var crossRate = curl.perform();
  try {
    const body = crossRate.data;
    // ...
  }
}

Volání kurzů ČNB — axios

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

  const url = `https://www.cnb.cz/.../denni_kurz.txt?date=${formatDate}`;
  const body = axios.getAxios().get(url);

  try {
    const rows = body.split('\n');
    // ...
  }
}