Paylink API – Tilaukset

Maksulinkit eli tilaukset ovat Paylinkin ydin. Rajapinnan kautta on saatavilla seuraavat toiminnot tilauksille:

EndpointToiminto
GET api/v1/ordersListaa tilaukset
POST api/v1/ordersLisää uusi tilaus
GET api/v1/orders/{orderId}Hae tilauksen tiedot
POST api/v1/orders/{orderId}/deliverLähetä maksupyyntö
PUT api/v1/orders/{orderId}Muokkaa tilausta
DELETE api/v1/orders/{orderId}Poista tilaus

Listaa tilaukset

Listaa kaikki tilaukset. Tilaukset on järjestetty luomisjärjestyksessä niin, että uusimmat tilaukset ovat ensimmäisenä.

Parametrit

page Vapaaehtoinen
Sivu miltä tilaukset haetaan. Rajapinta palauttaa 50 tilausta yhdellä sivulla.
GET api/v1/orders
cURL
curl -i -X GET -H "Authorization:Token API-AVAIN" 'https://test.app.paylink.fi/api/v1/orders?page=1'
Vastaus
{
  "has_more":false,
  "data":[
    {
      "id":5735,
      "display_id":"1030",
      "order_number_prefix":"PL",
      "due_date":"2020-08-25",
      "customer_locale":"fi_FI",
      "status":"pending",
      "notes":"Muistiinpanoja",
      "info_before": "Teksti ennen laskurivejä",
      "info_after": "Teksti laskurivien jälkeen",
      "customer_id":null,
      "email":"matti.meikalainen@example.com",
      "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
      "created_at":"2020-08-14T15:06:14.000+03:00",
      "updated_at":"2020-08-14T15:06:14.000+03:00",
      "address":{
        "firstname":"Matti",
        "lastname":"Meikäläinen",
        "company":null,
        "company_id":null,
        "address":"Testikatu 1",
        "city":"Helsinki",
        "postcode":"00100",
        "phone":"0401234567",
        "country":"FI"
      },
      "items":[
        {
          "title":"Testituote",
          "unit_base_price_cents":81,
          "unit_tax_cents":19,
          "unit_total_price_cents":100,
          "tax_rate_id":"fi_standard",
          "total_base_price_cents":81,
          "total_tax_cents":19,
          "total_price_cents":100,
          "quantity":1,
          "product_id":null
        }
      ]
    }
    ...
  ]
}

Lisää tilaus

Luo uusi tilaus.

Parametrit

email Pakollinen
Asiakkaan sähköpostiosoite
customer_locale Vapaaehtoinen
Asiakkaan kieli, fi_FI tai en_US. Oletus fi_FI
notes Vapaaehtoinen
Sisäisiä muistiinpanoja tilauksesta. Ei näytetä asiakkaalle.
info_before Vapaaehtoinen
Teksti ennen laskurivejä
info_after Vapaaehtoinen
Teksti laskurivien jälkeen
due_date Vapaaehtoinen
Tilauksen eräpäivä, syötä muodossa YYYY-MM-DD (esim. 2020-08-15).
reference Vapaaehtoinen
Tilitysviite mikäli käytössä on Paytrailin yksittäistilitykset. Huom! Oltava uniikki ja validi pankkiviitenumero. Luodaan automaattisesti jos jätetään tyhjäksi.
display_id Vapaaehtoinen
Loppuasiakkaalle näytettävä tilausnumero. Oltava uniikki. Luodaan automaattisesti jos jätetään tyhjäksi.
order_number_prefix Vapaaehtoinen
Tilausnumeroiden etuliite, jolla voi erotella tilaukset esimerkiksi verkkokaupan tilauksista. Tilausnumerot muodostuvat etuliitteestä ja varsinaisesta tilausnumerosta. Esimerkiksi jos etuliite on "P-" ja tilausnumero 123, lopullinen tilausnumero on "P-123". Etuliitteessä voi olla kirjaimia, numeroita ja väliviivoja. Oletuksena käytetään asetuksista löytyvää etuliitettä.
customer_id Vapaaehtoinen
Asiakastilin ID, jos tilaukseen halutaan kytkeä asiakasrekisterin asiakas.
address Pakollinen
Asiakkaan yhteystiedot. Mikäli jotain pakollista kenttää ei ole tiedossa, voi sen tilalla käyttää väliviivaa (-).
Lapsiparametrit
address.firstname Pakollinen
Asiakkaan etunimi
address.lastname Pakollinen
Asiakkaan sukunimi
address.company Vapaaehtoinen
Asiakkaan yrityksen nimi
address.company_id Vapaaehtoinen
Asiakkaan yrityksen y-tunnus
address.city Pakollinen
Asiakkaan postitoimipaikka
address.postcode Pakollinen
Asiakkaan postinumero
address.phone Vapaaehtoinen
Asiakkaan puhelinnumero
address.country Pakollinen
Asiakkaan maa kaksikirjaimisena maakoodina (esim. FI)
items Pakollinen
Tilausrivit. Summan on oltava vähintään 0,65 €.
Lapsiparametrit
items.title Pakollinen
Tilausrivin nimi
items.unit_total_price_cents Pakollinen
Verollinen yksikköhinta sentteinä
items.quantity Pakollinen
Lukumäärä
items.tax_rate_id Pakollinen
Veroprosentin tunniste, joko fi_standard (24 %), fi_intermediate (14 %), fi_reduced (10 %) tai fi_zero (0 %)
items.product_id Vapaaehtoinen
Tuotteen ID, jos tilausrivi halutaan kytkeä tuoterekisterin tuotteeseen.
POST api/v1/orders
cURL
curl -i -X POST \
   -H "Authorization:Token API-AVAIN" \
   -H "Content-Type:application/json" \
   -d \
'{
  "email": "matti.meikalainen@example.com",
  "customer_locale": "fi_FI",
  "notes": "Muistiinpanoja",
  "info_before": "Teksti ennen laskurivejä",
  "info_after": "Teksti laskurivien jälkeen",
  "due_date": "2020-08-25",
  "reference": "10003",
  "display_id": 1000,
  "order_number_prefix": "PL",
  "customer_id": null,
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "address": "Testikatu 1",
    "postcode": "00100",
    "city": "Helsinki",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Testituote",
      "unit_total_price_cents": 100,
      "quantity":1,
      "tax_rate_id":"fi_standard",
      "product_id": null
    }
  ]
}' \
 'https://test.app.paylink.fi/api/v1/orders'
Vastaus
{
  "id": 5737,
  "display_id": "1000",
  "order_number_prefix": "PL",
  "due_date": "2020-08-25",
  "customer_locale": "fi_FI",
  "status": "pending",
  "notes": "Muistiinpanoja",
  "info_before": "Teksti ennen laskurivejä",
  "info_after": "Teksti laskurivien jälkeen",
  "customer_id": null,
  "email": "matti.meikalainen@example.com",
  "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
  "created_at": "2020-08-17T12:06:41.000+03:00",
  "updated_at": "2020-08-17T12:06:41.000+03:00",
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "company": null,
    "company_id": null,
    "address": "Testikatu 1",
    "city": "Helsinki",
    "postcode": "00100",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Testituote",
      "unit_base_price_cents": 81,
      "unit_tax_cents": 19,
      "unit_total_price_cents": 100,
      "tax_rate_id": "fi_standard",
      "total_base_price_cents": 81,
      "total_tax_cents": 19,
      "total_price_cents": 100,
      "quantity": 1,
      "product_id": null
    }
  ]
}

Hae tilaus

Hakee yhden tilauksen tiedot tilaus-ID:n perusteella.

Parametrit

orderId Pakollinen
Tilauksen ID
GET api/v1/orders/{orderId}
cURL
curl -i -X GET \
   -H "Authorization:Token API-AVAIN" \
 'https://test.app.paylink.fi/api/v1/orders/1'
Vastaus
{
  "id": 1,
  "display_id": "1000",
  "order_number_prefix": "PL",
  "due_date": "2020-08-25",
  "customer_locale": "fi_FI",
  "status": "pending",
  "notes": "Muistiinpanoja",
  "info_before": "Teksti ennen laskurivejä",
  "info_after": "Teksti laskurivien jälkeen",
  "customer_id": null,
  "email": "matti.meikalainen@example.com",
  "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
  "created_at": "2020-08-17T12:06:41.000+03:00",
  "updated_at": "2020-08-17T12:06:41.000+03:00",
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "company": null,
    "company_id": null,
    "address": "Testikatu 1",
    "city": "Helsinki",
    "postcode": "00100",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Testituote",
      "unit_base_price_cents": 81,
      "unit_tax_cents": 19,
      "unit_total_price_cents": 100,
      "tax_rate_id": "fi_standard",
      "total_base_price_cents": 81,
      "total_tax_cents": 19,
      "total_price_cents": 100,
      "quantity": 1,
      "product_id": null
    }
  ]
}

Lähetä maksupyyntö

Lähettää maksupyynnön tilauksesta sähköpostilla asiakkaalle.

Parametrit

orderId Pakollinen
Tilauksen ID
POST api/v1/orders/{orderId}/deliver
cURL
curl -i -X POST \
   -H "Authorization:Token API-AVAIN" \
   -H "Content-Type:application/json" \
   -d \
'' \
 'https://test.app.paylink.fi/api/v1/orders/1/deliver'
Vastaus
{
  "id": 1,
  "display_id": "1000",
  "order_number_prefix": "PL",
  "due_date": "2020-08-25",
  "customer_locale": "fi_FI",
  "status": "pending",
  "notes": "Muistiinpanoja",
  "info_before": "Teksti ennen laskurivejä",
  "info_after": "Teksti laskurivien jälkeen",
  "customer_id": null,
  "email": "matti.meikalainen@example.com",
  "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
  "created_at": "2020-08-17T12:06:41.000+03:00",
  "updated_at": "2020-08-17T12:06:41.000+03:00",
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "company": null,
    "company_id": null,
    "address": "Testikatu 1",
    "city": "Helsinki",
    "postcode": "00100",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Testituote",
      "unit_base_price_cents": 81,
      "unit_tax_cents": 19,
      "unit_total_price_cents": 100,
      "tax_rate_id": "fi_standard",
      "total_base_price_cents": 81,
      "total_tax_cents": 19,
      "total_price_cents": 100,
      "quantity": 1,
      "product_id": null
    }
  ]
}

Muokkaa tilausta

Muokkaa tilauksen tietoja.

Huom! Maksetulle tilaukselle voi muokata ainoastaan muistiinpanoja (notes).

Parametrit

orderId Pakollinen
Tilauksen ID
Kts. muut parametrit kohdasta Lisää tilaus »
PUT api/v1/orders/{orderId}
cURL
curl -i -X PUT \
   -H "Authorization:Token API-avain" \
   -H "Content-Type:application/json" \
   -d \
'{
  "notes": "Uudet muistiinpanot"
}' \
 'https://test.app.paylink.fi/api/v1/orders/1'
Vastaus
{
  "id": 1,
  "display_id": "1000",
  "order_number_prefix": "PL",
  "due_date": "2020-08-25",
  "customer_locale": "fi_FI",
  "status": "pending",
  "notes": "Muistiinpanoja",
  "info_before": "Teksti ennen laskurivejä",
  "info_after": "Teksti laskurivien jälkeen",
  "customer_id": null,
  "email": "matti.meikalainen@example.com",
  "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
  "created_at": "2020-08-17T12:06:41.000+03:00",
  "updated_at": "2020-08-17T12:06:41.000+03:00",
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "company": null,
    "company_id": null,
    "address": "Testikatu 1",
    "city": "Helsinki",
    "postcode": "00100",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Testituote",
      "unit_base_price_cents": 81,
      "unit_tax_cents": 19,
      "unit_total_price_cents": 100,
      "tax_rate_id": "fi_standard",
      "total_base_price_cents": 81,
      "total_tax_cents": 19,
      "total_price_cents": 100,
      "quantity": 1,
      "product_id": null
    }
  ]
}

Poista tilaus

Poistaa tilauksen.

Huom! Maksettua tilausta ei voi poistaa.

Parametrit

orderId Pakollinen
Tilauksen ID
DELETE api/v1/orders/{orderId}
cURL
curl -i -X DELETE \
   -H "Authorization:Token API-AVAIN" \
 'https://test.app.paylink.fi/api/v1/orders/1'