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.png

3. 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

MetodiPolkuMitä se tekee
POST/v1/cardsLuo 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/frontKortti tai kirje sellaisena kuin se painetaan; myös /back (kortit sekä kirjeet, joissa on backSide)
POST/v1/recipientsLisää 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}/approveHyvä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
nameKortin nimi omaan käyttöösi
productcard 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
templateKortit: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Kirjeet: letter-formal, letter-classic, letter-band, letter-plain
countryCA, US, NL, DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS; oletuksena NL. Vastaanottajien on asuttava tässä maassa
languageen, nl, fr, de, es, sv, no, da, fi, is; oletuksena maan oma kieli
backSideKirjeet 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
websiteVärit ja logo luetaan sivustolta, jos et lähetä niitä
destinationUrlMinne QR-koodi vie; oletuksena verkkosivusto
brandcompanyName, primaryColor, secondaryColor, logoUrl, font
textKortit: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Kirjeet: headline, body, ctaLine (QR-koodin vieressä), signOff, backHeadline, backBody
contactwebsite, 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
Osoitestreet, houseNumber, addition tai addressLine1, addressLine2; lisäksi postcode, city, region, country
Muutreference (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

RajaAvainta kohden
Kaikki kutsut120 minuutissa
Korttien luominen tai muuttaminen sekä kutsut, joissa on kuvia300 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.