O projekte - návody
Integrácia cez webové služby umožňuje prepojenie formulárov umiestnených na portáli ipdf.sk s akoukoľvek aplikáciou tretích strán. Podporované sú tri spôsoby integrácie:
- iframe - najjednoduchší spôsob, možná úprava dizajnu a pridanie špecifických funkcií
- JSON - preferovaný spôsob, vyžaduje programovanie na strane partnera, integrácia do aplikácií
- SOAP - nepreferovaný spôsob, vyžaduje programovanie na strane partnera, integrácia do aplikácií
Pre všetky typy integrácie platí, že vytvárané tlačivá sa ukladajú v archíve autorizovaného užívateľa. Je teda možné s nimi manipulavať rovnako ako s bežnými tlačivami - stiahnuť, nahrať a upraviť, odoslať na email atď. Zároveň je potrebné v Nastaveniach účtu správne nastaviť životnosť a maximálny povolený počet tlačív (kvóta) s ohľadom na predpokladaný počet tlačív vytvorených prostredníctvom integrácie. V prípade vyčerpania povolenej kvóty na počet tlačív by sa návštevníkom tlačivo nevytvorilo, ale zobrazilo by sa chybové upozornenie.
Iframe integrácia je najjednoduchším variantom integrácie nakoľko nevyžaduje zo strany partnera takmer žiadne programovanie.
Realizuje sa vložením HTML elementu <iframe> na partnerskej webstránke, pričom kód obsahuje pridelený autentifikačný kľúč užívateľa.
Kód aj s inštrukciami na jeho umiestnenie dodáme po preverení partnerskej stránky, prípadne prispôsobeniu dizajnu alebo požadovaných špecifických funkcií.
Príklad 1 - Vložený kód na partnerský web v prípade iframe integrácie:
<iframe src="https://ipdf.sk/your-integrated-formular?iframe=your-auth-key-123!abc..">
<noframes>Váš prehliadač nepodporuje iframes. Odporúčame prejsť na moderný prehliadač, napr. Chrome.</noframes>
</iframe>
JSON integrácia vyžaduje programovanie na strane partnera - tzn. vyzbieranie údajov pre vyplnenie polí vo formulári a ich odoslanie v autentifikovanej API požiadavke. Tento typ integrácie je vhodný napr. v prípade, keď už poznáte údaje potrebné pre vyplnenie formulára z vlastnej databázy a potrebujete z nich vygenerovať PDF tlačivo, pričom sa nechcete zaoberať jeho údržbou resp. aktualizáciou. Príkladom môže byť faktúra - pokiaľ máte už vyzbierané údaje odberateľa a dodávateľa, stačí doplniť fakturované položky (popis, sumu a sadzbu DPH) a odoslať požiadavku na linku s formulárom na portáli ipdf.sk - viď príklad nižšie. Dôležité linky pre vytvorebnie JSON požiadavky:
- Popis atribútov: https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura?help
- Vzor JSON implementácie: https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura?json
Odosielaná JSON požiadavka musí byť odoslaná metódou POST a musí obsahovať nasledujúce atribúty:
- json - identifikátor výstupného formátu
- key - autentifikačný kľúč pridelený užívateľovi
- data - zakódovaný JSON reťazec s hodnotami pre vyplnenie polí v cieľovom formulári
Vrátená odpoveď zo servera ipdf.sk obsahuje nasledujúce atribúty:
- success - 0 alebo 1, kde 1 = úspech, tzn. tlačivo bolo vytvorené a uložené v archíve užívateľa
- info - popis chýb v prípade neúspechu
- file_name - názov vytvoreného tlačiva v archíve užívateľa
- download_link - linka pre stiahnutie tlačiva z archívu platná 24 hodín od momentu vytvorenia
- file_content - zakódovaný obsah vytvoreného PDF súboru pre uloženie v prípade potreby na volajúcom serveri partnera (base64 binary stream)
Príklad 2 - Odoslanie autentifikovanej JSON požiadavky:
<?php
// Odoslanie JSON požiadavky
// =========================
$url = "https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura";
$data = array(
// povinný parameter "json"
"json" => 1,
// povinný autentifikačný API kľúč
"key" => "uARM_PXyvI***********************",
// hodnoty pre vyplnenie polí vo formulári, popis atribútov vždy na linke s parametrom "?help":
// https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura?help
"data" => json_encode([
"A000_CISLO_FAKTURY" => "20250123",
"A001_DODAVATEL_MENO" => "Dodavateľ s.r.o.",
"A002_DODAVATEL_ULICA_CISLO_DOMU" => "Dodávateľská 99",
"A003_DODAVATEL_PSC" => "01234",
"A004_DODAVATEL_MESTO" => "Dodávkovce pod Nitrou",
"A005_DODAVATEL_ICO" => "10203040",
"A006_DODAVATEL_ICDPH" => "1023459899",
"A007_DODAVATEL_TELEFON" => "0903 123456",
"A008_DODAVATEL_EMAIL" => "dodavatel@mymail.tld",
"A009_DODAVATEL_CISLO_REGISTRA" => "Fyzická osoba zapísaná v registri 123456/CC OÚ Bratislava II.",
"A011_DODAVATEL_BANKOVY_UCET" => "SK69 0200 0000 0026 1108 1080",
"A013_DATUM_VYSTAVENIA" => "02.04.2025",
"A014_DATUM_SPLATNOSTI" => "16.04.2025",
"A015_DATUM_DODANIA_SLUZBY" => "02.04.2025",
"A016_VARIABILNY_SYMBOL" => "20250123",
"A017_KONSTANTNY_SYMBOL" => "0308",
"A018_ODBERATEL_MENO" => "Odberateľ a.s.",
"A019_ODBERATEL_ULICA_CISLO_DOMU" => "Odberová ul. 123",
"A020_ODBERATEL_PSC" => "12345",
"A021_ODBERATEL_MESTO" => "Odberovce nad Nitrou",
"A022_ODBERATEL_ICO" => "40302010",
"A023_ODBERATEL_ICDPH" => "998954102",
"A024_SUMA_BEZ_DPH" => "200",
"A025_ZAKLAD_DANE" => "200",
"A026_DPH_CELKOM" => "46",
"A027_SUMA_S_DPH" => "246",
"A028_PRILOHY" => "Ďakujeme a tešíme sa na ďalšiu spoluprácu.",
"A029_VYSTAVIL" => "Roman Dodávateľ, 0903 123456",
"A030_TEXT_FAKTURUJEME_VAM" => "Faktúrujeme Vám za dodané služby nasledovné:",
"A049_DOKLAD_ZALOHA" => "15/230",
"A050_ZALOHA" => "-50",
"A055_SUMA_NA_UHRADU" => "196",
"CURRENCY" => "EUR",
"__TEMPLATES__" =>
array (
"polozky" =>
array (
0 =>
array (
"POLOZKA_NAZOV" => "Položka prvá popis ..",
"POLOZKA_MNOZSTVO" => "10",
"POLOZKA_JEDNOTKA" => "kg",
"POLOZKA_DPH_SADZBA" => "23",
),
),
),
)
]),
);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
// uncomment in test environment
// curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
// curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
$json_response = curl_exec($curl);
if (curl_errno($curl)){
die("Chyba: " . curl_error($curl));
}
curl_close($curl);
$response = json_decode($json_response, true);
// Spracovanie odpovede
// ====================
$response = json_decode($json_response, true);
if(empty($response["file_content"])){
exit("Súbor sa nepodarilo vytvoriť. Popis chyby: ".$response["info"]);
}else{
file_put_contents("/path/to/save.pdf", base64_decode($response["file_content"]));
echo "Úspech! ".$response["info"];
}
?>
SOAP integrácia vyžaduje podobne ako JSON programovanie na strane partnera - tzn. vyzbieranie údajov pre vyplnenie polí vo formulári a ich odoslanie v autentifikovanej API požiadavke. SOAP však nie je preferovaný spôsob integrácie vzhľadom ku potenciálnym technickým komplikáciám. Pokiaľ to je možné, odporúčame využiť JSON integráciu. Rozdiely medzi obidvoma spôsobmi sú skôr technického charakteru, výstup a spracovanie odpovede je rovnaké. SOAP vyžaduje dodatočnú definíciu elementov vo formáte WSDL. Potom linky potrebné pre kompletnú SOAP integráciu v prípade faktúry budú:
- WSDL: https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura?wsdl
- Endpoint / Služba: https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura?soap
- Popis atribútov: https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura?help
- Vzor SOAP implementácie: https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura?help-soap
Pre odoslanie SOAP požiadavky je potrebné mať inštalované (v prípade PHP) rozšírenie
SoapClient
a tlačivo sa vygeneruje metódou generate s nasledovnými parametrami:
- key - autentifikačný kľúč pridelený užívateľovi
- data - dátová štruktúra (pole alebo objekt) obsahujúca hodnoty pre vyplnenie polí v cieľovom formulári
Vrátená odpoveď zo servera ipdf.sk obsahuje nasledujúce atribúty:
- success - 0 alebo 1, kde 1 = úspech, tzn. tlačivo bolo vytvorené a uložené v archíve užívateľa
- info - popis chýb v prípade neúspechu
- file_name - názov vytvoreného tlačiva v archíve užívateľa
- download_link - linka pre stiahnutie tlačiva z archívu platná 24 hodín od momentu vytvorenia
- file_content - zakódovaný obsah vytvoreného PDF súboru pre uloženie v prípade potreby na volajúcom serveri partnera (base64 binary stream)
Príklad 3 - Odoslanie autentifikovanej SOAP požiadavky:
<?php
// Odoslanie SOAP požiadavky
// =========================
$api_key = "uARM_PXyvI***********************";
$data = [
// hodnoty pre vyplnenie polí vo formulári, popis atribútov vždy na linke s parametrom "?help":
// https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura?help
"fields" => [
"A000_CISLO_FAKTURY" => "20250123",
...
// rovnaká štruktúra ako v prípade JSON - Príklad 2
]
];
try{
// vytvoríme tlačivo
$client = new SoapClient("https://ipdf.sk/uctovne-tlaciva/zalohova-faktura-dobropis-predfaktura?soap");
$response = $client->generate($api_key, $data);
}catch(SoapFault $e){
echo "Chyba pri vytváraní dokumentu: ".$e->getMessage();
}
// Spracovanie odpovede
// ====================
if($response->success == "1"){
echo "Úspech - dokument bol vytvorený. Linka pre stiahnutie dokumentu: ".$response->download_link;
// súbor si môžete uložiť na lokálny disk
file_put_contents("/path/to/save.pdf", base64_decode($response->file_content));
}else{
echo "Dokument sa nepodarilo vytvoriť. Popis chyby: ".$response->info;
}
?>
