Webhooks

Webhook on tiedonvälitysmenetelmä, jonka avulla verkkokehittäjät voivat luoda omia HTTP-kutsujaan, jotka suoritetaan jonkin määrätyn tapahtuman yhteydessä.

Seuraavat toiminnot ovat tällä hetkellä mahdollisia MyCashflow'n Webhooks-laajennuksen avulla:

  • Tilaustietojen hakeminen
  • Tilausten käsitteleminen
  • Tilauskommenttien lisääminen

Voit käyttää laajennusta integroidaksesi verkkokauppasi tilausten osalta johonkin ulkopuoliseen ohjelmaan. Integrointeja voit toteuttaa myös MyCashflow'n REST API:n avulla.

Toimintaperiaatteet

Webhooksia käytetään lähettämällä jollain ohjelmointikielellä (usein cURL-ohjelman avulla) HTTP-pyyntö verkkokaupan Webhooks-osoitteeseen. MyCashflow'n Webhooks-laajennus palauttaa tuosta osoitteesta XML-muotoisen vastauksen pyyntöön.

GET-tyyppisiä Webhooks-komentoja on mahdollista käyttää myös syöttämällä haluttu Webhooks-osoite selaimen osoiteriville. Näin voit helposti testata Webhooks-pyyntöjä verkkokaupassasi.

Verkkokauppaan tulevista tilauksista lähetetään aina automaattinen POST-pyyntö laajennuksen asetuksissa määriteltyyn osoitteeseen.

Alla on esitelty Webhooks-pyynnön kaikki osat:

  1. Kaikkien Webhooks-pyyntöjen yhteyspiste on https://KAUPANOSOITE.mycashflow.fi/webhooks/
  2. Yhteyspisteen perään lisätään haluttu toiminto (katso lista sallituista toiminnoista): https://KAUPANOSOITE.mycashflow.fi/webhooks/get
  3. Seuraavaksi pyyntöön lisätään toimintoon liittyvät GET- tai POST-parametrit: https://KAUPANOSOITE.mycashflow.fi/webhooks/get?order=n
  4. Viimeiseksi pyyntöön lisätään verkkokaupan yksilöllinen API-avain: https://KAUPANOSOITE.mycashflow.fi/webhooks/get?order=n&key=jyghji765rfghji
    • Kun suoritat Webhooks-pyynnön selaimen osoiterivillä, API-avainta ei tarvitse lisätä osoitteeseen, kunhan olet kirjautunut verkkokaupan hallintatyökaluun.

Alla on esimerkki Webhooks-pyynnöstä, jossa lähetetään asiakkaalle julkinen tilauskommentti:

https://KAUPANOSOITE.mycashflow.fi/webhooks/process
    action=add_comment
    order=23
    message="Kommenttia pukkaa"
    public_message=1
    key=kjhbnko987654e

Asennus ja käyttöönotto

Lue myös laajennuksien yleiset asennus- ja käyttöönotto-ohjeet.

Laajennukset eivät ole käytettävissä MyCashflow Free -palvelupaketissa.

Määritä laajennuksen asetuksissa osoite, johon verkkokaupasta lähetetään Webhook-kutsuja, sekä tunnistautumiseen käytettävä API key.

Kun olet määrittänyt Webhooksin asetukset, testaa laajennuksen toimivuutta lähettämällä jokin pyyntö syöttämääsi osoitteeseen (saatavilla olevat toiminnot esitelty alla). Voit esimerkiksi tehdä testitilauksen, josta lähetetään automaattinen ilmoitus

Webhooks-toiminnot

Alla on listattu kaikki MyCashflow'n Webhooks-laajennuksen toiminnot ja niiden parametrit.

Katso myös esimerkkejä toimintojen soveltamisesta käytännössä.

POST /webhooks/process
 action=deliver

Merkitsee tilauksen toimitetuksi.
order Kokonaisluku Käsiteltävän tilauksen ID-numero
send_email 0 / 1

Arvolla 1 lähetetään toimitusvahvistus, josta lähtee myös sähköposti asiakastietojen ja toimitusosoitteen sähköpostiin. Oletuksena viestiä ei lähetetä (arvo 0).

POST /webhooks/process
 action=add_comment

Lisää tilaukselle kommentin.
order Kokonaisluku Käsiteltävän tilauksen ID-numero
public_message 0 / 1 Määrittää onko kommentti julkinen viesti (arvolla 1), josta lähtee myös sähköposti asiakastietojen ja toimitusosoitteen sähköpostiiin. Oletuksena kommentti ei ole julkinen (arvo 0).
message Teksti Tilauskommentin sisältö tekstimuodossa
GET /webhooks/get
Käytetään yhden tai usean tilauksen hakemiseen ID-numeroiden perusteella.
order Kokonaisluku Haettavan tilauksen ID-numero
order_ids Kokonaislukutaulukko

Käytetään useiden tilauksien hakemiseen ID-numerojen perusteella.

Esim. order_ids[]=1&order_ids[]=4&order_ids[]=56

GET /webhooks/changes

Käytetään tilausten hakemiseen niiden luontiajankohdan ja muutosten perusteella.

Palauttaa aina vain 100 tilausta kerrallaan halutusta ajankohdasta alkaen.

created_after_ts Merkkijono

Unix timestamp -muotoinen aikamääre, jonka jälkeen luodut tilaukset halutaan hakea.

Esim. created_after_ts=1483185600

updated_after_ts Merkkijono Unix timestamp -muotoinen aikamääre, jonka jälkeen päivittyneet tilaukset halutaan hakea.
GET /webhooks/send
Käytetään epäonnistuneen Webhooks-sanoman lähettämiseen uudestaan.
order Kokonaisluku Tilauksen ID-numero

Paluuarvot

Kaikki Webhooksin palauttama tieto on XML-muodossa. Alla näet esimerkin Webhooksin palauttamasta XML-sanomasta.

  Näytä esimerkkitiedosto

Oheinen esimerkki on vastaus GET /webhooks/changes -pyyntöön, jolla haetaan tilauksia verkkokaupasta.

Paluusanomaan kuuluvat tilauksen, tilaajan ja tilattujen tuotteiden tiedot.

<Orders>
  <Order id="58">
    <OrderNumber>58</OrderNumber>
    <OrderedAt timestamp="1345401893">2012-08-19 21:44:53</OrderedAt>
    <OrderStatus>Open</OrderStatus>
    <OrderLanguage>fi</OrderLanguage>
    <Comments>K&amp;auml;sitteletteh&amp;auml;n pikaisesti, koska t&amp;auml;m&amp;auml; on kiireisempi kuin muut tilaukset.</Comments>
    <PaymentMethod PaymentID="7">Checkout</PaymentMethod>
    <PaymentReference>20120819001532</PaymentReference>
    <PaymentStatus>Paid</PaymentStatus>
    <ShippingMethod ShippingID="6">SmartPOST</ShippingMethod>
    <ShippingWeight>0.5</ShippingWeight>
    <ShippingPackages>1</ShippingPackages>
    <Documents>
      <Receipt>http://smo43.mycashflow.fi/orderstatus/58/receipt/52d07914f6bcdf448084320f3de6a816</Receipt>
      <DispatchNote>http://smo43.mycashflow.fi/orderstatus/58/dispatchnote/ba4be2b2ed682be3c646be5ef7f3a77d</DispatchNote>
      <Invoice>http://smo43.mycashflow.fi/orderstatus/58/invoice/f358b6fe49b80c91425137059e0cb49b</Invoice>
    </Documents>

    <CustomerInformation>
      <FirstName>Ismo</FirstName>
      <LastName>Ruotsalainen</LastName>
      <Company>Pulse247 Oy</Company>
      <BusinessID>FI21315706</BusinessID>
      <StreetAddress>Syväojankatu 3A</StreetAddress>
      <ZipCode>87100</ZipCode>
      <City>Kajaani</City>
      <Country>fi</Country>
      <Email allowMarketing="false">ismo@pulse247.info</Email>
      <Phone allowMarketing="false">020 741 9172</Phone>
      <IPAddress>85.29.85.227</IPAddress>
    </CustomerInformation>

    <ShippingAddress>
      <FirstName>Ismo</FirstName>
      <LastName>Ruotsalainen</LastName>
      <Company>Pulse247 Oy</Company>
      <StreetAddress>Syväojankatu 3A</StreetAddress>
      <ZipCode>87100</ZipCode>
      <City>Kajaani</City>
      <Country>fi</Country>
      <Phone>020 741 9172</Phone>
    </ShippingAddress>

    <Products>
      <Product>
        <ProductID>3</ProductID>
        <ProductName>Lacoste kävelykengät</ProductName>
        <Variation id="3">Valkoinen/42</Variation>
        <Code>123123</Code>
        <UnitPrice vat="0">41.28</UnitPrice>
        <Quantity>1</Quantity>
        <Total>41.28</Total>
        <Shipped>false</Shipped>
      </Product>

      <Product>
        <ProductID>1199</ProductID>
        <ProductName>Lahjakortti 100€</ProductName>
        <UnitPrice vat="0">66.12</UnitPrice>
        <Quantity>1</Quantity>
        <Total>66.12</Total>
        <Shipped>false</Shipped>
        
        <Campaign>
          <CampaignID>496</CampaignID>
          <NormalUnitPrice>82.6446</NormalUnitPrice>
        </Campaign>

      </Product>

      <Product>
        <ProductID PaymentID="7">PAYMENT</ProductID>
        <ProductName>Checkout</ProductName>
        <Quantity>1</Quantity>
      </Product>

      <Product>
        <ProductID ShippingID="6">SHIPPING</ProductID>
        <ProductName>SmartPOST</ProductName>
        <UnitPrice vat="0">5</UnitPrice>
        <Quantity>1</Quantity>
        <Total>5</Total>
      </Product>

    </Products>
  </Order>
</Orders>

Lisätietoa Webhooksin XML-tietorakenteesta löydät Lisätietoja-kappaleesta.

Esimerkkejä

Alla on listattu esimerkkejä MyCashflow'n Webhooks-laajennuksella onnistuvista toiminnoista.

Katso myös kaikkien toimintojen tarkat kuvaukset ja käytettävissä olevat parametrit.

  Yksittäisen tilauksen hakeminen

Voit hakea verkkokauppasi Webhooks-rajapinnan kautta yksittäisen tilauksen tiedot:

GET /webhooks/get?order=43&key=gvbnkiytfghu76tg

Kun haet yksittäisen tilauksen Webhooks-rajapinnasta, paluusanoman juurielementti on <Order>, joka sisältää tiedot tilauksesta, tilaajasta ja tuotteista.

  Uusien tilausten hakeminen

Webhooks-laajennuksen avulla voit myös hakea verkkokauppaasi tulleita uusia tilauksia ulkoiseen järjestelmään.

GET /webhooks/changes?ts=n&key=jhbnji8765rfg

Normaali implementointi omaan sovellukseen menee niin, että sovellus kysyy rajapinnasta tapahtumia tietyn kellon ajan jälkeen ja käsittelee aineiston tilaukset. Lopuksi sovellus tallentaa viimeisimmän tilauksen timestamp-arvon talteen ja käyttää sitä seuraavassa kyselyssä.

<Orders time_from="1336738000" time_to="1345401893" orders="58">
	<Order id="1">
		<OrderNumber>1</OrderNumber>
		<OrderedAt timestamp="1336738023">2012-05-11 15:07:03</OrderedAt>
		...
	</Order>
	...
	<Order id="58">
		<OrderNumber>58</OrderNumber>
		<OrderedAt timestamp="1345401893">2012-08-19 21:44:53</OrderedAt>
		...
	</Order>
</Orders>

GET /webhooks/changes -pyynnön paluusanoma on muuten vastaava kuin yksittäistä tilausta kysyttäessä, paitsi koko XML-tiedoston juurielementti on <Orders>, jonka alla on jokaista palautunutta tilausta kohti oma <Order>-elementti.

<Orders>-elementin attribuuteissa on kerrottu miltä aikaväliltä tilauksia palautetaan ja kuinka monta tilausta aineistossa on kokonaisuutena. Myös yksittäisen tilauksen <OrderedAt>-elementille on lisätty attribuutti timestamp, joka kertoo suoraan tilauksen aikaleiman.

GET /webhooks/changes -rajapinnan tilaukset kannattaa käsitellä järjestyksessä ja tallentaa aina onnistuneen tilauksen jälkeen tilauksen oma timestamp-arvo talteen mieluummin kuin <Orders>-elementin time_to-arvo. Tällöin seuraava haku aloitetaan aina ensimmäisestä käsittelemättä jääneestä tilauksesta eikä välistä jää tilauksia noutamatta, jos käsittely on aiemmin epäonnistunut.

  Valittujen tilauksien hakeminen

Voit hakea kerralla useita tilauksia käyttämällä seuraavaa Webhooks-pyyntöä:

GET /webhooks/get?order_ids[]=23&order_ids[]=43&order_ids[]=3&key=jhbnji8765rfg

Kun haet useita tilauksia, paluusanoman juurielementti on <Orders>, joka sisältää oman <Order>-elementin jokaiselle palautuneelle tilaukselle, samalla tavoin kuin GET /webhooks/changes -pyynnöllä.

  Tilauksen ja kaikkien avointen tuotteiden merkitseminen toimitetuksi

Voit merkitä Webhooks-pyynnöllä tilauksen toimitetuksi. Käytä tällöin seuraavia parametreja:

POST /webhooks/process
    action=deliver
    order=45
    send_email=1
    key=gvbnkiytfghu76tg

Esimerkissä lähetetään asiakkaalle toimitusvahvistus asettamalla parametri send_email=1.

  Tilauskommentin lisääminen

Voit lisätä tilaukselle tilauskommentin, josta voit tarvittaessa lähettää asiakkaalle sähköposti-ilmoituksen. Käytä tällöin seuraavaa pyyntöä:

POST /webhooks/process
    action=add_comment
    message="Viestin sisältö"
    public_message=1
    key=jhbnji8765rfg

Esimerkissä asetettu kommentti lähetetään julkisesti asiakkaalle asettamalla attribuutti public_message=1.

  Webhooks-sanoman lähettäminen uudelleen

GET /webhooks/send -pyynnöllä voit lähettää uudelleen epäonnistuneen sanoman. Toiminnolle annetaan order-parametrinä lähetettävän tilauksen tilausnumero.

GET /webhooks/send?order=34&key=jhbnji8765rfg


Lisätietoja