Maksulinkit eli tilaukset ovat Paylinkin ydin. Rajapinnan kautta on saatavilla seuraavat toiminnot tilauksille:
Endpoint | Toiminto |
---|---|
GET api/v1/orders | Listaa tilaukset |
POST api/v1/orders | Lisää uusi tilaus |
GET api/v1/orders/{orderId} | Hae tilauksen tiedot |
POST api/v1/orders/{orderId}/deliver | Lä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",
"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.
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",
"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",
"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",
"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",
"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",
"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'