Manuálna práca s API s nástrojom Postman

Pokiaľ nechcete integrovať naše API do existujúcich procesov, či nemáte kam, pomôže vám tento návod pre posielanie API požiadaviek pomocou nástroja Postman. Celkovo bez znalosti programovania, tak môžete využiť API SSLmarketu a ušetriť váš čas.

Integrácia SSLmarket API do iných prostredí má výhody v tom, že riešenie môžete realizovať komplexne. V návode popisované riešenie nemôže nikdy fungovať automatizovane, je manuálne, ale aspoň vám ušetrí čas.

Inštalácia aplikácie Postman

Na webu si stiahnete verziu pre váš desktop. Aplikácia Postman existuje aj vo webovej verzií, ale tá je pre náš účel nevhodná (nefunguje).

Verzia pre Windows sa inštaluje tradičným spôsobom, v linuxe budete mať Postman pravdepodobne k dispozícii ako snap balíček. V terminále teda zadajte:

sudo snap install postman

Nastavenie aplikácie pre SSLmarket

Pre maximálne zjednodušenie práce s API a programom sme vám pripravili "kolekciu" volaní v súbore JSON, ktorú stačí naimportovať a všetky funkcie máte hneď k dispozícii. Importujte kolekciu (tlačítko vľavo hore "import"), potom zvoľte od nás pripravený súbor JSON. V Collections uvidíte položku SSLmarket a desať funkcií. Kliknite na kolekciu SSLmarket pravým tlačítkom a nastavte premenné v "Edit → Variables".

Najdôležitejšie je nastaviť premennú X-Auth-Token hodnotu zo zák. Účtu. Ostatné premenné iste logicky spojíte so správnymi hodnotami, ale nižšie nájdete ich prehľad.

Vysvetlenie polí

• X-Auth-Token – pole pre vložení API kľúča
• owner_### - údaje budúceho vlastníka certifikátu pre upresnenie.
• auth_### - údaje autorizačného kontaktu, ktorý pri certifikáte s overením potvrdzuje objednávku.
• tech_### - údaje technického kontaktu. Ten do overenia nevstupuje, ale obdrží vydaný certifikát e-mailom.
• invoice_### - pole pre upresnenie fakturačných údajov; tieto informácie definujú odberateľa na fakture.

Tieto defaultné údaje sa budú ponúkať v premenných (napríklad pri zadaní objednávky) a nebudete ich musieť zadávať znovu. Pokiaľ vám nie je niektoré z polí jasné, nájdete ich v dokumentácii API.

Po dokončení nastavení a uvedení všetkých informácii môžete začať posielať požiadavky do do API SSLmarketu.

Zasielanie požiadaviek

Po nastavení programu môžete začať posielať požiadavky a hlavne nové objednávky. CSR musí byť bez medzier a zalomení, tie je potreba vyriešiť pomocou escape sekvencie. Viac v následujúcom odstavci.

Vyberte v kolekcii funkciu API, ktorú chcete využiť. Potom v pravej (veľkej) časti okna v záložke Body uvidíte konštrukciu dotazou. Napríklad pri vložení objednávky sú tam všetky informácie k budúcemu certifikátu (rozsah zodpovedá objednávke na webe). Informácie uvedené v zátvorkách znamenajú, že bude použitá daná premenná, ktorú ste definovali skôr - napríklad {{owner_name}}. Tieto položky upravujete iba pokiaľ potrebujete použiť iné než defaultné údaje.

Údaje pre vloženie objednávky

Údaje o žiadateľovi a kontaktoch sa vám načítajú z pripravených defaultných údajov. Pre každú objednávku je potreba upresniť tieto špecifické údaje:

• domain - Common name certifikátu
• dns_names - zoznam SANov v certifikáte
• years - počet rokov platnosti objednávky (platnosť certifikátu je obmedzená, ale objednávka môže byť na viac rokov)
• csr - sem vložte CSR (musí byť bez riadkovania a medzie, viď nižšie). Je to nepovinný údaj a CSR môžete do SSLmarketu vložiť aj po vložení objednávky cez API.
• dv_auth_method - voľba spôsobu overenia DCV (email, dns, ftp)

Keď sú všetky údaje vyplnené a požiadavka je pripravená, potom ju do API odošlite po kliknutí na modré tlačítko Send.

Priebeh a výsledok požiadaviek vidíte v spodnej časti okna. Pokiaľ je výsledok úspešný, dostanete späť požadovanú informáciu či číslo objednávky, pokiaľ ste objednávku vkladali. V opačnom prípade dostanete späť chybovú hlášku, ktorá konkretizuje čo je v požiadavke zle alebo čo chýba.

Príklad úspešného vloženia objednávky:

{
    "order_id": "155252"
}

Príklad chybovej hlášky:

   {
    "error": [
        "dv_auth_method => isEmpty - Položka je povinná a nesmie byť prázdná"
    ]
}

Možné kolízie pri zasielaní obejdnávok

• Použité URL – použite URL endpointu v tvare www.sslmarket.tld, nie iba sllmarket.tld. Na základnej doméne dochádza k presmerovaniu a následne problémom s requestmi.
• CSR request - Dajte pozor, aby CSR nebolo rozdelené na viac riadkov. Pokiaľ vám robí problémy vložiť CSR v správnom tvare, tak pošlite objednávku bez neho a vložte ho štandardne cez administráciu.
  • CSR nie je možné poslať rozdelené na riadky, aj keď ho takto zo svojho serveru dostanete.
  • V CSR nemôžu byť medzery, kone riadkov či zalomenie odstavcov; riadky zakončite „escape sekvenciou“ rn.
  • CSR ľahko upravíte do vhodného tvaru jedným kliknutím s použitím nástroja Remove or replace line breaks. Zvoľte možnosť „Replace line breaks with customer text“ a ako custom text dajte rn. Ostatné možnosti zrušte a kliknite na zelené tlačítko nižšie.

FAQ pre manuálne využitie API