Swiftyper API

Úlohou API je sprístupnenie softvérového rozhrania na prístup k službám súvisiacimi s vyhľadaním miest, právnických osôb a SZČO.

Služba je postavená na REST architektúre. JSON je výstupom všetkých odpovedí z API aj vrátane chýb. V prípade použitia API knižnice prevedieme odpoveď na objekt programovacieho jayzka knižnice.

Autentifikácia

Napojenie na Swiftyper API prebieha vyžiadaním API kľúča cez hlavičku X-Swiftyper-API-Key alebo parameter api_key.

Spravovať API kľúče môžete cez Váš používateľský účet.

API kľúče sú predvolene neobmedzené. Neobmedzené kľúče nie sú bezpečné, pretože ich môže používať ktokoľvek a odkiaľkoľvek. Pre produkčné aplikácie odporúčame nastaviť obmedzenia API kľúča nakoľko pomáhajú zabrániť neoprávnenému použitiu a vyčerpávaniu kvót. Obmedzenia určujú, ktoré webové stránky alebo IP adresy môžu používať API kľúč.

Všetky API požiadavky musia byť smerované prostredníctvom protokolu HTTPS. Požiadavky smerované cez protokol HTTP nebudú spracované. Pri všetkých požiadavkách je nevyhnutná autentifikácia.

Chybové kódy

Používame bežné HTTP kódy odpovedí na indikáciu úspechu alebo neúspechu API požiadavky. Kódy v rozsahu 2xx všeobecne označujú úspech, kódy v rozsahu 4xx indikujú chybu, ktorá vznikla na základe poskytnutých informácií (napr. chýajúci požadovaný parameter, presiahnutie limitu atď.). Kódy v rozsahu 5xx indikujú chybu na našich serveroch.

Odchytávanie chýb

Naše API knižnice môžu vyvolať výnimky z mnohých dôvodov, napríklad z dôvodu prekročenia mesačného limitu, neplatných parametrov, chýb autentifikácie a nedostupnosti siete. Odporúčame vždy sa pokúsiť elegantne zvládnuť výnimky z nášho API.

Dostupné subjekty

Údaje čerpáme z referenčných registrov verejnej správy. Informácie o právnických osobách sú pravideľne aktualizované zo zdrojových registrov (napr. obchodný register, živnostenský register).

Údaje aktualizujeme v závislosti od dostupnosti vydania nových datasetov - zvyčajne raz denne.

Aktuálne poskytujeme register právnických osôb a SZČO a ich kontaktné a fakturačné údaje týchto krajin:

Dostupné krajiny

Údaje čerpáme z referenčných registrov verejnej správy. Informácie o adresách sú pravideľne aktualizované zo zdrojových registrov.

Údaje aktualizujeme v závislosti od dostupnosti vydania nových datasetov - zvyčajne raz denne.

Aktuálne poskytujeme adriesy a ich metadáta týchto krajin:

Popis atribútov číselníka

Číselník krajov

Zobrazenie základného zoznamu obsahujúceho kraje konkrétnej krajiny. Zobrazenie číselníku sa nepočíta do mesačého limitu. Číselníky sa zobrazujú vždy celé.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba.

Číselník okresov

Zobrazenie základného zoznamu obsahujúceho okresy konkrétnej krajiny. Zobrazenie číselníku sa nepočíta do mesačého limitu. Číselníky sa zobrazujú vždy celé.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba.

Číselník miest a obcí

Zobrazenie základného zoznamu obsahujúceho mestá a obce konkrétnej krajiny. Zobrazenie číselníku sa nepočíta do mesačého limitu. Číselníky sa zobrazujú vždy celé.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba.

Poštové adresy

Prostredníctvom služby Swiftyper Places API je možné vyhľadať viacero druhov miest - adresu, ulicu, obec a poštové smerovacie číslo.

Popis atribútov

Vyhľadanie adresy

Vyhľadanie poštových adries cez akúkoľvek časť adresy.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Vyhľadanie ulice

Vyhľadanie ulíc na základe názvu.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Vyhľadanie obce

Vyhľadanie obcí na základe názvu.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Vyhľadanie PSČ

Vyhľadanie poštového smerovacieho čísla na základe kódu.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Detail miesta

Načítanie podrobností na základe identifikátora miesta. Prostredníctvom identifikátora je možné načítať adresu, ulicu, obec a poštové smerovacie čísla.

Výstup

Výstupom je v prípade platného id objekt s popísanými atribútmi, v opačnom pripade sa zobrazí chyba.

Reverzné geokódovanie

Vyhľadávanie adresy podľa zemepisných súradníc (GPS, systém WGS84).

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Fakturačné adresy

Prostredníctvom služby Swiftyper Business API je možné vyhľadať právnicke osoby a SZČO viacerými spôsobmi - prostredníctvom identifikačného čísla organizácie a na základe názvu právnickej osoby prípadne SZČO.

Popis atribútov

Vyhľadanie subjektu

Vyhľadanie kontaktných a fakturačných údajov o právnických osobách a SZČO na základe názvu právnickej osoby prípadne SZČO.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Vyhľadanie podľa IČO

Vyhľadanie kontaktných a fakturačných údajov o právnických osobách a SZČO na základe identifikačného čísla organizácie.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Detail subjektu

Načítanie podrobností právnickej osoby a SZČO na základe identifikátora subjektu.

Výstup

Výstupom je v prípade platného id objekt s popísanými atribútmi, v opačnom pripade sa zobrazí chyba.

Preklady

Prostredníctvom služby Swiftyper Internationalization API je možné vyhľadať a preložiť uložené natívne frázy vašej aplikácie.

Popis atribútov fráz

Vyhľadanie fráz

Vyhľadanie natívnych fráz. Pokiaľ nepoužijete vyhľadávanie, výstupom budú všetky frázy.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Uloženie fráz

Uloženie natívnych fráz v anglickom jazyku do databázy aby sa dali preložiť. Ďalšie informácie o prekladoch nájdete v časti Preklady.

Výstup

Výstupom je informácia o počte úspešne uložených frázach. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Popis atribútov prekladov

Vyhľadanie prekladov

Vyhľadanie a načítanie prekladov. Pokiaľ nepoužijete vyhľadávanie, výstupom budú iba preklady ktoré boli schválené automaticky (podľa počtu hlasov), alebo manuálne.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Uloženie prekladu

Uloženie prekladu frázy do vybraného jazyka.

Výstup

Výstupom je objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Poštové adresy

Účelom rozšírenia je rýchle vkladanie adries bez nutnosti vyplňovania všetkých adresných polí formulára na webovej stránke alebo v mobilnej aplikácii.

Vyhľadávacia stratégia

Výsledky vyhľadávania prispôsobujeme podľa zadanej adresy vo formulári. Keď začnete vypĺňaním krajiny alebo obce, zobrazíme adresy týkajúce sa tohto miesta.

Podporované prehliadače

Inštalácia

Ponúkame viacero spôsobov ako môžete integrovať službu Swiftyper Places WebAPI do Vašej aplikácie.

CDN <script>

JavaScriptová knižnica je dostupná na platforme jsDelivr CDN.
<script src="https://cdn.jsdelivr.net/npm/swiftyper.js@1.0.6"></script>

Príklad použitia v kóde:
<script src="https://cdn.jsdelivr.net/npm/swiftyper.js@1.0.6"></script>

<div>
    <input type="text" id="ulica" placeholder="Ulica, číslo" />
</div>
<div>
    <input type="text" id="psc" placeholder="PSČ" />
</div>
<div>
    <input type="text" id="mesto" placeholder="Mesto" />
</div>
<div>
    <input type="text" id="krajina" placeholder="Krajina" />
<div>

<script>
  var placesAutocomplete = new swiftyper.places({
      selectors: {
          street: document.querySelector('#ulica'),
          municipality: document.querySelector('#mesto'),
          postalCode: document.querySelector('#psc'),
          country: document.querySelector('#krajina'),
      },
      apiKey: '2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y',
  });
</script>

npm

Nájdete nás aj na npm.

Na inštaláciu stačí zadať príkaz:
npm install swiftyper.js --save

Príklad použitia v HTML:
<div>
<input type="text" id="ulica" placeholder="Ulica, číslo" />
</div>
<div>
<input type="text" id="psc" placeholder="PSČ" />
</div>
<div>
<input type="text" id="mesto" placeholder="Mesto" />
</div>
<div>
<input type="text" id="country" placeholder="Krajina" />
<div>

Príklad použitia v JavaScripte:
const { places } = require('swiftyper.js');

const placesAutocomplete = new places({
  selectors: {
      street: document.querySelector('#ulica'),
      municipality: document.querySelector('#mesto'),
      postalCode: document.querySelector('#psc'),
      country: document.querySelector('#krajina'),
  },
  apiKey: '2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y',
});

Nastavenia

Popis nastavení ktoré môžete použiť v metóde places({ nastavenia }).

Udalosti

Rozšírenie používa určité udalosti, ktoré si môžete prispôsobiť.

Metódy

Popis metód ktoré môžete použiť po inicializácii metódy places().

Štýlovanie

Rozšírenie používa pár základných CSS tried a tágov ktoré si môžete pre vašu aplikáciu prispôsobiť.

Príklady použitia

Poštovú adresu je možné zadať niekoľkými spôsobmi, v týchto príkladoch použitia uvádzame tie najpoužívanejšie.

Fakturačné adresy

Účelom rozšírenia je rýchle vkladanie fakturačných údajov bez nutnosti vyplňovania všetkých adresných polí formulára na webovej stránke alebo v mobilnej aplikácii.

Podporované prehliadače

Inštalácia

Ponúkame viacero spôsobov ako môžete integrovať službu Swiftyper Business WebAPI do Vašej aplikácie.

CDN <script>

JavaScriptová knižnica je dostupná na platforme jsDelivr CDN.
<script src="https://cdn.jsdelivr.net/npm/swiftyper.js@1.0.6"></script>

Príklad použitia v kóde:
<script src="https://cdn.jsdelivr.net/npm/swiftyper.js@1.0.6"></script>

<div>
    <input type="text" id="subjekt" placeholder="Názov organizácie" />
</div>
<div>
    <input type="text" id="ico" placeholder="IČO" />
</div>
<div>
    <input type="text" id="ic_dph" placeholder="IČ DPH" />
</div>
<div>
    <input type="text" id="dic" placeholder="DIČ" />
</div>
<div>
    <input type="text" id="ulica" placeholder="Ulica, číslo" />
</div>
<div>
    <input type="text" id="psc" placeholder="PSČ" />
</div>
<div>
    <input type="text" id="mesto" placeholder="Mesto" />
</div>
<div>
    <input type="text" id="krajina" placeholder="Krajina" />
</div>

<script>
  var businessAutocomplete = new swiftyper.business({
      selectors: {
          name: document.querySelector('#subjekt'),
          cin: document.querySelector('#ico'),
          tin: document.querySelector('#dic'),
          vatin: document.querySelector('#ic_dph'),
          street: document.querySelector('#ulica'),
          municipality: document.querySelector('#mesto'),
          postalCode: document.querySelector('#psc'),
          country: document.querySelector('#krajina'),
      },
      apiKey: 'v6S9BbdkN817Rvaw15RLsaVo7bZCBNH63wgPgTcqaxO9',
  });
</script>

npm

Nájdete nás aj na npm.

Na inštaláciu stačí zadať príkaz:
npm install swiftyper.js --save

Príklad použitia v HTML:
<div>
<input type="text" id="subjekt" placeholder="Názov organizácie" />
</div>
<div>
<input type="text" id="ico" placeholder="IČO" />
</div>
<div>
<input type="text" id="ic_dph" placeholder="IČ DPH" />
</div>
<div>
<input type="text" id="dic" placeholder="DIČ" />
</div>
<div>
<input type="text" id="ulica" placeholder="Ulica, číslo" />
</div>
<div>
<input type="text" id="psc" placeholder="PSČ" />
</div>
<div>
<input type="text" id="mesto" placeholder="Mesto" />
</div>
<div>
<input type="text" id="krajina" placeholder="Krajina" />
<div>

Príklad použitia v JavaScripte:
const { business } = require('swiftyper.js');

const businessAutocomplete = new business({
  selectors: {
            name: "#subjekt",
            cin: "#ico",
            tin: "#dic",
            vatin: "#ic_dph",
            street: "#ulica",
            municipality: "#mesto",
            postalCode: "#psc",
            country: "#krajina",
  },
  apiKey: 'v6S9BbdkN817Rvaw15RLsaVo7bZCBNH63wgPgTcqaxO9',
});

Nastavenia

Popis nastavení ktoré môžete použiť v metóde business({ nastavenia }).

Udalosti

Rozšírenie používa určité udalosti, ktoré si môžete prispôsobiť.

Metódy

Popis metód ktoré môžete použiť po inicializácii metódy business().

Štýlovanie

Rozšírenie používa pár základných CSS tried a tágov ktoré si môžete pre vašu aplikáciu prispôsobiť.

Príklady použitia