Yotru API
Luo postikortteja ja kirjeitä, lisää vastaanottajia ja hyväksy kampanjoita omasta ohjelmistostasi. Jokainen vastaanottaja lisätään kyseisen kortin tai kirjeen avoimeen kampanjaan, eikä mitään postiteta ennen kuin kampanja on hyväksytty ja maksettu. Postia lähtee 16 maahan: postikortteja maihin CA, US, NL, DE, GB ja kirjeitä kaikkiin niistä.
Tunnistautuminen
Ensimmäinen avaimesi luodaan, kun avaat sivun Asetukset → Integraatiot → API-avaimet. Sähköpostiosoitteesi on oltava vahvistettu, ja sinun on oltava tilin omistaja tai ylläpitäjä. Avain näytetään vain kerran, joten tallenna se heti. Jos kadotat sen, luo uusi avain ja mitätöi vanha.
Authorization: Bearer yk_live_...Perus-URL on https://api.yotru.com. Testitilaa ei ole: kaikki avaimet ovat tuotantoavaimia, mutta voit vapaasti luoda kortteja ja lisätä vastaanottajia. Vain hyväksyminen maksaa.
Pika-aloitus
1. Luo kortti. Se, minkä jätät pois, tulee pohjasta tai luetaan kentän website sivustolta.
curl -X POST https://api.yotru.com/v1/cards \
-H "Authorization: Bearer $YOTRU_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Autumn offer","country":"NL","website":"https://example.com","text":{"headline":"Hello neighbour"}}'Kirje toimii samalla tavalla. Tämä kirje lähtee Saksaan saksankielisenä, ja sen kääntöpuolelle painetaan toinen sivu:
curl -X POST https://api.yotru.com/v1/cards \
-H "Authorization: Bearer $YOTRU_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Herbstangebot","product":"letter","country":"DE","website":"https://example.com","backSide":true,"text":{"headline":"Guten Tag","body":"Guten Tag {firstName} {lastName},\n\n..."}}'2. Katso tulos. Kuva on juuri se, mikä painetaan.
curl https://api.yotru.com/v1/cards/CARD_ID/preview/front \
-H "Authorization: Bearer $YOTRU_KEY" -o front.png3. Lisää vastaanottajat. Ensimmäinen kutsu avaa kampanjan, ja sen tunnus on kentässä batch.campaignId.
curl -X POST https://api.yotru.com/v1/recipients \
-H "Authorization: Bearer $YOTRU_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: import-2026-11-08" \
-d '{"cardId":"CARD_ID","recipients":[{"reference":"crm-42","name":"Anna de Vries","street":"Kerkstraat","houseNumber":"12","postcode":"1011 AB","city":"Amsterdam","country":"NL"}]}'4. Hyväksy. Vastauksessa on payUrl, ja kampanja menee painoon, kun se on maksettu. Voit myös hyväksyä ja maksaa kampanjan sivulla hallintapaneelissasi. Seuraavaksi lisäämäsi vastaanottajat avaavat uuden kampanjan.
curl -X POST https://api.yotru.com/v1/campaigns/CAMPAIGN_ID/approve \
-H "Authorization: Bearer $YOTRU_KEY"Päätepisteet
| Metodi | Polku | Mitä se tekee |
|---|---|---|
| POST | /v1/cards | Luo kortti (JSON tai multipart kentillä data ja photo) |
| PATCH | /v1/cards/{id} | Muuta korttia. Vain lähettämäsi kentät muuttuvat. Hyväksytyt kampanjat säilyttävät korttinsa |
| GET | /v1/cards/{id} | Hae kortti |
| GET | /v1/cards/{id}/preview/front | Kortti tai kirje sellaisena kuin se painetaan; myös /back (kortit sekä kirjeet, joissa on backSide) |
| POST | /v1/recipients | Lisää enintään 1 000 vastaanottajaa kutsua kohden |
| GET | /v1/batch?cardId= | Kampanja, joka täyttyy kortille parhaillaan |
| GET | /v1/campaigns/{id} | Kampanjan tila |
| POST | /v1/campaigns/{id}/approve | Hyväksy: palauttaa maksulinkin |
Kortit
Kaikki kentät ovat valinnaisia. Vastauksessa on id, printable, issues ja problems. Myös hallintapaneelissa tehty kortti käy: kopioi sen tunnus kohdasta Kirjeet. Kortin tunnuksella lähetetyt vastaanottajat menevät kyseisen kortin omaan kampanjaan. Kirje luodaan samalla kutsulla, ja sillä on tunnus samoin kuin kortilla.
| Kenttä | Arvot |
|---|---|
name | Kortin nimi omaan käyttöösi |
product | card tai letter; oletuksena card. Kortit lähtevät maihin CA, US, NL, DE, GB, kirjeet kaikkiin maihin. Korttia ei voi myöhemmin muuttaa kirjeeksi eikä kirjettä kortiksi |
template | Kortit: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Kirjeet: letter-formal, letter-classic, letter-band, letter-plain |
country | CA, US, NL, DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS; oletuksena NL. Vastaanottajien on asuttava tässä maassa |
language | en, nl, fr, de, es, sv, no, da, fi, is; oletuksena maan oma kieli |
backSide | Kirjeet maihin DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS: true painaa kääntöpuolelle toisen sivun lisähintaan kirjettä kohden |
website | Värit ja logo luetaan sivustolta, jos et lähetä niitä |
destinationUrl | Minne QR-koodi vie; oletuksena verkkosivusto |
brand | companyName, primaryColor, secondaryColor, logoUrl, font |
text | Kortit: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Kirjeet: headline, body, ctaLine (QR-koodin vieressä), signOff, backHeadline, backBody |
contact | website, email, phone |
Kirjeen body painetaan juuri sellaisena kuin lähetät sen, joten aloita se haluamallasi tervehdyksellä, esimerkiksi Hei {firstName},. Muuttujat {firstName}, {lastName} ja {companyName} täytetään vastaanottajakohtaisesti. Vastauksessa on myös product ja language. Yksisivuisen kirjeen previewBack on null.
Kortti maahan, johon lähetetään vain kirjeitä, tuntematon kieli tai maa sekä backSide muissa kuin näissä maissa hylätään koodilla 400, ja virheilmoitus kertoo, mikä kenttä on väärin. Hinta määräytyy sen maan mukaan, jossa kortti tai kirje postitetaan, katso hinnat.
Vastaanottajat
Vastaanottajalla on oltava henkilö tai yritys sekä täydellinen osoite.
| Kenttä | Arvot |
|---|---|
| Henkilö | name tai firstName ja lastName; lisäksi company, jobTitle |
| Osoite | street, houseNumber, addition tai addressLine1, addressLine2; lisäksi postcode, city, region, country |
| Muut | reference (palautetaan sinulle), email, phone, website, destinationUrl, customFields, photo |
Jokainen vastaanottaja palautetaan joko tilassa accepted tunnuksen id kanssa tai tilassa refused syyn kanssa. Syy on name, address, country, duplicate tai photo. Jos vastaanottaja asuu muussa maassa kuin kortin country, hänet hylätään syyllä country. Luo silloin kortti tai kirje hänen maahansa. Lähetä Idempotency-Key-otsake, niin toistettu kutsu on turvallinen.
Kuvat
Lähetä kuvat tiedostoina muodossa multipart/form-data ja laita JSON kenttään data. Yhdessä kutsussa voi olla enintään 25 tiedostoa, kukin enintään 10 MB ja yhteensä enintään 32 MB. Kortilla kentän nimi on photo. Vastaanottaja, jolla on "photo": "anna.jpg", saa kyseisen tiedoston. Muuten hän saa kortin kuvan. Logo voi olla linkki, kuva ei.
Kampanjat ja maksu
Kampanjan tila on open, awaiting_payment, approved, printing tai sent. Vähimmäismäärää ei ole: maksat kampanjan korteista, ja alle 100 kortin kampanjassa jokainen kortti maksaa saman kuin 100 kortin erässä. Hyväksynnän yhteydessä tilin omistaja saa myös sähköpostiin maksulinkin ja maksun jälkeen laskun.
Rajat ja virheet
| Raja | Avainta kohden |
|---|---|
| Kaikki kutsut | 120 minuutissa |
| Korttien luominen tai muuttaminen sekä kutsut, joissa on kuvia | 300 päivässä |
Virheet palautetaan JSONina, jossa on message: 400, kun lähettämässäsi pyynnössä on vikaa, 401, kun avain puuttuu tai on väärä, 404, kun kohdetta ei ole tililläsi, 409, kun tila ei salli toimintoa, ja 429, kun olet ylittänyt rajan.