Base-URL, nøgler og scopes
Kald https://DIT-TRYKKERI/api/v1 på trykkeriets tildelte værtsnavn. Den offentlige reference ligger på /api/v1/openapi.json på samme vært; HeyMadeIts vært viser også den rutebaserede reference. Opret nøgler med scopes under /portal/platform/credentials. Send Authorization: Bearer DIN_API_NOEGLE og Accept: application/json. Nøgler virker kun på deres eget trykkeris vært. Opbevar dem på serveren, udskift dem ved behov, og tilbagekald ubrugte nøgler. Åbn udviklerportalen på /developers med interaktiv Swagger-dokumentation, kodeeksempler og en Postman-samling. AI-agenter kan læse /llms.txt, /llms-full.txt og /developers/reference.md direkte. Den tekniske reference er på engelsk.
Find eller opret en kunde
Brug GET /customers?email=person%40example.com til at finde kunden. POST /customers kræver name og email; locale er valgfrit. Gem data.id på jeres egen godkendte kunde. Lad aldrig browseren vælge en anden customer_id. Oprettelse af en kunde tildeler ikke Business-licens og sender ikke en loginmail.
POST /api/v1/customers
{"name":"Example customer","email":"[email protected]","locale":"en"}Find en skabelon og opret et redigerbart design
GET /templates understøtter category, width_mm, height_mm, pages og fields=browse. Svaret indeholder udgivne HeyMadeIt-skabeloner og jeres egne; andre trykkeriers skabeloner er udelukket. GET /templates/{uuid} læser én. Opret et design med customer_id, title og enten format eller width_mm og height_mm. Ved template skal slutformatet angives, og format udelades. Flade design understøtter op til otte sider i standard-API’et.
POST /api/v1/designs
{"customer_id":123,"title":"Business card","width_mm":85,"height_mm":55,"bleed_mm":3,"pages":1,"template":"TEMPLATE_UUID"}Udsted en engangssession til editoren
Opret en embed-nøgle, og tillad webshoppens præcise origin, inklusive https og eventuel port. Backend kalder POST /editor-sessions for den godkendte kundes design. parent_origin skal være tilladt. finish er save eller basket. Svaret indeholder session_token, expires_in (300 sekunder) og redeem_url. Tokenet kan indløses én gang via POST; det må ikke sættes i en URL. Send aldrig API-nøglen til browseren.
POST /api/v1/editor-sessions
{"customer_id":123,"design":"DESIGN_UUID","embed_key":"PUBLIC_EMBED_KEY","parent_origin":"https://shop.example.com","finish":"basket"}Åbn browser-SDK’et
Hent SDK’et fra trykkeriets vært. Jeres /design-session-endpoint skal godkende kunden og hente en ny session på serveren. SDK’et åbner en iframe og kontrollerer beskeder ud fra origin og frame. onComplete betyder, at designet er gemt; backend skal kontrollere ejerskab, produkt, antal og betaling før en ordre. close() fjerner iframen.
<script src="https://YOUR-PRINTER-HOST/embed/v1/sdk.js"></script>
<div id="design-editor"></div>
<script>
async function openDesigner() {
const response = await fetch("/design-session", {method: "POST"});
if (!response.ok) throw new Error("Could not start editor");
const session = await response.json();
window.HeyMadeIt.open({
container: "#design-editor",
sessionToken: session.session_token,
onComplete: data => console.log("Saved design", data),
onClose: reason => console.log("Closed", reason)
});
}
</script>Sæt en tryk-PDF i kø og hent den
POST /designs/{uuid}/exports med format pdf_print returnerer HTTP 202 og data.uuid. Spørg GET /exports/{uuid}; status done giver file_url. Hent den relative URL fra serveren med samme bearer-nøgle. Andre statusser omfatter queued, rendering, encoding, failed og canceled; håndter fejl og udløb. layout kan være pages eller spreads. Brug bleed:true til dokumentets beskæring og marks:true til skæremærker.
POST /api/v1/designs/DESIGN_UUID/exports
{"format":"pdf_print","bleed":true,"marks":true,"layout":"pages"}Produkter, fragt og idempotente ordrer
Produkter bruger width, height, unit og antalpriser i mindste valutaenhed (net_ore). Fragt bruger /shipping-methods. POST /orders kræver headeren Idempotency-Key, customer_id, payment_method, shipping_method_id og lines med product, design og quantity. Genbrug kun nøglen til samme ordreindhold. Læs GET /orders/{uuid} for produktionsfiler. Brug PATCH /orders/{uuid} med paid eller cancelled, når serveren har verificeret betaling eller annullering. Ved ekstern betaling verificerer HeyMadeIt ikke betalingsudbyderen for jer.
POST /api/v1/orders
Idempotency-Key: shop-order-1042
{"customer_id":123,"payment_method":"external","shipping_method_id":7,"lines":[{"product":"PRODUCT_UUID","design":"DESIGN_UUID","quantity":100}]}Tildeling af Business-licenser
GET /client-licences returnerer allowance, allocated og virksomhedsteams. POST /client-licences kræver customer_id (virksomhedens ejer), name og seats. Udelad team for at oprette et team; send et eksisterende team-UUID for at ændre antallet. Alle teams bruger samme trykkerpulje. API-nøgler skal have licences:read eller licences:write. Ejeren og åbne invitationer tæller med i virksomhedens pladser. DELETE /client-licences/{team} frigiver virksomhedens tildeling uden at slette dens arbejde.
POST /api/v1/client-licences
{"customer_id":123,"name":"Example company","seats":3}Fejl, sideinddeling og kaldgrænser
401 betyder manglende, tilbagekaldt eller forkert-vært-nøgle. 403 betyder manglende scope, slukket integration eller utilstrækkelig adgang. 404 beskytter også andre lejeres ressourcer. 409 viser konflikt i status eller idempotens. 422 returnerer valideringsfejl. 429 betyder vent og prøv igen med længere mellemrum. Lister har data og metadata om sideinddeling; de fleste kataloglister accepterer per_page op til 100. Følg kaldgrænserne i OpenAPI-referencen. MCP bruger brugerens OAuth/adgangstoken, ikke merchant API-nøglerne.