API-documentatie
In het kort
Met de API verstuur je printjobs vanuit je eigen software en volg je wat ermee gebeurt. Het basisadres is https://api.printmelo.com/api/v1.
- Maak een API-key aan in het dashboard onder API-keys.
- Zoek het id van je printer op in het overzicht, of via
GET /printers. - Verstuur een printjob met
POST /printjobs.
curl -X POST https://api.printmelo.com/api/v1/printjobs \
-H "Authorization: Bearer JOUW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-10482-label" \
-d '{"printer_id": 12, "title": "Verzendlabel 10482", "content_type": "pdf_uri", "content": "https://example.com/labels/10482.pdf"}'
De machineleesbare beschrijving staat op https://app.printmelo.com/openapi.json (OpenAPI 3.1). Daarmee genereer je een client in je eigen programmeertaal.
AI-assistenten en coding agents
Printmelo heeft een MCP-server op https://api.printmelo.com/mcp. Een coding agent doorzoekt daarmee deze documentatie, bekijkt printers en printjobs en test op de oefenprinter. Inloggen gaat met een API-key als Bearer-token, of via OAuth.
Fouten
Een fout heeft altijd dezelfde vorm: een leesbare message en een vaste code.
| Code | Betekenis |
|---|---|
unauthenticated | De API-key ontbreekt of is ongeldig. |
forbidden | Deze key geeft geen toegang tot dit endpoint, of mist het recht dat het endpoint vraagt. |
not_found | Dit bestaat niet in jouw account. |
validation_failed | De invoer klopt niet. Het veld errors zegt per veld wat er mis is. |
plan_limit | De limiet van je abonnement is bereikt of je proefperiode is afgelopen. |
conflict | De actie past niet bij de huidige toestand, bijvoorbeeld een printjob die al is afgerond. |
rate_limited | Te veel verzoeken. Probeer het later opnieuw. |
key_budget | Deze API-key heeft zijn dagbudget voor printjobs bereikt. Morgen kan hij weer printen. |
server_error | Er ging iets mis aan onze kant. |
Overstappen van PrintNode
De API lijkt bewust op die van PrintNode, zodat een bestaande koppeling met weinig werk overstapt. Deze veldnamen van PrintNode werken ook bij ons.
| PrintNode | Printmelo | Opmerking |
|---|---|---|
| Basic-auth met de key als gebruikersnaam | Hetzelfde, of Bearer | Geen wijziging nodig. |
printerId | printer_id | Beide werken. De ids zelf zijn anders: haal ze opnieuw op. |
contentType | content_type | Beide werken, met dezelfde waarden: pdf_uri, pdf_base64, raw_uri, raw_base64. |
qty of options.copies | copies | Alle drie werken. |
expireAfter | expire_after | Beide werken, in seconden. |
X-Idempotency-Key | Idempotency-Key | Beide werken. |
Child accounts met X-Child-Account-By-Id of -By-CreatorRef | Sub-accounts met X-Child-Account-Id of -Reference | Beide werken. Zie Sub-accounts hieronder. |
| Antwoord is een los getal of een lijst | {"data": ...} | Pas het uitlezen van het antwoord aan. |
Status done bij afleveren aan de wachtrij | spooled, daarna done | done betekent bij ons dat de printer het heeft geprint. |
Wat je erbij krijgt: uitwijkprinters en printergroepen, afbeeldingen printen, de reden waarom een printer wacht, de doorlooptijd per printjob, vaste foutcodes en ondertekende webhooks.