Briefe aus Ihrem Workflow.
Sicher per API.

Jeder Kunde erhält einen eigenen Live-Schlüssel. Der vollständige Schlüssel wird bei der Erstellung genau einmal angezeigt und serverseitig ausschließlich als SHA-256-Hash gespeichert.

Authorization: Bearer yk_live_…

• Schlüssel ausschließlich in einem Secret Store oder einer geschützten Umgebungsvariable speichern.
• Für Test, Produktion und getrennte Anwendungen jeweils eigene Schlüssel verwenden.
• Bei Verdacht auf Offenlegung den Schlüssel sofort über Yonek widerrufen lassen.

Ein API-Key, ein stabiler Idempotency-Key und ein JSON-Body genügen.

curl --request POST 'https://yonek.de/api/brief/v1/orders' \
  --header 'Authorization: Bearer yk_live_…' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: crm-4711-2026-09-26' \
  --data '{
    "external_id": "crm-4711",
    "recipient": {
      "name": "Max Mustermann",
      "company": "Muster GmbH",
      "address_line1": "Musterstraße 1",
      "postal_code": "12345",
      "city": "Berlin",
      "country": "DE"
    },
    "letter": {
      "salutation": "Sehr geehrter Herr Mustermann,",
      "text": "vielen Dank für das angenehme Gespräch. Wie angekündigt erhalten Sie heute unsere Unterlagen."
    },
    "sender_reference": "CRM-4711",
    "context": "Interne Zusatzinformation zur manuellen Prüfung.",
    "metadata": {
      "campaign": "herbst-2026",
      "account_owner": "roman"
    }
  }'

const response = await fetch('https://yonek.de/api/brief/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YONEK_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'crm-4711-2026-09-26'
  },
  body: JSON.stringify({
    external_id: 'crm-4711',
    recipient: {
      name: 'Max Mustermann',
      company: 'Muster GmbH',
      address_line1: 'Musterstraße 1',
      postal_code: '12345',
      city: 'Berlin',
      country: 'DE'
    },
    letter: {
      text: 'Vielen Dank für das angenehme Gespräch. Wie angekündigt erhalten Sie heute unsere Unterlagen.'
    }
  })
});

const result = await response.json();
if (!response.ok) throw new Error(result.error);

Erfolgreiche Antwort 201 Created

{
  "order_id": "bo_mg12abc_1a2b3c4d",
  "status": "received",
  "status_url": "/api/brief/v1/orders/bo_mg12abc_1a2b3c4d",
  "duplicate": false
}

Legt eine neue Bestellung im Status received an. Der Endpunkt erwartet UTF-8-kodiertes JSON.

Header

Request-Body

Ruft den aktuellen Status einer Bestellung ab. Ein API-Key sieht ausschließlich Bestellungen, die mit demselben Schlüssel angelegt wurden.

curl 'https://yonek.de/api/brief/v1/orders/bo_mg12abc_1a2b3c4d' \
  -H 'Authorization: Bearer yk_live_…'

{
  "order_id": "bo_mg12abc_1a2b3c4d",
  "external_id": "crm-4711",
  "status": "production",
  "status_text": "In Produktion",
  "created_at": "2026-09-26T09:30:00.000Z",
  "updated_at": "2026-09-26T11:15:00.000Z",
  "sent_at": null,
  "estimated_delivery_at": null,
  "delivered_at": null,
  "delivery_estimate_passed": false,
  "request_id": "req_muidwm02_1709e62e0f"
}

Statusmodell

Optional sendet Yonek die Ereignisse order.created und order.status_changed an Ihren HTTPS-Endpunkt. Zustellungen laufen über eine persistente Outbox und werden bei Fehlern mit exponentiellem Backoff bis zu zehnmal wiederholt.

{
  "id": "wh_muidx1_1a2b3c4d",
  "event": "order.status_changed",
  "created_at": "2026-09-26T12:30:00.000Z",
  "data": {
    "order_id": "bo_mg12abc_1a2b3c4d",
    "external_id": "crm-4711",
    "status": "sent",
    "created_at": "2026-09-26T09:30:00.000Z",
    "updated_at": "2026-09-26T12:30:00.000Z",
    "sent_at": "2026-09-26T12:30:00.000Z",
    "estimated_delivery_at": "2026-09-30T12:30:00.000Z",
    "delivered_at": null
  }
}

Signatur prüfen

Der Header Yonek-Signature hat das Format t=UNIXZEIT,v1=HMAC. Berechnen Sie HMAC-SHA-256 über t + "." + rawBody mit Ihrem einmalig angezeigten Webhook-Secret und vergleichen Sie timing-sicher. Lehnen Sie Zeitstempel ab, die deutlich älter als fünf Minuten sind.

Verwenden Sie pro logischer Bestellung einen stabilen Idempotency-Key. Senden Sie denselben Request bei Timeout oder unklarer Netzwerkantwort mit demselben Key erneut.

Die Idempotenz gilt innerhalb eines API-Keys. Derselbe Key kann bei zwei verschiedenen Kundenschlüsseln jeweils eine Bestellung erzeugen.

Ihre tatsächlich konfigurierten Grenzen und den vereinbarten Preis erhalten Sie authentifiziert über:

Rate-Limits werden dauerhaft gespeichert und überstehen Neustarts. Antworten enthalten X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Bei 429 kommt zusätzlich Retry-After. Tageskontingente werden um 00:00 UTC zurückgesetzt.

Fehler werden konsistent als JSON mit den Feldern error, message und request_id ausgegeben. Validierungsfehler enthalten zusätzlich details. Unbekannte Nutzdatenfelder werden bewusst abgelehnt.

{
  "error": "validation_failed",
  "details": [
    "recipient.address_line1 fehlt",
    "letter.text muss mindestens 10 Zeichen enthalten"
  ]
}

Empfohlene Integrationspraxis

1. 1
   Vor dem Senden validieren

   Adresse, Empfänger und finalen Brieftext bereits in Ihrem System prüfen.

2. 2
   Secrets serverseitig halten

   API-Key nie loggen, an Clients senden oder in Quellcode einchecken.

3. 3
   Retries begrenzen

   Bei 429 den Retry-After-Header beachten, sonst exponentielles Backoff verwenden.

4. 4
   IDs speichern

   order_id, external_id und Idempotency-Key gemeinsam in Ihrer Datenbank ablegen.

5. 5
   Status moderat pollen

   Für normale Abläufe reichen wenige Statusabfragen pro Tag.