Kassaintegraatio¶
Kassaintegraation avulla sekä myöhästymismaksut että muut Kohassa näkyvät maksut siirretään Kohan virkailijanäkymästä suoraan kassajärjestelmän kautta kassaan.
1.1. Kassaliittymän käyttäminen virkailijatyökalussa¶
Seuraavasta linkistä löydät artikkelin kuvineen kassaliittymän käyttämiseen.1.2. Sanasto¶
kassaliittymä = Kohan ja kassan välinen yhteys. Koha on yhteydessä kassaan kassajärjestelmän kautta. maksutapahtuma = accountlines.accounttype sarakkeessa tyyppiä "Pay", payments_transactions taulun rivi maksu/lasku = mikä tahansa Koha-lasku, joka on maksettava. Esimerkiksi myöhästymisestä aiheutunut lasku. maksutyyppi = Kohan tunnistama koodi, jolla eritellään esimerkiksi myöhästymismaksut ja uuden kortin luomisesta aiheutunut maksu. tuotekoodi = Kassan tunnistama koodi, jolla eritellään esimerkiksi myöhästymismaksut ja kopiomaksut. toimipiste = Paikka, jossa kassa (tai useita kassoja sijaitsee).
1.3. Kassaliittymän alustaminen¶
1.3.1 Asentaminen¶
- LWP::Curl tai Net::Curl::Easy moduulien asennuksessa voi olla ongelmia. Tarvitset libcurl4-openssl-dev paketin asentaaksesi nuo moduulit.
sudo apt-get install libcurl4-openssl-dev
- Koodi on KohaSuomessa. Varmista, että atomicupdatet ovat ajan tasalla ajamalla installer/data/mysql/atomicupdate.pl --pending
- Asenna tarvittavat sertifikaatit, mikäli avaintiedosto on suojattu salasanalla, pura avaimen salasanasuojaus kohdan 1.3.3 ohjeen mukaisesti
- Määrittele sertifikaatit ja muut parametrit kohdassa 1.3.3.
- Aseta Kohan järjestelmäasetukset kohdassa 1.3.2.
1.3.2 Kassaliittymän aktivoiminen / poiskytykeminen¶
Kassaliittymä tarvitsee toimiakseen toteutetun interfacen. Interfacen voi toteuttaa olioon Koha::Payment::POS::<interfacesi_nimi>. KohaSuomessa on toteutettuna valmiiksi interface CPU:lle, josta voi ottaa esimerkkiä.
Kassaliittymä aktivoidaan järjestelmäasetuksista, asetuksessa POSIntegration .
Jokaiselle kirjastolle, jossa kassaliittymää aiotaan käyttää, tulee määritellä Kohan maksutyypit kassajärjestelmän tunnistamiksi tuotekoodeiksi. Kassaliittymän aktivointi onnistuu seuraavasti (esimerkkinä CPU-interface JOE_JOE branchissa):
JOE_JOE: POSInterface: CPU HE: 5110 N: 5130 Kauko: 5140 Korva: 5150 L: 5150 Kopio: 5400 Default: 5100
Eli yleisesti
BRANCH: POSInteface: interfacen_nimi F: 1234 FU: 12345
F & FU ovat accountlines-taulun accounttype sarakkeen Koha-maksutyyppejä.
1.3.3 Yhteyden määritykset¶
Kassaliittymän yhteydet kannattaa määrittää koha-konfiguraatiossa (koha-dev/etc/koha-conf.xml). Esimerkiksi CPU-interfacen konfiguraatio on seuraavanlainen:
<pos>
<CPU>
<!-- Delivered by CPU: -->
<source></source> <!-- Source id -->
<secretKey></secretKey> <!-- Secret key for generating SHA-256 hash -->
<url></url> <!-- Address to the cash register server -->
<mode></mode> <!-- Use 2 for synchronized mode -->
<!-- Koha settings -->
<notificationAddress></notificationAddress> <!-- https://server/api/v1/payments/pos/cpu/{invoicenumber}/report -->
<!-- Replace "server" with your server address, but keep {invoicenumber} as it is (it will be converted later into real id) -->
<!-- SSL certificates -->
<ssl_cert></ssl_cert> <!-- SSL certificate path -->
<ssl_key></ssl_key> <!-- SSL key path -->
<ssl_ca_file></ssl_ca_file> <!-- CA certificate path -->
</CPU>
</pos>
NotificationAddress on CPU-interfacen vaatima osoite, johon kassajärjestelmä lähettää maksukuittauksen (Kohan REST API endpoint /api/v1/pos/cpu/{invoicenumber}/report). Kannattaa myös estää yhteys muilta paitsi kassapalvelimelta tähän REST API-endpointtiin.
Huomioi, että ssl-avain ei saa olla salasanasuojattu. Perlin LWP::UserAgent ei osaa toimia salasanalla suojattujen avainten kanssa. Salasanasuojatun avaimen salauksen voi tarvittaessa purkaa komennolla:
openssl rsa -in alkuperäinen_avain.key -out salaamaton_avain.key
1.4. Kassaliittymän toiminta (tekninen kuvaus)¶
Tämä on tekninen kuvaus kassaliittymän toiminnasta. Kassaliittymän virkailijapuolen toiminnan näkee kappaleessa 1.
1.4.1 Koha-maksusta kassamaksuksi¶
Maksun alustus¶
Kun virkailija siirtyy maksamaan laskuja, hän käyttää members/paycollect.pl sivua. Kun maksu on hyväksytty kassaan lähetettäväksi, kassaliittymä alustaa uuden maksutapahtuman payments_transactions-tauluun. Koska yhdellä maksutapahtumalla voidaan maksaa saman asiakkaan useampia laskuja (esim. 5 myöhästymismaksua kerrallaan), kassaliittymän tulee tietää, mitä laskuja kyseisellä maksutapahtumalla aiotaan maksaa. Tämä tieto tallentuu payments_transactions_accountlines tauluun. Maksu alustetaan ensin unsent tilaan, jolloin generoidaan edellä mainitut tarvittavat tiedot maksutapahtumasta tietokantaan.
Maksun lähettäminen¶
Maksun määrä määritellään normaalisti ennen kuin se lähetetään kassaan (tämän jälkeen lähetetty maksu on maksettava kokonaan). Kun virkailija on hyväksynyt maksun lähetettäväksi kassaan, käytetään edelleen members/paycollect.pl sivua. Aiemmin alustettu maksu on nyt muunnettu JSON muotoon. Tämä JSON-viesti lähetetään AJAXilla samaan members/paycollect-ajax.pl sivuun, joka aloittaa long-polling kutsun kassajärjestelmään. Koha::Payment::POS::<interface> lähettää maksun kassajärjestelmään. Maksutapahtuma merkitään pending-tilaan.
Muista, että maksu voidaan lähdettää vain kerran samalla maksutunnisteella. Jos testaat kahdesta eri tietokannasta kassaliittymää, saattaa käydä niin, että lähetät vahingossa samoja maksutunnisteita (maksutunniste = payments_transaction.transaction_id).
Maksun jälkeen¶
Long-poll kutsun vastaus¶
Kun maksu on suoritettu kassalla, long-poll kutsu vastaanottaa vastauksen. Tällöin ohjelma jatkaa suorittamalla Koha::Payment::POS::<interface>->complete_payment subroutinen.
REST API kuittaus¶
Kassajärjestelmä lähettää kuittauksen REST-rajapintaamme. Kontrolleri löytyy tiedostosta Koha/REST/V1/Payments/Pos/<interface>/Reports.pm.
Maksu on nyt merkattu joko paid- tai cancelled-tilaan.
4.2 Maksutapahtuman tilat¶
- unsent - Maksu on alustettu, mutta sitä ei ole vielä lähetetty kassaan.
- pending - Maksu on alustettu ja lähetetty kassaan, mutta vastausta ei ole vielä saatu kassajärjestelmästä.
- processing - Maksu on suoritettu kassalla, ja sitä suoritetaan parhaillaan Kohassa.
- paid - Maksu on maksettu kassalla ja merkitty maksetuksi Kohassa.
- cancelled - Maksu on peruttu kassalla (tai yhteydessä on tapahtunut virhe) ja merkitty perutuksi Kohassa (kts. payments_transactions.description mahdollista virheilmoitusta varten).
Miten ohitan kassaliittymän käytön väliaikaisesti?
Virkailija voi vaihtaa kirjastoaan. Vaihda sellaiseen kirjastoon, jossa kassaliittymä ei ole käytössä. Kassaliittymää käyttävät kirjastothan määritellään cpuitemnumbers-järjestelmäasetuksessa. Voit myös kytkeä POSIntegration-järjestelmäasetuksen jokaisen branchin POSInterface-parametrin arvolle "disabled". Tällöin kassajärjestelmä ei ole missään kirjastossa käytössä.
Kassaliittymämaksuihin liittyvät lokit kannattaa tehdä Koha::Loggerilla, esimerkiksi CPU käyttää lokitiedostoa cpu_pos.log, joka tallennetaan Kohan lokikansioon.
Verkkomaksut¶
Huom! Tätä ohjetta tarvitaan vain siinä tapauksessa, että CPU:n verkkomaksupalvelu on suoraan kytköksissä Kohaan/Kohan verkkokirjastoon. Jos käytössä on Finna, niin silloin verkkomaksupalvelu juttelee Finnan kanssa ja määritykset tehdään Finnan ylläpidossa. Ohjeistukset löytyvät Finna-wikistä.
Verkkomaksut noudattavat melko samanlaista kaavaa kuin kassaliittymäkin.
Verkkomaksu tarvitsee toimiakseen toteutetun interfacen. KohaSuomessa on toteutettuna valmiiksi CPU-interface. Interface voidaan toteuttaa olioon Koha::Payment::Online::<interfacesi_nimi>. Olion parent, Koha::Payment::Online kertoo mitä alirutiineja vaaditaan toteutetuksi. Järjestelmäasetus verkkomaksulle löytyy OnlinePayments. Järjestelmäasetuksen kuvauksessa on kerrottu sen käyttö. Verkkomaksamisen yhteydenmääritykseen kannattaa käyttää $KOHA_CONF tiedostoa. Verkkomaksuihin liittyvät lokit kannattaa tehdä Koha::Loggerilla, esimerkiksi CPU käyttää lokitiedostoa cpu_online_payments.log, joka tallennetaan Kohan lokikansioon.