API-Referenz

Public API für serverseitige Badge-Workflows

Alle Endpunkte, Parameter, Header und Resultate für Integrationen mit privatem API-Key. Der Vertragsstand wird direkt aus dem OpenAPI-Dokument der API erzeugt.

Schnellstart

Basis-URL: https://api.namensschild.io

1Privaten API-Key im Dashboard erzeugen und ausschließlich serverseitig speichern.
2Für Tooling und Automatisierung zuerst /openapi.json oder die Root-Discovery unter / abrufen.
3Mit GET /v1/templates und GET /v1/paper-presets kompatible IDs für Vorlage und Papierpreset ermitteln.
4Mit GET /v1/credits das verfügbare Guthaben und den Account-Status prüfen.
5Mit POST /v1/generate `template_id`, CSV, `slot_mapping` und entweder `paper_preset_id` oder `paper_layout` senden und das PDF direkt speichern.
6Die Export-ID persistieren und bei Bedarf später über GET /v1/exports oder GET /v1/exports/{id} weiterverwenden.

Authentifizierung & Header

Persönlicher API-Schlüssel im Format Bearer ns_live_… oder Bearer ns_test_…

Authorizationheader

Privater API-Schlüssel als Bearer-Token. Gehört ausschließlich in einen vertrauenswürdigen Server-Kontext.

Authorization: Bearer <api_key>

Test vs. Livens_test_… / ns_live_…

Beide Schlüsselarten sprechen denselben Vertrag an, trennen aber die Verarbeitungsumgebung.

X-Request-Idheader

Jede Antwort enthält diese Korrelations-ID. Für Support- und Debug-Fälle in den eigenen Logs speichern.

Idempotency-Keyheader

Bei POST /v1/generate immer mitsenden, wenn das System Requests automatisch wiederholt – verhindert Doppelabbuchung.

Discovery & Verträge

Für Agenten, SDKs und Integrations-Tooling veröffentlicht die API-Domain zusätzlich zur menschlichen Referenz mehrere maschinenlesbare Discovery-Artefakte.

Root Discovery JSONhttps://api.namensschild.io/

Maschinenlesbarer Einstieg mit Basis-URL, Auth-Hinweisen, Discovery-Artefakten und den wichtigsten Ressourcen.

OpenAPI 3.1https://api.namensschild.io/openapi.json

Kanonische Maschinenbeschreibung der Public API. /openapi/v1 bleibt als Kompatibilitätsalias erreichbar.

llms.txthttps://api.namensschild.io/llms.txt

Kuratierter KI-Hinweis für Agenten, der auf OpenAPI, Docs und die wichtigsten Endpunkte verweist.

API-Kataloghttps://api.namensschild.io/.well-known/api-catalog

Standardisierte Discovery im Linkset-Format mit service-desc-, service-doc- und service-meta-Verweisen.

POST/v1/generate

Der Export-Endpunkt nimmt eine explizite `template_id`, CSV, ein semantisches `slot_mapping` und genau eine Layoutquelle entgegen: entweder `paper_preset_id` oder `paper_layout`. Daraus rendert die API sofort ein PDF und belastet die benötigten Credits direkt im selben Request.

Scope: exports:write

Erfolgsantwort: PDF-Datei im Body mit Export- und Credit-Headern.
Pflichtfelder: `template_id`, `slot_mapping`, `csv` und genau eines von `paper_preset_id` oder `paper_layout`.
Die Schildgröße kommt aus der Vorlage; Preset oder Direktlayout definieren nur Seite, Ränder, Lücken, Spalten und Zeilen.
`slot_mapping` ist ein JSON-String im Format Slot -> CSV-Header.
Optional: `Idempotency-Key` für sichere Retries bei Netzwerkabbrüchen.

Parameter

Idempotency-Keystringheaderoptional

Optionale UUID, um wiederholte Schreib-Requests 24 Stunden lang idempotent zu machen.

Format: uuid

Request Body

multipart/form-data · erforderlich

template_idstringerforderlich

Konkrete Vorlagen-ID für das Badge-Layout.

paper_preset_idstringoptional

Optionale Papierpreset-ID. Sende entweder paper_preset_id oder paper_layout.

paper_layoutstringoptional

Optionaler JSON-String mit direktem Papierlayout. Sende entweder paper_layout oder paper_preset_id.

slot_mappingstringerforderlich

JSON-String im Format {"first_name":"Vorname","last_name":"Nachname"}. Pflicht-Slots hängen von der gewählten Vorlage ab.

csvstringerforderlich

Format: binary

fontstringoptional

Werte: courier, helvetica, times · Standardwert: courier

colorstringoptional

Pattern: ^#[0-9A-Fa-f]{6}$

logostringoptional

Format: binary

webhook_urlstringoptional

Format: uri

modestringoptional

Werte: live, test · Standardwert: live

Verfügbare Template-Slots

Klassisch

tpl_classic_default

Pflicht-Slots: first_name, last_name, company, role

Mit Logo

tpl_logo_default

Pflicht-Slots: first_name, last_name, company

Mit QR-Code

tpl_qr_default

Pflicht-Slots: first_name, last_name, company, qr_code

Minimal

tpl_minimal_default

Pflicht-Slots: first_name, last_name

Responses

200PDF erfolgreich erzeugt.

application/pdf · string

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

X-Export-Idstringoptional

X-Credits-Chargedintegeroptional

Minimum: 0

X-Credits-Remainingintegeroptional

Minimum: 0

400Pflichtfeld fehlt oder ungültiger Wert.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

401Kein oder ungültiger API-Schlüssel.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

402Nicht genug Credits für den angeforderten Export.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

403Schlüssel vorhanden, aber ohne Berechtigung für diesen Endpunkt.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

413CSV oder Logo ist größer als das erlaubte Limit.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

422CSV oder slot_mapping konnten nicht verarbeitet werden.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

429Zu viele Requests in kurzer Zeit.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

Retry-Afterintegeroptional

Minimum: 1

X-RateLimit-Remainingintegeroptional

Minimum: 0

X-RateLimit-Resetintegeroptional

Minimum: 0

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

Hinweise für die Integration

Ein privater API-Key gehört ausschließlich in dein Backend oder in einen anderen vertrauenswürdigen Server-Kontext.
Gültige Vorlagen und Papierpresets findest du über `GET /v1/templates` und `GET /v1/paper-presets`.
`paper_layout` ist ein JSON-String. Verwende ihn, wenn du Seitengröße, Ränder, Lücken und Raster direkt pro Export festlegen willst.
Logo-Dateien laufen außerhalb von `slot_mapping` über das separate Multipart-Feld `logo`.
Die Antwort enthält immer `X-Export-Id`, `X-Credits-Charged` und `X-Credits-Remaining`.

curl https://api.namenschild.io/v1/generate \
  -X POST \
  -H "Authorization: Bearer ns_live_dein_privater_api_key" \
  -H "Idempotency-Key: 9a4f3b8e-2c1d-4e7f-b0a1-1234567890ab" \
  -F "template_id=tpl_classic_default" \
  -F "paper_preset_id=ppt_badge_80x50_tech_sheet" \
  -F 'slot_mapping={"first_name":"Vorname","last_name":"Nachname","company":"Firma","role":"Position"}' \
  -F "font=helvetica" \
  -F "color=#7836F4" \
  -F "csv=@teilnehmende.csv;type=text/csv" \
  -F "logo=@logo.png;type=image/png" \
  -D headers.txt \
  -o badges.pdf

Beispiel: direktes paper_layout

{
  "sheet": { "width_mm": 210, "height_mm": 297 },
  "margins": { "top_mm": 20, "right_mm": 15, "bottom_mm": 20, "left_mm": 15 },
  "gaps": { "horizontal_mm": 20, "vertical_mm": 20 },
  "grid": { "columns": 2, "rows": 4 },
  "fill_direction": "row_major"
}

Beispiel: Erfolgs-Header

HTTP/1.1 200 OK
Content-Type: application/pdf
X-Request-Id: 34f7251c-36e8-48a2-a34d-09a6515e64af
X-Export-Id: exp_8a0f4f17c56a4dbca28ee935
X-Credits-Charged: 48
X-Credits-Remaining: 152

Beispiel: Fehlerantwort bei ungültigem slot_mapping

{
  "type": "invalid_slot_mapping",
  "message": "Für die gewählte Vorlage fehlen Pflicht-Slots: role.",
  "docUrl": "https://docs.namenschild.io/api#errors"
}

GET/v1/credits

Dieser Endpunkt liefert den aktuellen Credit-Stand des Accounts, das nächste Verfallsdatum und die Auto-Refill-Einstellungen.

Scope: credits:read

Typischer Einsatz: Vor einem Export die verfügbare Kapazität prüfen.
Die Antwort ist immer JSON.
`credits_remaining` ist die Zahl, die für metered Accounts tatsächlich verbraucht werden kann.

Responses

200Aktueller Credit-Stand.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

credits_remainingintegererforderlich

Minimum: 0

credits_expire_atstring | nullerforderlich

Format: date-time

is_unlimitedbooleanerforderlich

auto_refillbooleanerforderlich

auto_refill_thresholdinteger | nullerforderlich

Minimum: 0

auto_refill_packagestring | nullerforderlich

401Kein oder ungültiger API-Schlüssel.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

403Schlüssel vorhanden, aber ohne Berechtigung für diesen Endpunkt.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

429Zu viele Requests in kurzer Zeit.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

Retry-Afterintegeroptional

Minimum: 1

X-RateLimit-Remainingintegeroptional

Minimum: 0

X-RateLimit-Resetintegeroptional

Minimum: 0

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

Hinweise für die Integration

Bei Unlimited-Accounts bleibt `credits_remaining` als technischer Saldo sichtbar, `is_unlimited` ist dann zusätzlich `true`.
Die Daten kommen aus dem serverseitigen Ledger und nicht aus einer separat gepflegten Balance-Tabelle.

curl https://api.namenschild.io/v1/credits \
  -H "Authorization: Bearer ns_live_dein_privater_api_key"

Beispiel: JSON-Antwort

{
  "credits_remaining": 152,
  "credits_expire_at": "2026-12-31T23:59:59.000Z",
  "is_unlimited": false,
  "auto_refill": true,
  "auto_refill_threshold": 50,
  "auto_refill_package": "200"
}

GET/v1/templates

Dieser Endpunkt listet alle verfügbaren Vorlagen des Accounts. Optional kannst du die Liste auf Vorlagen einschränken, die mit einem bestimmten Papierpreset kompatibel sind.

Scope: templates:read

Typischer Einsatz: zuerst eine gültige `template_id` für den Export auswählen.
Optionaler Filter: `paper_preset_id`.
Die Antwort zeigt pro Vorlage die erforderlichen Public-API-Slots.

Parameter

paper_preset_idstringqueryoptional

Optionaler Kompatibilitätsfilter für ein bestimmtes Papierpreset.

Responses

200Verfügbare Vorlagen für den Account.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

dataarrayerforderlich

401Kein oder ungültiger API-Schlüssel.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

403Schlüssel vorhanden, aber ohne Berechtigung für diesen Endpunkt.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

429Zu viele Requests in kurzer Zeit.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

Retry-Afterintegeroptional

Minimum: 1

X-RateLimit-Remainingintegeroptional

Minimum: 0

X-RateLimit-Resetintegeroptional

Minimum: 0

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

Hinweise für die Integration

Die Liste enthält Systemvorlagen und private Vorlagen des authentifizierten Accounts.
Nutze die Slot-Liste direkt, um dein `slot_mapping` gegen die CSV-Header zu validieren.

curl "https://api.namenschild.io/v1/templates?paper_preset_id=ppt_badge_80x50_tech_sheet" \
  -H "Authorization: Bearer ns_live_dein_privater_api_key"

Beispiel: Vorlagenliste

{
  "data": [
    {
      "id": "tpl_classic_default",
      "name": "Klassisch",
      "design": "classic",
      "badge_width_mm": 80,
      "badge_height_mm": 50,
      "default_paper_preset_id": "ppt_badge_80x50_tech_sheet",
      "required_slots": ["first_name", "last_name", "company", "role"]
    }
  ]
}

GET/v1/templates/{id}

Dieser Endpunkt liefert die Detailansicht einer einzelnen Vorlage, inklusive Status, Sichtbarkeit und erforderlicher Slots.

Scope: templates:read

Typischer Einsatz: Detailvalidierung einer bereits ausgewählten `template_id`.
Die Antwort bleibt JSON und enthält keine Binärdaten.
Bei unbekannter oder nicht verfügbarer Vorlage liefert der Endpunkt `404`.

Parameter

idstringpatherforderlich

Responses

200Vorlagen-Detailansicht.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

idstringerforderlich

namestringerforderlich

designstringerforderlich

Werte: classic, logo, qr, minimal

badge_width_mmnumbererforderlich

badge_height_mmnumbererforderlich

default_paper_preset_idstringerforderlich

required_slotsarrayerforderlich

visibilitystringerforderlich

Werte: system, private

statusstringerforderlich

Werte: draft, published

definition_versionintegererforderlich

Minimum: 1

401Kein oder ungültiger API-Schlüssel.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

403Schlüssel vorhanden, aber ohne Berechtigung für diesen Endpunkt.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

404Ressource nicht gefunden.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

429Zu viele Requests in kurzer Zeit.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

Retry-Afterintegeroptional

Minimum: 1

X-RateLimit-Remainingintegeroptional

Minimum: 0

X-RateLimit-Resetintegeroptional

Minimum: 0

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

Hinweise für die Integration

Für den eigentlichen Export sendest du anschließend die `template_id` zusammen mit genau einer Layoutquelle: `paper_preset_id` oder `paper_layout`.
Die Slot-Liste ist identisch zur Listenansicht und eignet sich für serverseitige Validierung.

curl https://api.namenschild.io/v1/templates/tpl_classic_default \
  -H "Authorization: Bearer ns_live_dein_privater_api_key"

GET/v1/paper-presets

Dieser Endpunkt listet verfügbare Papierpresets mit ihren Layout-Voreinstellungen wie Seitengröße, Rändern, Lücken und Raster.

Scope: templates:read

Typischer Einsatz: zuerst eine gültige `paper_preset_id` für den Export auswählen.
Optionaler Filter: `template_id`.
`paper_layout` beschreibt die Layout-Defaults, `badges_per_page` die Kapazität.

Parameter

template_idstringqueryoptional

Optionaler Filter auf Presets, deren Layout zur Schildgröße einer bestimmten Vorlage passt.

Responses

200Verfügbare Papierpresets für den Account.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

dataarrayerforderlich

401Kein oder ungültiger API-Schlüssel.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

403Schlüssel vorhanden, aber ohne Berechtigung für diesen Endpunkt.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

429Zu viele Requests in kurzer Zeit.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

Retry-Afterintegeroptional

Minimum: 1

X-RateLimit-Remainingintegeroptional

Minimum: 0

X-RateLimit-Resetintegeroptional

Minimum: 0

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

Hinweise für die Integration

Die eigentliche Platzierung im PDF wird deterministisch aus Vorlage und `paper_layout` berechnet.
Systempresets kommen von namensschild.io; private Presets sind nur für den jeweiligen Account sichtbar.

curl "https://api.namenschild.io/v1/paper-presets?template_id=tpl_classic_default" \
  -H "Authorization: Bearer ns_live_dein_privater_api_key"

Beispiel: Papierpreset-Liste

{
  "data": [
    {
      "id": "ppt_badge_80x50_tech_sheet",
      "name": "Technischer A4-Bogen 80x50",
      "description": "A4-Preset für 80x50-mm-Namensschilder.",
      "purchase_url": null,
      "visibility": "system",
      "paper_layout": {
        "sheet": { "width_mm": 210, "height_mm": 297 },
        "margins": { "top_mm": 20, "right_mm": 20, "bottom_mm": 227, "left_mm": 20 },
        "gaps": { "horizontal_mm": 10, "vertical_mm": 0 },
        "grid": { "columns": 2, "rows": 1 },
        "fill_direction": "row_major"
      },
      "badges_per_page": 2,
      "created_at": "2026-06-03T10:00:00.000Z",
      "updated_at": "2026-06-03T10:00:00.000Z"
    }
  ]
}

GET/v1/paper-presets/{id}

Dieser Endpunkt liefert die Detailansicht eines einzelnen Papierpresets inklusive Name, Beschreibung, Kauf-Link und vollständigem `paper_layout`.

Scope: templates:read

Typischer Einsatz: Layoutlogik und technische Maße eines Presets transparent nachvollziehen.
Die Antwort enthält keine Badge-Größe; diese kommt immer aus der Vorlage.
Bei unbekanntem oder nicht verfügbarem Papierpreset liefert der Endpunkt `404`.

Parameter

idstringpatherforderlich

Responses

200Papierpreset-Detailansicht.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

idunbekannterforderlich

nameunbekannterforderlich

descriptionunbekannterforderlich

purchase_urlunbekannterforderlich

visibilityunbekannterforderlich

paper_layoutobjecterforderlich

badges_per_pageunbekannterforderlich

created_atunbekannterforderlich

updated_atunbekannterforderlich

definition_versionintegererforderlich

Minimum: 1

401Kein oder ungültiger API-Schlüssel.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

403Schlüssel vorhanden, aber ohne Berechtigung für diesen Endpunkt.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

404Ressource nicht gefunden.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

429Zu viele Requests in kurzer Zeit.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

Retry-Afterintegeroptional

Minimum: 1

X-RateLimit-Remainingintegeroptional

Minimum: 0

X-RateLimit-Resetintegeroptional

Minimum: 0

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

Hinweise für die Integration

Die konkrete Slot-Platzierung wird aus `paper_layout` und der gewählten Vorlage berechnet.
Für die Exportanfrage genügt später die `paper_preset_id`; alternativ kannst du ein eigenes `paper_layout` direkt senden.

curl https://api.namenschild.io/v1/paper-presets/ppt_badge_80x50_tech_sheet \
  -H "Authorization: Bearer ns_live_dein_privater_api_key"

GET/v1/exports

Dieser Endpunkt listet Exporte des authentifizierten Accounts mit Filtern und Keyset-Cursor-Pagination.

Scope: exports:read

Standardmäßig werden alle Exporte des Accounts in absteigender Zeitreihenfolge geliefert.
Filter verfügbar: `source`, `status`, `template_id`, `paper_preset_id`, `created_after`, `created_before`.
Für die nächste Seite wird `next_cursor` aus der Antwort unverändert wieder an `cursor` übergeben.

Parameter

limitintegerqueryoptional

Minimum: 1 · Maximum: 100 · Standardwert: 20

cursorstringqueryoptional

Opaker Cursor für die nächste Seite.

sourcestringqueryoptional

Werte: app, public_api

statusstringqueryoptional

Werte: pending, processing, ready, failed

template_idstringqueryoptional

paper_preset_idstringqueryoptional

created_afterstringqueryoptional

Format: date-time

created_beforestringqueryoptional

Format: date-time

Responses

200Exportliste für den Account.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

dataarrayerforderlich

next_cursorstring | nullerforderlich

400Pflichtfeld fehlt oder ungültiger Wert.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

401Kein oder ungültiger API-Schlüssel.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

403Schlüssel vorhanden, aber ohne Berechtigung für diesen Endpunkt.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

429Zu viele Requests in kurzer Zeit.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

Retry-Afterintegeroptional

Minimum: 1

X-RateLimit-Remainingintegeroptional

Minimum: 0

X-RateLimit-Resetintegeroptional

Minimum: 0

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

Hinweise für die Integration

`download_available` ist `true`, sobald ein Export fertig ist und erneut heruntergeladen werden kann.
Die Liste liefert bewusst keine Binärdaten. Für Re-Downloads nutzt du `GET /v1/exports/{id}`.

curl "https://api.namenschild.io/v1/exports?source=public_api&status=ready&limit=20" \
  -H "Authorization: Bearer ns_live_dein_privater_api_key"

Beispiel: JSON-Antwort mit next_cursor

{
      "data": [
        {
          "id": "exp_8a0f4f17c56a4dbca28ee935",
          "source": "public_api",
          "status": "ready",
          "template_id": "tpl_classic_default",
          "paper_preset_id": "ppt_badge_80x50_tech_sheet",
          "layout_source": "preset",
          "badge_count": 48,
          "credits_charged": 48,
      "download_available": true,
      "created_at": "2026-06-02T10:00:00.000Z",
      "updated_at": "2026-06-02T10:00:04.000Z",
      "expires_at": "2026-08-01T10:00:04.000Z"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNi0wMlQxMDowMDowMC4wMDBaIiwiaWQiOiJleHBfOGEwZjRmMTdjNTZhNGRiY2EyOGVlOTM1In0"
}

GET/v1/exports/{id}

Über diesen Endpunkt lädst du ein bereits erzeugtes PDF erneut herunter. Verwende dafür die Export-ID aus dem Header von `POST /v1/generate` oder aus `GET /v1/exports`.

Scope: exports:read

Response-Body: `application/pdf`.
Funktioniert nur für Exporte, die bereits erfolgreich erzeugt wurden.
`404` bedeutet entweder unbekannte Export-ID oder noch kein verfügbarer Export.

Parameter

idstringpatherforderlich

Responses

200Vorhandenes Export-PDF.

application/pdf · string

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

401Kein oder ungültiger API-Schlüssel.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

403Schlüssel vorhanden, aber ohne Berechtigung für diesen Endpunkt.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

404Ressource nicht gefunden.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

429Zu viele Requests in kurzer Zeit.

application/json · object

X-Request-Idstringoptional

Korrelation-ID zur Zuordnung von Client-Fehlern, Supabase-Logs und Sentry-Ereignissen.

Format: uuid

Retry-Afterintegeroptional

Minimum: 1

X-RateLimit-Remainingintegeroptional

Minimum: 0

X-RateLimit-Resetintegeroptional

Minimum: 0

typestringerforderlich

messagestringerforderlich

docUrlstringerforderlich

Format: uri

creditsRemainingintegeroptional

Minimum: 0

creditsRequiredintegeroptional

Minimum: 0

Hinweise für die Integration

Der Download verbraucht keine zusätzlichen Credits.
Für wiederholbare Kundendownloads solltest du die Export-ID dauerhaft in deinem System speichern.

curl https://api.namenschild.io/v1/exports/exp_8a0f4f17c56a4dbca28ee935 \
  -H "Authorization: Bearer ns_live_dein_privater_api_key" \
  -o badges.pdf

Beispiel: 404-Fehler

{
  "type": "not_found",
  "message": "Der angeforderte Export wurde nicht gefunden oder ist noch nicht verfügbar.",
  "docUrl": "https://docs.namenschild.io/api#errors"
}

creditsRequiredintegeroptional

Minimum: 0