Yotru API
Opret postkort og breve, tilføj modtagere og godkend kampagner fra din egen software. Hver modtager føjes til en åben kampagne for det kort eller brev, og intet sendes, før kampagnen er godkendt og betalt. Post går til 16 lande: postkort til CA, US, NL, DE, GB, breve til dem alle.
Autentificering
Din første nøgle oprettes, når du åbner Indstillinger → Integrationer → API-nøgler. Din e-mailadresse skal være bekræftet, og du skal være ejer eller administrator af kontoen. En nøgle vises kun én gang, så gem den med det samme. Mister du den, så opret en ny og tilbagekald den gamle.
Authorization: Bearer yk_live_...Basis-URL'en er https://api.yotru.com. Der er ingen testtilstand: alle nøgler er live, men du kan frit oprette kort og tilføje modtagere. Kun godkendelse koster penge.
Kom i gang
1. Opret et kort. Det, du udelader, kommer fra skabelonen eller læses 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åde. Dette brev går til Tyskland, på tysk, med en trykt side på bagsiden:
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 det. Billedet er præcis det, der bliver trykt.
curl https://api.yotru.com/v1/cards/CARD_ID/preview/front \
-H "Authorization: Bearer $YOTRU_KEY" -o front.png3. Tilføj modtagere. Det første kald åbner en kampagne; dens id står 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. Godkend. Svaret indeholder en payUrl; kampagnen går til tryk, når den er betalt. Du kan også godkende og betale på kampagnesiden i dit dashboard. De næste modtagere, du tilføjer, åbner en ny kampagne.
curl -X POST https://api.yotru.com/v1/campaigns/CAMPAIGN_ID/approve \
-H "Authorization: Bearer $YOTRU_KEY"Endpoints
| Metode | Sti | Hvad den gør |
|---|---|---|
| POST | /v1/cards | Opret et kort (JSON eller multipart med data og photo) |
| PATCH | /v1/cards/{id} | Ændr et kort; kun det, du sender, ændres. Godkendte kampagner beholder deres kort |
| GET | /v1/cards/{id} | Hent et kort |
| GET | /v1/cards/{id}/preview/front | Kortet eller brevet, som det bliver trykt; også /back (kort og breve med backSide) |
| POST | /v1/recipients | Tilføj op til 1.000 modtagere pr. kald |
| GET | /v1/batch?cardId= | Den kampagne, der fyldes op for et kort lige nu |
| GET | /v1/campaigns/{id} | Status for en kampagne |
| POST | /v1/campaigns/{id}/approve | Godkend: returnerer betalingslinket |
Kort
Alle felter er valgfrie. Svaret indeholder id, printable, issues og problems. Et kort, du har lavet i dit dashboard, virker også: kopiér dets id under Breve. Modtagere sendt med et kort-id kommer på en kampagne for netop det kort. Et brev oprettes med samme kald og har et id ligesom et kort.
| Felt | Værdier |
|---|---|
name | Dit eget navn til kortet |
product | card eller letter; card, hvis feltet udelades. Kort går til CA, US, NL, DE, GB; breve til alle lande. Et kort kan ikke senere blive til et brev eller omvendt |
template | Kort: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Breve: 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 feltet udelades. Modtagerne skal bo i dette land |
language | en, nl, fr, de, es, sv, no, da, fi, is; landets eget sprog, hvis feltet udelades |
backSide | Breve til DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS: true trykker en ekstra side på bagsiden mod et tillæg pr. brev |
website | Farver og logo læses herfra, når du ikke sender dem |
destinationUrl | Hvor QR-koden fører hen; hjemmesiden, hvis feltet udelades |
brand | companyName, primaryColor, secondaryColor, logoUrl, font |
text | Kort: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Breve: headline, body, ctaLine (ved siden af QR-koden), signOff, backHeadline, backBody |
contact | website, email, phone |
Et brevs body trykkes, præcis som du sender den, så start med den hilsen, du ønsker, for eksempel Kære {firstName},. Tokens som {firstName}, {lastName} og {companyName} udfyldes pr. modtager. Svaret indeholder også product og language; previewBack er null for et brev på én side.
Et kort til et land, der kun modtager breve, et sprog eller land, vi ikke kender, og backSide uden for de lande afvises med en 400, der fortæller, hvilket felt der er forkert. Prisen følger det land, kortet eller brevet sendes i, se priser.
Modtagere
En modtager skal have en person eller en virksomhed og en fuldstændig adresse.
| Felt | Værdier |
|---|---|
| Person | name eller firstName og lastName; også company, jobTitle |
| Adresse | street, houseNumber, addition eller addressLine1, addressLine2; også postcode, city, region, country |
| Andet | reference (returneres til dig), email, phone, website, destinationUrl, customFields, photo |
Hver modtager kommer tilbage som accepted med et id eller som refused med en årsag: name, address, country, duplicate eller photo. En modtager uden for kortets country afvises med country; opret i stedet et kort eller brev til modtagerens land. Send en Idempotency-Key-header, så et gentaget kald er sikkert.
Fotos
Send fotos som filer med multipart/form-data, og læg JSON i et felt, der hedder data. Højst 25 filer på 10 MB pr. kald og 32 MB i alt. På et kort hedder feltet photo. En modtager med "photo": "anna.jpg" får den fil; uden får modtageren kortets foto. Et logo må gerne være et link; et foto må ikke.
Kampagner og betaling
En kampagne er open, awaiting_payment, approved, printing eller sent. Der er intet minimum: du betaler for kortene på kampagnen, og under 100 kort koster hvert kort det samme som ved 100 kort. Når du godkender, får kontoejeren også et betalingslink på e-mail og efter betaling fakturaen.
Grænser og fejl
| Grænse | Pr. nøgle |
|---|---|
| Alle kald | 120 i minuttet |
| Oprettelse eller ændring af kort og kald med fotos | 300 om dagen |
Fejl er JSON med en message: 400 for fejl i det, du sendte, 401 for en manglende eller forkert nøgle, 404 for noget, der ikke findes på din konto, 409, når tilstanden ikke tillader det, og 429, når du er over en grænse.