CyfroPass
Loslegen

Doku

Öffentliche API

Automatisieren Sie Ihre Digitalen Produktpässe: Produkte anlegen und aktualisieren, Pässe veröffentlichen, Templates lesen und Kataloge importieren — über eine einfache REST-API. Authentifizierung per API-Schlüssel.

OpenAPI-Spezifikation herunterladen Endpunkt-Referenz

Plan-Voraussetzung

Die API ist in jedem Plan verfügbar, auch Free — die Stufen unterscheiden sich durch das Tageskontingent, nicht durch den Zugang. Jede Anfrage prüft Ihr aktuelles Entitlement erneut.

Basis-URL

Alle Endpunkte werden unter dem Präfix /v1 auf Ihrer CyfroPass-Domain bereitgestellt.

https://<your-domain>/v1

Authentifizierung

Erstellen Sie einen Schlüssel als Owner unter Einstellungen → API-Schlüssel. Senden Sie ihn als Bearer-Token oder im Header X-API-Key. Der Rohschlüssel wird nur einmal angezeigt.

Authorization: Bearer cp_live_…
X-API-Key: cp_live_…

Rate-Limits

Die Durchsetzung ist ein Tageskontingent (UTC), getrennt in Schreibvorgänge/Tag (POST/PATCH/PUT/DELETE) und Passport-Lesevorgänge/Tag (GET). Free: 100 Schreib- + 100 Lesevorgänge/Tag; Starter: 1.000 Schreibvorgänge/Tag, unbegrenzt Lesen; Business & Scale: unbegrenzt. Beim Erreichen des Limits kommt 429 mit einer Tageslimit-Meldung; das Fenster wird um 00:00 UTC zurückgesetzt. Senden Sie bei Schreibvorgängen einen Idempotency-Key-Header, um sicher zu wiederholen — die erste Antwort wird 24 Stunden lang erneut ausgeliefert.

Fehler-Format

Jeder Fehler nutzt ein einheitliches JSON-Format mit einem stabilen, maschinenlesbaren Code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

Referenz

Endpunkte

Products

Manage the product catalogue (SKUs) and the documents attached to each product.

GET /products List products (paginated, filterable).
POST /products Create a product from a template version.
GET /products/{id} Fetch one product.
PATCH /products/{id} Update mutable fields; data is merged.
DELETE /products/{id} Delete a draft product. (409 if published)
GET /products/{id}/documents List a product's documents.
POST /products/{id}/documents Upload a document (multipart, ≤ 25 MiB).
GET /products/{id}/documents/{docID} Download a document.
DELETE /products/{id}/documents/{docID} Delete a document. 
curl https://app.passflow.example/v1/products \
  -H "Authorization: Bearer cp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Passports

Publish, re-publish and archive passports, and read their immutable version history. Passport routes are keyed by product id.

GET /passports/products/{productID} Current passport (with snapshot).
POST /passports/products/{productID}/publish Publish or re-publish. (422 on validation failure)
POST /passports/products/{productID}/archive Archive the current passport.
GET /passports/products/{productID}/versions Version history (metadata).
GET /passports/products/{productID}/versions/{version} One version's snapshot. 
curl -X POST \
  https://app.passflow.example/v1/passports/products/PRODUCT_ID/publish \
  -H "Authorization: Bearer cp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Templates

Read the platform-provided, versioned product-group templates and validate product data against them. Templates are read-only over the API.

GET /templates List templates and their versions.
GET /templates/field-types The generic field-type registry.
GET /templates/{id} List versions of one template.
GET /templates/{id}/{version} Full template document (sections, fields).
POST /templates/{id}/{version}/validate Validate data against a version.
GET /templates/{id}/diff Diff two versions (from, to). 
curl https://app.passflow.example/v1/templates/textile/2026-draft-1 \
  -H "Authorization: Bearer cp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Import

Bulk-import products from a CSV file or a connected Shopify / WooCommerce / PrestaShop store. Every fetch becomes an import job with the same map → validate → execute lifecycle.

POST /import/upload Upload a CSV (multipart, ≤ 10 MB).
POST /import/sources/test Test a store connector.
POST /import/sources/fetch Fetch a store catalogue into a job.
POST /import/{job}/mapping-suggest Suggest a column → field mapping.
POST /import/{job}/validate Validate mapped rows (no products created).
POST /import/{job}/execute Create products from valid rows. (idempotent)
GET /import/{job} Get import job status. 
curl -X POST https://app.passflow.example/v1/import/upload \
  -H "Authorization: Bearer cp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@products.csv"

Die vollständige, maschinenlesbare Spezifikation gibt es als openapi.yaml.