AnmeldenGratis testen
API · v1.0.0

Die API für den Tarif 595

Erfassen Sie Teilnehmende und Tarif-595-Rechnungen aus Ihrer Website, Ihrer Kasse oder Ihrem Buchungstool. Zen595 erzeugt das XML generalInvoice 5.0, das PDF mit QR-Rechnung und den Rückforderungsbeleg; Sie behalten Ihre Software.

OpenAPI-Spezifikation (JSON)Konto eröffnen
REST und JSON

Dokumentiert in OpenAPI 3.1: In Postman importieren oder Ihren Client generieren.

Präzise Fehler

400: jedes fehlerhafte Feld. 422: die genaue Liste dessen, was für den Tarif 595 fehlt.

Keine Doppelten

Header Idempotency-Key: Eine wiederholte Anfrage erzeugt nie eine zweite Rechnung.

Daten in der Schweiz

Datenbank in der Schweiz; AHV- und Versichertennummern verschlüsselt.

In 3 Anfragen starten

Erstellen Sie einen Schlüssel unter Einstellungen → API-Schlüssel (Angebote Solo und Studio) und senden Sie ihn im Header Authorization. Der Schlüssel gibt Zugriff auf ein einziges Konto; er wird nur einmal angezeigt.

1. Teilnehmer:in erfassen

curl https://api.zen595.ch/v1/participants \
  -H "Authorization: Bearer z595_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: eleve-4711" \
  -d '{
    "familyName": "Fontaine", "givenName": "Léa", "sex": "female",
    "birthdate": "1988-05-14", "zip": "1260", "city": "Nyon",
    "insurerId": "<id de GET /v1/insurers>", "insuredId": "80756123",
    "email": "lea@example.ch", "externalRef": "4711"
  }'

2. Rechnung ausstellen

curl https://api.zen595.ch/v1/invoices \
  -H "Authorization: Bearer z595_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: facture-4711-2027-T1" \
  -d '{
    "participantId": "par_…",
    "lines": [{ "serviceId": "svc_…", "quantity": 3, "amount": 390,
                "dateBegin": "2027-01-05", "dateEnd": "2027-03-30" }],
    "prepaid": true
  }'

Fehlt eine vom Tarif 595 verlangte Angabe, lautet die Antwort 422 mit der Liste missing (zum Beispiel participant.insuredId) und es wird nichts erstellt. Fügen Sie ?dryRun=1 hinzu, um zu prüfen, ohne auszustellen.

3. PDF abrufen oder an die Teilnehmerin / den Teilnehmer senden

curl -o facture.pdf https://api.zen595.ch/v1/invoices/inv_…/pdf -H "Authorization: Bearer z595_live_…"
curl -o facture.xml https://api.zen595.ch/v1/invoices/inv_…/xml -H "Authorization: Bearer z595_live_…"

curl -X POST https://api.zen595.ch/v1/invoices/inv_…/send -H "Authorization: Bearer z595_live_…" \
  -H "Content-Type: application/json" -d '{}'

Idempotenz

Fügen Sie Ihren Anfragen einen Header Idempotency-Key (8 bis 255 Zeichen, eindeutig pro Vorgang) hinzu POST. Während 24 Stunden liefert derselbe Schlüssel mit demselben Inhalt die ursprüngliche Antwort zurück (Header Idempotent-Replayed: true), ohne etwas neu zu erstellen: Nach einem Netzwerkunterbruch können Sie gefahrlos erneut senden, ohne doppelte Rechnung. Gleicher Schlüssel mit anderem Inhalt: 422. Ursprüngliche Anfrage noch in Bearbeitung: 409.

Limiten und Fehler

  • 120 Anfragen pro Minute und Schlüssel; darüber 429 avec Retry-After.
  • Fehler als JSON: { "error": "…", "code": "…", "fields": [{ "path": "birthdate", "message": "…" }] }.
  • 402 PLAN_LIMIT : Angebot «Einstieg», 10 Rechnungen pro Monat erreicht. 404 : unbekanntes Objekt oder eines anderen Kontos.
  • Jede Antwort enthält eine X-Request-Id : Geben Sie sie an, wenn Sie dem Support schreiben.
  • Ausgestellte Rechnung: wird nie geändert. Stornieren Sie sie und stellen Sie die korrigierte Rechnung aus mit cancelsId.

Referenz

Élèves

Les personnes facturées (patients au sens du XML 5.0).

get/v1/participantsLister les élèves
  • q (query) : Recherche nom, prénom, e-mail

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

post/v1/participantsCréer un élève
  • Idempotency-Key (header) : Rejouer la requête sans doublon pendant 24 h (recommandé pour toute création).

Antworten: 201 Créé · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

get/v1/participants/{id}Lire un élève
  • id (path) : par_…

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 404 Introuvable · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

patch/v1/participants/{id}Modifier un élève
  • id (path) : par_…

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

delete/v1/participants/{id}Archiver un élève

Ses factures restent consultables.

  • id (path) : par_…

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

post/v1/participants/importImporter des élèves en masse

Jusqu'à 2000 lignes. Dates en YYYY-MM-DD ou JJ.MM.AAAA, sexe F/M, caisse par nom (insurerName) ou GLN (insurerGln). Avec ?dryRun=1, contrôle sans enregistrer. Une ligne dont externalRef existe déjà met la fiche à jour.

  • dryRun (query)
  • Idempotency-Key (header) : Rejouer la requête sans doublon pendant 24 h (recommandé pour toute création).

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

Prestations

Vos cours ou abonnements, chacun avec sa position du Tarif 595 et son prix.

get/v1/servicesLister les prestations

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

post/v1/servicesCréer une prestation

L'unité (séance ou mois) est déduite de la position.

  • Idempotency-Key (header) : Rejouer la requête sans doublon pendant 24 h (recommandé pour toute création).

Antworten: 201 Créée · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

Factures

Émission, PDF, XML, envoi par e-mail, annulation.

get/v1/invoicesLister les factures
  • status (query)
  • participantId (query)
  • before (query) : Pagination : issuedAt de la dernière facture reçue
  • limit (query)

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

post/v1/invoicesÉmettre une facture

Contrôle complet avant émission : s'il manque une donnée exigée par le Tarif 595, réponse 422 avec la liste missing (rien n'est créé). Avec ?dryRun=1, contrôle seulement. Numérotation continue par compte.

  • dryRun (query)
  • Idempotency-Key (header) : Rejouer la requête sans doublon pendant 24 h (recommandé pour toute création).

Antworten: 201 Émise · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 402 Offre Découverte : 10 factures par mois atteintes (code PLAN_LIMIT). · 422 Données manquantes pour le Tarif 595 · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

get/v1/invoices/{id}Lire une facture
  • id (path) : inv_…

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 404 Introuvable · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

get/v1/invoices/{id}/pdfPDF de la facture

Facture avec QR-facture, justificatif de remboursement et feuille de codes QR. Régénéré à l'identique et vérifié contre l'empreinte du XML.

  • id (path) : inv_…

Antworten: 200 PDF · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

get/v1/invoices/{id}/xmlXML generalInvoice 5.0
  • id (path) : inv_…

Antworten: 200 XML · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

post/v1/invoices/{id}/sendEnvoyer la facture à l'élève par e-mail

PDF en pièce jointe, au nom de votre studio ; les réponses arrivent sur votre e-mail.

  • id (path) : inv_…
  • Idempotency-Key (header) : Rejouer la requête sans doublon pendant 24 h (recommandé pour toute création).

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 409 Facture annulée · 422 Pas d'adresse e-mail (code NO_EMAIL) · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

post/v1/invoices/{id}/cancelAnnuler une facture

Une facture émise ne se modifie pas : annulez-la, puis émettez la facture corrigée avec cancelsId.

  • id (path) : inv_…
  • Idempotency-Key (header) : Rejouer la requête sans doublon pendant 24 h (recommandé pour toute création).

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

Cours

Facturer tous les élèves d'un cours en une requête.

post/v1/courses/{id}/invoicesFacturer les élèves d'un cours

Une facture par élève (100 au plus par requête). Les élèves déjà facturés pour ce cours sont ignorés ; un élève incomplet est signalé sans bloquer les autres. ?dryRun=1 pour contrôler.

  • id (path) : crs_…
  • dryRun (query)
  • Idempotency-Key (header) : Rejouer la requête sans doublon pendant 24 h (recommandé pour toute création).

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

Référentiels

Positions du Tarif 595 et caisses (sans authentification).

get/v1/positionsPositions du Tarif 595

Catalogue officiel (FR, DE, IT) avec dates de validité.

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

get/v1/insurersCaisses (liste MediData)

Antworten: 200 OK · 400 Corps invalide : fields liste les champs en erreur. · 401 Clé API absente ou invalide. · 429 Plus de 120 requêtes par minute pour cette clé (en-tête Retry-After).

Vollständige Schemas (Inhalte, Antworten) in der OpenAPI-Spezifikation. Eine Frage oder eine Integration geplant? contact@zen595.ch