Potřebuji zjistit dostupné prostředky na kontě klienta s určitou kartou a vložit mu na konto pohledávku.

Na svém webovém rozhraní získáte aktuální formální popis služby ve formě WSDL. Zde si popíšeme základní princip práce s touto webovou službou.

Všechny metody webové služby využívají k zabezpečení přístupu ověření v hlavičce. Jde o kombinaci loginu, hesla a ID provozu, pod který se budou následně vkládat pohledávky. Login a heslo musí být jakýkoliv platný login do ISKAMu a ID provozu najdete v dialogu Struktura organizace - provoz musí být definován jako typ Externí systém.

Typické použití webové služby je, že klient načte svou kartu na čtečce systému, který se chce na ISKAM napojit. Zná tedy číslo čipu dané karty. Metoda GetCardInfo vrátí základní informace o kartě a jejím majiteli. Volání vypadá typicky takto:

POST /WebServices/CardOperationsSL.asmx HTTP/1.1
Host: <adresa webového rozhraní>
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://aps-brno.cz/GetCardInfo"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthSoapHd xmlns="http://aps-brno.cz/">
      <Login>string</Login>
      <Password>string</Password>
      <LocationID>guid</LocationID>
    </AuthSoapHd>
  </soap:Header>
  <soap:Body>
    <GetCardInfo xmlns="http://aps-brno.cz/">
      <ChipNumber>string</ChipNumber>
    </GetCardInfo>
  </soap:Body>
</soap:Envelope>

Jako odpověď obdržíte strukturu v této podobě:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCardInfoResponse xmlns="http://aps-brno.cz/">
      <GetCardInfoResult>
        <ErrorsOcured>boolean</ErrorsOcured>
        <ID>guid</ID>
        <Number>string</Number>
        <Surname>string</Surname>
        <FirstName>string</FirstName>
        <Title>string</Title>
        <AccountBallance>decimal</AccountBallance>
        <CardValid>boolean</CardValid>
      </GetCardInfoResult>
    </GetCardInfoResponse>
  </soap:Body>
</soap:Envelope>

Před voláním dalších metod webové služby se ujistěte, že je karta platná (CardValid=true) a nedošlo při zjištění údajů k chybám (ErrorsOcured=false). Ve většině případů není povoleno naúčtovat službu, na kterou klient nemá dostatek prostředků (lze to ale pro určité typy služeb povolit), takže důležitý je i vrácený stav konta (AccountBallance).

Toto je nejdůležitější metoda webové služby, slouží k samotnému vložení pohledávky za určitou službu nebo zboží. Volání metody vypadá takto:

POST /WebServices/CardOperationsSL.asmx HTTP/1.1
Host: adresa webového rozhraní
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://aps-brno.cz/PerformOperation"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthSoapHd xmlns="http://aps-brno.cz/">
      <Login>string</Login>
      <Password>string</Password>
      <LocationID>guid</LocationID>
    </AuthSoapHd>
  </soap:Header>
  <soap:Body>
    <PerformOperation xmlns="http://aps-brno.cz/">
      <CardID>guid</CardID>
      <PaymentAmount>decimal</PaymentAmount>
      <ServiceType>string</ServiceType>
      <Description>string</Description>
      <Abbrevitation>string</Abbrevitation>      
      <VATRate>Basic or Reduced or Without or NoneVAT or SecondReduced</VATRate>
      <Source>string</Source>
      <ServiceID>guid</ServiceID>
      <CheckUnique>boolean</CheckUnique>
      <UndoServiceID>guid<UndoServiceID>
    </PerformOperation>
  </soap:Body>
</soap:Envelope>

Parametr CardID je ID z výsledku volání metody GetCardInfo. PaymentAmount je částka, kterou má klient zaplatit (cena služby). ServiceType je právě třípísmenná zkratka typu poskytované služby. Ta musí být předem zadána v katalogu typů služeb v ISKAMu a právě k typu služby se pak dá navázat např. povolení vložit službu i v případě, že klient nemá dostatečné prostředky na účtu. Popis (Description) a zkratka (Abbrevitation) slouží k identifikaci pohledávky pro klienta. Zkratka má maximálně 5 znaků (nejčastěji se používají tři znaky), popis do padesáti znaků (kvůli případným tištěným dokladům je však lepší do třiceti znaků). VATRate je určení sazby DPH, samotná výše DPH se řídí nastavením sazeb DPH v ISKAMu. Source je zdroj financování, slouží pro zaúčtování na správný výnosový a analytický účet. Zdroj musí být předem definován v číselníku zdrojů v ISKAMu a je tedy nutné se na možných hodnotách dohodnout předem s ekonomickým oddělením. Zdroj také případně určuje, zda daná služba podléhá hlášení do EET nebo nikoliv.

ServiceID by měl být jedinečný identifikátor dané transakce v externím systému. V kombinaci s parametrem CheckUnique slouží k zajištění transakčnosti zápisu dané pohledávky. Pokud totiž dojde např. k výpadku spojení během volání metody PerformOperation, tak externí systém neví, zda se transakci podařilo zapsat, nebo nikoliv. Může tedy volání se stejným ServiceID a s CheckUnique=true zopakovat a pokud bude výsledkem chyba, že dané ServiceID již existuje, tak má jistotu, že se transakce zapsala a má ji tedy považovat za přenesenou. Alternativně si to lze ověřit voláním metody GetOperations a vyhledáním daného ServiceID v návratové struktuře.

Parametr UndoServiceID (novinka od 28.5.2021) je nepovinný a typicky se nepoužívá. Slouží k závěrečnému vyúčtování služby, na kterou předtím byla vybrána záloha (viz následující podkapitola). Pokud vámi použitá knihovna pro komunikaci s webovou službou neumožňuje parametr vynechat, tak můžete jako „prázdnou“ hodnotu poslat 00000000-0000-0000-0000-000000000000.

Metoda PerformOperation vrací chybu s vysvětlením, proč se operaci nepodařilo zapsat (a status 500), v případě úspěchu jen prázdnou SOAP hlavičku (status 200).

Pokud klient čerpá službu, jejíž cenu nelze určit předem a poskytnutí trvá dlouho a reálně tak hrozí, že klient mezi voláním metody GetCardInfo a PerformOperation peníze na svém kontě částečně utratí (např. nabíjení elektromobilu), tak je vhodné nejprve vložit pohledávku pro zálohu na takovou službu (de facto udělat blokaci) a po poskytnutí služby vložit finální pohledávku a zálohu uvolnit (stornovat). Prakticky se tedy nejprve zavolá PerformOperation, kde se použije vhodný popis a hlavně vyhrazený zdroj pro zálohovou platbu (aby šlo následně snadno zkontrolovat, že nezůstaly žádné nevyúčtované zálohy). Externí systém takové záloze přidělí své jedinečné ServiceID (které samozřejmě předá při volání metody PerformOperation) a po úspěšném vložení zahájí poskytnutí služby. Předpokládá se, že výše zálohy bude maximální možný limit pro danou službu, tj. že finální cena služby bude shora omezena výší této zálohy.

Po poskytnutí služby zavolá externí systém podruhé metodu PerformOperation s novým ServiceID, zdrojem a popisem určeným pro skutečně poskytnuté služby a ServiceID předané při vložení zálohy předá v parametru UndoServiceID. Webová služba ISKAMu provede v rámci jednoho zápisu do databáze storno zálohové pohledávky a vložení finální pohledávky s tím, že prostředky ze zálohy budou primárně použity na úhradu vložené služby. Poskytovatel služby se tak vyhne riziku, že by služba zůstala neuhrazená.

Ukázka zálohové pohledávky:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthSoapHd xmlns="http://aps-brno.cz/">
      <Login>ws</Login>
      <Password>ws</Password>
      <LocationID>a92e8776-b782-44e9-bba6-afeabaca451f</LocationID>
    </AuthSoapHd>
  </soap:Header>
  <soap:Body>
    <PerformOperation xmlns="http://aps-brno.cz/">
      <CardID>00000000-0000-0000-0000-00000000293d</CardID>
      <PaymentAmount>500</PaymentAmount>
      <ServiceType>ELE</ServiceType>
      <Description>Záloha na dobíjení elektromobilu</Description>
      <Abbrevitation>ELZ</Abbrevitation>
      <VATRate>Basic</VATRate>
      <Source>3503</Source>
      <ServiceID>6FC1BC8A-EADA-4E3C-9E4A-99602A77B400</ServiceID>
      <CheckUnique>true</CheckUnique>
     </PerformOperation>
  </soap:Body>
</soap:Envelope>

Odpovídající vyúčtování:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthSoapHd xmlns="http://aps-brno.cz/">
      <Login>ws</Login>
      <Password>ws</Password>
      <LocationID>a92e8776-b782-44e9-bba6-afeabaca451f</LocationID>
    </AuthSoapHd>
  </soap:Header>
  <soap:Body>
    <PerformOperation xmlns="http://aps-brno.cz/">
      <CardID>00000000-0000-0000-0000-00000000293d</CardID>
      <PaymentAmount>230</PaymentAmount>
      <ServiceType>ELE</ServiceType>
      <Description>Dobíjení elektromobilu</Description>
      <Abbrevitation>ELE</Abbrevitation>
      <VATRate>Basic</VATRate>
      <Source>3504</Source>
      <ServiceID>6FC1BC8A-EADA-4E3C-9E4A-99602A77B401</ServiceID>
      <CheckUnique>true</CheckUnique>
      <UndoServiceID>6FC1BC8A-EADA-4E3C-9E4A-99602A77B400</UndoServiceID>
    </PerformOperation>
  </soap:Body>
</soap:Envelope>

Tato metoda slouží ke stornu pohledávky se zadaným ServiceID. Používá se např. při úspěšné reklamaci služby u poskytovatele. Při částečném uznání reklamace (snížení ceny služby) lze využít i metodu postup analogický k vyúčtování zálohy, čímž se vyhnete riziku, že po stornu původní pohledávky se prostředky použijí na úhradu případného dluhu za jiné služby a na zápis nové pohledávky v nižší výši tak nezbydou na kontě prostředky.

Metoda slouží ke získání rekapitulace poskytnutých služeb. Díky filtru na zdroj lze snadno samostatně sledovat různé druhy služeb (byť vkládaných prostřednictvím stejného loginu) a odlišit tak např. zálohy od finálních vyúčtování. Metoda vrací jen nestornované pohledávky.

Metoda pošle SMS na mobilní telefon majitele karty, pokud je nastavena platební brána a v ISKAMu je vyplněno mobilní číslo u klienta. Upozorňujeme, že na použití této funkce je nutné se explicitně dohodnout s provozovatelem ISKAMu, protože pro provozovatele ISKAMu znamená zaslání SMS náklad.

Metoda pošle e-mail na všechny dostupné e-mailové adresy držitele karty. Jako e-mail odesílatele se použije hodnota vyplněná v parametrech ISKAMu jako e-mail odesílatele hesla.

Pro přístup k WSDL služby použijte ideálně přímo adresu, kterou dostanete od provozovatele ISKAMu. V níže uvedeném ZIP archívu je statická kopie WSDL z května 2021, verze na konkrétní instalaci se může lišit. cardoperationssl.zip

~~DISCUSSION~~