Yotru API

Búðu til póstkort og bréf, bættu við viðtakendum og samþykktu herferðir úr þínum eigin hugbúnaði. Hver viðtakandi fer í opna herferð fyrir það póstkort eða bréf og ekkert er sent fyrr en herferðin hefur verið samþykkt og greidd. Pósturinn fer til 16 landa: póstkort til CA, US, NL, DE, GB og bréf til þeirra allra.

Auðkenning

Fyrsti lykillinn þinn verður til þegar þú opnar Stillingar → Tengingar → API-lyklar. Netfangið þitt þarf að vera staðfest og þú þarft að vera eigandi eða stjórnandi aðgangsins. Lykill birtist aðeins einu sinni, svo geymdu hann strax. Ef þú týnir honum skaltu búa til nýjan og afturkalla þann gamla.

Authorization: Bearer yk_live_...

Grunnslóðin er https://api.yotru.com. Enginn prófunarhamur er til: allir lyklar virka í raunumhverfinu, en það kostar ekkert að búa til póstkort og bréf og bæta við viðtakendum. Aðeins það að samþykkja kostar peninga.

Fyrstu skrefin

1. Búðu til póstkort. Það sem þú sleppir kemur úr sniðmátinu eða er lesið af website.

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"}}'

Bréf virkar á sama hátt. Þetta bréf fer til Þýskalands, á þýsku, með prentaðri síðu á bakhliðinni:

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. Skoðaðu það. Myndin sýnir það sem verður prentað.

curl https://api.yotru.com/v1/cards/CARD_ID/preview/front \
  -H "Authorization: Bearer $YOTRU_KEY" -o front.png

3. Bættu við viðtakendum. Fyrsta kallið opnar herferð og auðkenni hennar er í 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. Samþykktu. Svarið inniheldur payUrl og herferðin fer í prentun þegar greitt hefur verið. Þú getur líka samþykkt og greitt á síðu herferðarinnar í stjórnborðinu. Næstu viðtakendur sem þú bætir við opna nýja herferð.

curl -X POST https://api.yotru.com/v1/campaigns/CAMPAIGN_ID/approve \
  -H "Authorization: Bearer $YOTRU_KEY"

Endapunktar

AðferðSlóðHlutverk
POST/v1/cardsBýr til póstkort eða bréf (JSON, eða multipart með data og photo)
PATCH/v1/cards/{id}Breytir póstkorti eða bréfi; aðeins það sem þú sendir breytist. Samþykktar herferðir halda sinni útgáfu
GET/v1/cards/{id}Sækir póstkort eða bréf
GET/v1/cards/{id}/preview/frontPóstkortið eða bréfið eins og það er prentað; einnig /back (póstkort, og bréf með backSide)
POST/v1/recipientsBætir við allt að 1.000 viðtakendum í hverju kalli
GET/v1/batch?cardId=Herferðin sem er að fyllast núna fyrir póstkort eða bréf
GET/v1/campaigns/{id}Staða herferðar
POST/v1/campaigns/{id}/approveSamþykkir: skilar greiðslutenglinum

Póstkort og bréf

Allir reitir eru valfrjálsir. Svarið inniheldur id, printable, issues og problems. Póstkort eða bréf sem þú bjóst til í stjórnborðinu virkar líka: afritaðu auðkenni þess undir Bréf. Viðtakendur sem eru sendir með því auðkenni fara í sérstaka herferð fyrir það póstkort eða bréf. Bréf er búið til með sama kalli og fær auðkenni eins og póstkort.

ReiturGildi
nameNafnið sem þú gefur því
productcard (póstkort) eða letter (bréf); card ef þú sleppir því. Póstkort fara til CA, US, NL, DE, GB; bréf til allra landa. Póstkorti er ekki hægt að breyta í bréf síðar, né öfugt
templatePóstkort: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Bréf: letter-formal, letter-classic, letter-band, letter-plain
countryCA, US, NL, DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS; NL ef þú sleppir því. Viðtakendur verða að búa í þessu landi
languageen, nl, fr, de, es, sv, no, da, fi, is; tungumál landsins ef þú sleppir því
backSideBréf til DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS: true prentar aðra síðu á bakhliðina, gegn aukagjaldi á hvert bréf
websiteLitir og merki eru lesin þaðan ef þú sendir þau ekki
destinationUrlHvert QR-kóðinn vísar; vefsíðan ef þú sleppir því
brandcompanyName, primaryColor, secondaryColor, logoUrl, font
textPóstkort: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Bréf: headline, body, ctaLine (við hliðina á QR-kóðanum), signOff, backHeadline, backBody
contactwebsite, email, phone

body bréfs er prentað eins og þú sendir það, svo byrjaðu það á kveðjunni sem þú vilt, til dæmis Góðan dag {firstName},. Breytur eins og {firstName}, {lastName} og {companyName} eru fylltar út fyrir hvern viðtakanda. Svarið inniheldur líka product og language; previewBack er null fyrir bréf með einni síðu.

Póstkorti til lands sem tekur aðeins við bréfum, tungumáli eða landi sem við þekkjum ekki og backSide utan þessara landa er hafnað með 400 sem segir hvaða reitur er rangur. Verðið fer eftir landinu sem póstkortið eða bréfið er sent í, sjá verð.

Viðtakendur

Viðtakandi þarf nafn manneskju eða fyrirtækis og fullt heimilisfang.

ReiturGildi
Manneskjaname, eða firstName og lastName; einnig company, jobTitle
Heimilisfangstreet, houseNumber, addition, eða addressLine1, addressLine2; einnig postcode, city, region, country
Annaðreference (skilað aftur til þín), email, phone, website, destinationUrl, customFields, photo

Hver viðtakandi kemur til baka sem accepted með id, eða sem refused með ástæðu: name, address, country, duplicate eða photo. Viðtakanda utan country póstkortsins eða bréfsins er hafnað með country; búðu þá til póstkort eða bréf fyrir land viðkomandi. Sendu hausinn Idempotency-Key svo öruggt sé að endurtaka kall.

Myndir

Sendu myndir sem skrár með multipart/form-data og settu JSON-ið í reit sem heitir data. Mest 25 skrár, 10 MB hver, í hverju kalli og 32 MB samtals. Á póstkorti eða bréfi heitir reiturinn photo. Viðtakandi með "photo": "anna.jpg" fær þá skrá; án hennar fær hann mynd póstkortsins eða bréfsins. Merki má vera tengill en mynd má það ekki.

Herferðir og greiðsla

Herferð er open, awaiting_payment, approved, printing eða sent. Engin lágmarkspöntun: þú greiðir fyrir póstkortin eða bréfin í herferðinni og ef þau eru færri en 100 kostar hvert stykki það sama og við 100. Þegar þú samþykkir fær eigandi aðgangsins líka tölvupóst með greiðslutengli og eftir greiðslu reikninginn.

Takmörk og villur

TakmörkÁ hvern lykil
Öll köll120 á mínútu
Að búa til eða breyta póstkortum og bréfum, og köll með myndum300 á dag

Villur eru JSON með message: 400 ef eitthvað er að því sem þú sendir, 401 ef lykil vantar eða hann er rangur, 404 ef eitthvað er ekki á aðganginum þínum, 409 þegar staðan leyfir það ekki og 429 þegar þú ferð yfir takmörk.