Manuální práce s API s nástrojem Postman

Pokud nechcete integrovat naše API do stávajících procesů, či nemáte kam, pomůže vám tento návod pro posílání API požadavků pomocí nástroje Postman. Díky němu máte hotové prostředí pro posílání dotazů a námi předkonfigurované funkce. Zcela bez znalosti programování tak můžete využít API SSLmarketu a ušetřit váš čas.

Integrace SSLmarket API do jiných prostředí má výhody v tom, že řešení můžete realizovat komplexně. V návodu popisované řešení nemůže nikdy fungovat automatizovaně, je manuální, ale alespoň vám ušetří čas.

Instalace aplikace Postman

Na webu si stáhněte verzi pro váš desktop. Aplikace Postman existuje i ve webové verzi, ale ta je pro náš účel nevhodná (nefunguje).

Verze pro Windows se instaluje tradičním způsobem, v linuxu budete mít Postman pravděpodobně k dispozici jako snap balíček. V terminálu tedy zadejte:

sudo snap install postman
Pak program spusťte. Po spuštění vás požádá o přihlášení či vytvoření uživatelského účtu; to lze však přeskočit díky nenápadnému odkazu úplně na spodu okna. Přihlášení na Postman účet přináší výhodu synchronizace projektů mezi jednotlivými instancemi. Na svou práci můžete jednoduše navázat i doma. Pokud nechcete využít výhod účtu a synchronizace, nebo jenom testujete, přihlašovat se nemusíte.

Nastavení aplikace pro SSLmarket

Pro maximální zjednodušení práce s API a programem jsme vám připravili "kolekci" volání v souboru JSON, kterou stačí naimportovat a všechny funkce máte hned k dispozici. Importujte kolekci (tlačítko vlevo nahoře "import"), pak zvolte od nás připravený soubor JSON. V Collections uvidíte položku SSLmarket a deset funkcí. Klikněte na kolekci SSLmarket pravým tlačítkem a nastavte proměnné v "Edit → Variables".

editace proměnných
Editace proměnných pro Collection. Klikněte pro zvětšení.

Nejdůležitější je nastavit proměnou X-Auth-Token hodnotou ze zák. Účtu. Ostatní proměnné jistě logicky spojíte se správnými hodnotami, ale níže najdete jejich přehled.

Vysvětlení polí

  • X-Auth-Token – pole pro vložení API klíče
  • owner_### - údaje budoucího vlastníka certifikátu pro upřesnění.
  • auth_### - údaje autorizačního kontaktu, který u certifikátů s ověřením potvrzuje objednávku.
  • tech_### - údaje technického kontaktu. Ten do ověření nevstupuje, ale obdrží vydaný certifikát e-mailem.
  • invoice_### - pole pro upřesnění fakturačních údajů; tyto informace definují odběratele na faktuře.
nastavené proměnné
Nastavené proměnné pro Collection. Klikněte pro zvětšení.

Tyto výchozí údaje se budou nabízet v proměnných (například při zadání objednávky) a nebudete je muset zadávat znovu. Pokud vám není některé z polí jasné, najdete je v dokumentaci API.

Po dokončení nastavení a uvedení všech informací můžete začít posílat požadavky do API SSLmarketu.

Zasílání požadavků

Po nastavení programu můžete začít posílat požadavky a zejména nové objednávky. CSR musí být bez mezer a zalomení, ty je třeba vyřešit pomocí escape sekvence. Více v následujícím odstavci.

Vyberte v kolekci funkci API, kterou chcete využít. Pak v pravé (velké) části okna v záložce Body uvidíte konstrukci dotazu. Například při vložení objednávky jsou tam všechny informace k budoucímu certifikátu (rozsah odpovídá objednávce na webu). Informace uvedené v závorkách znamenají, že bude použita daná proměnná, kterou jste dříve definovali - například {{owner_name}}. Tyto položky upravujete pouze pokud potřebujete použít jiné než výchozí údaje.

Údaje pro vložení objednávky

Údaje o žadateli a kontaktech se vám načtou z připravených výchozích údajů. Pro každou objednávku je potřeba upřesnit tyto specifické údaje:

  • domain - Common name certifikátu
  • dns_names - seznam SANů v certifikátu
  • years - počet let platnosti objednávky (platnost certifikátu je omezena, ale objednávka může být na více let)
  • csr - zde vložte CSR (musí být bez řádkování a mezer, viz níže). Je to nepovinný údaj a CSR můžete do SSLmarketu vložit i po vložení objednávky přes API.
  • dv_auth_method - volba způsobu ověření DCV (email, dns, ftp)

Když jsou všechny údaje vyplněny a požadavek je připraven, pak ho do API odešlete po kliknutí na modré tlačítko Send.

Průběh a výsledek dotazu vidíte ve spodní části okna. Pokud je výsledek úspěšný, dostanete zpět požadovanou informaci či číslo objednávky, pokud jste objednávku vkládali. V opačném případě dostanete zpět chybovou hlášku, která konkretizuje co je v dotazu špatně či co chybí.

Příklad úspěšného vložení objednávky:

{
    "order_id": "155252"
}

Příklad chybové hlášky:

   {
    "error": [
        "dv_auth_method => isEmpty - Položka je povinná a nesmí být prázdná"
    ]
}

Možné kolize při zasílání objednávek

  • Použité URL – použijte URL endpointu ve tvaru www.sslmarket.tld, nikoliv pouze sslmarket.tld. Na základní doméně dochází k přesměrování a následně problémům s requesty.
  • CSR request - Dejte pozor, aby CSR nebylo rozděleno na více řádků. Pokud vám dělá problémy vložit CSR ve správném tvaru, tak pošlete objednávku bez něj a vložte ho standardně přes administraci.
    • CSR není možné poslat rozdělené na řádky, byť ho takto ze svého serveru dostanete.
    • V CSR nesmí být mezery, konce řádků či zalomení odstavců; řádky zakončete „escape sekvencí“ rn.
    • CSR snadno upravíte do vhodného tvaru jedním klikem s použitím nástroje Remove or replace line breaks. Zvolte možnost „Replace line breaks with customer text“ a jako custom text dejte rn. Ostatní možnosti zrušte a klikněte na zelené tlačítko níže.

FAQ pro manuální využití API

Z pohledu dostupných funkcí samozřejmě nikoliv, oba přístupy nesou stejné výsledky. Využití API SSLmarketu pomocí nástroje Postman vám ušetří čas a náklady na integraci API do jiného systému, avšak je potřeba akce spouštět manuálně, což je jediná nevýhoda tohoto přístupu. Nemůžete si zautomatizovat objednávání či prodlužování certifikátů, na to je potřeba vlastní řešení s implementací naší API.

Všechny objednávky najdete na vašem zákaznickém účtu tak, jak byste je zadali tradičním způsobem přes web. Váš požadavek identifikuje ke správnému účtu vygenerovaný API klíč.

Fakturace funguje tradičním způsobem, takže pro využití API doporučujeme kreditní účet s automatickou úhradou objednávek.