Yotru API
Lag postkort og brev, legg til mottakere og godkjenn kampanjer fra ditt eget system. Hver mottaker legges til i en åpen kampanje for det kortet eller brevet, og ingenting sendes før kampanjen er godkjent og betalt. Post går til 16 land: postkort til CA, US, NL, DE, GB, brev til alle.
Autentisering
Den første nøkkelen din lages når du åpner Innstillinger → Integrasjoner → API-nøkler. E-postadressen din må være bekreftet, og du må være eier eller administrator for kontoen. En nøkkel vises bare én gang, så lagre den med en gang. Mister du den, lager du en ny og trekker tilbake den gamle.
Authorization: Bearer yk_live_...Basis-URL-en er https://api.yotru.com. Det finnes ingen testmodus: alle nøkler er live, men du kan fritt lage kort og legge til mottakere. Bare godkjenning koster penger.
Hurtigstart
1. Lag et kort. Det du utelater, kommer fra malen eller leses fra 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"}}'Et brev fungerer på samme måte. Dette går til Tyskland, på tysk, med en trykt side på baksiden:
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. Se på det. Bildet er det som blir trykt.
curl https://api.yotru.com/v1/cards/CARD_ID/preview/front \
-H "Authorization: Bearer $YOTRU_KEY" -o front.png3. Legg til mottakere. Det første kallet åpner en kampanje. ID-en finnes i 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. Godkjenn. Svaret inneholder en payUrl, og kampanjen går til trykk når den er betalt. Du kan også godkjenne og betale på kampanjesiden i dashbordet. De neste mottakerne du legger til, åpner en ny kampanje.
curl -X POST https://api.yotru.com/v1/campaigns/CAMPAIGN_ID/approve \
-H "Authorization: Bearer $YOTRU_KEY"Endepunkter
| Metode | Sti | Hva det gjør |
|---|---|---|
| POST | /v1/cards | Lag et kort (JSON, eller multipart med data og photo) |
| PATCH | /v1/cards/{id} | Endre et kort. Bare det du sender, endres. Godkjente kampanjer beholder kortet sitt |
| GET | /v1/cards/{id} | Les et kort |
| GET | /v1/cards/{id}/preview/front | Kortet eller brevet slik det blir trykt. Også /back (postkort, og brev med backSide) |
| POST | /v1/recipients | Legg til opptil 1 000 mottakere per kall |
| GET | /v1/batch?cardId= | Kampanjen som fylles nå for et kort |
| GET | /v1/campaigns/{id} | Status for en kampanje |
| POST | /v1/campaigns/{id}/approve | Godkjenn: returnerer betalingslenken |
Kort
Alle felt er valgfrie. Svaret inneholder id, printable, issues og problems. Et kort du har laget i dashbordet, fungerer også: kopier ID-en under Brev. Mottakere som sendes med ID-en til et kort, havner i en egen kampanje for det kortet. Et brev lages med det samme kallet og får en ID akkurat som et kort.
| Felt | Verdier |
|---|---|
name | Hva du kaller kortet |
product | card eller letter; card hvis det utelates. Postkort går til CA, US, NL, DE, GB, brev til alle land. Et postkort kan ikke bli et brev senere, eller omvendt |
template | Postkort: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Brev: 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; NL hvis det utelates. Mottakerne må bo i dette landet |
language | en, nl, fr, de, es, sv, no, da, fi, is; landets eget språk hvis det utelates |
backSide | Brev til DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS: true trykker en side til på baksiden, mot et tillegg per brev |
website | Farger og logo leses herfra når du ikke sender dem |
destinationUrl | Hvor QR-koden leder; nettsiden hvis det utelates |
brand | companyName, primaryColor, secondaryColor, logoUrl, font |
text | Postkort: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Brev: headline, body, ctaLine (ved siden av QR-koden), signOff, backHeadline, backBody |
contact | website, email, phone |
body i et brev blir trykt nøyaktig slik du sender den, så start med hilsenen du vil ha, for eksempel Hei {firstName},. Tokens som {firstName}, {lastName} og {companyName} fylles inn per mottaker. Svaret inneholder også product og language. previewBack er null for et brev med én side.
Et postkort til et land som bare tar imot brev, et språk eller land vi ikke kjenner, og backSide utenfor de landene avvises med 400 og en melding om hvilket felt som er feil. Prisen er den som gjelder i landet kortet eller brevet sendes fra, se priser.
Mottakere
En mottaker trenger en person eller et firma, og en fullstendig adresse.
| Felt | Verdier |
|---|---|
| Person | name, eller firstName og lastName; også company, jobTitle |
| Adresse | street, houseNumber, addition, eller addressLine1, addressLine2; også postcode, city, region, country |
| Annet | reference (sendes tilbake til deg), email, phone, website, destinationUrl, customFields, photo |
Hver mottaker kommer tilbake som accepted med en id, eller som refused med en grunn: name, address, country, duplicate eller photo. En mottaker utenfor kortets country avvises med country. Lag i stedet et kort eller brev for mottakerens land. Send en Idempotency-Key-header, så er et gjentatt kall trygt.
Bilder
Send bilder som filer med multipart/form-data, og legg JSON i et felt som heter data. Maks 25 filer på 10 MB per kall og 32 MB totalt. På et kort heter feltet photo. En mottaker med "photo": "anna.jpg" får den filen. Uten får mottakeren kortets bilde. En logo kan være en lenke, et bilde kan ikke det.
Kampanjer og betaling
En kampanje er open, awaiting_payment, approved, printing eller sent. Det finnes ikke noe minimum: du betaler for kortene og brevene i kampanjen. Under 100 stykk koster hvert stykk det samme som ved 100. Når du godkjenner, får kontoeieren også en e-post med en betalingslenke, og etter betalingen fakturaen.
Grenser og feil
| Grense | Per nøkkel |
|---|---|
| Alle kall | 120 i minuttet |
| Lage eller endre kort, og kall med bilder | 300 per dag |
Feil kommer som JSON med en message: 400 for feil i det du sendte, 401 for manglende eller feil nøkkel, 404 for noe som ikke finnes på kontoen din, 409 når statusen ikke tillater det, 429 når du er over en grense.