Se connecterEssayer gratuitement
API · v1.0.0

L'API Tarif 595

Créez vos élèves et vos factures Tarif 595 depuis votre site, votre caisse ou votre outil de réservation. Zen595 produit le XML generalInvoice 5.0, le PDF avec QR-facture et le justificatif de remboursement ; vous gardez votre logiciel.

Spécification OpenAPI (JSON)Créer un compte
REST et JSON

Documentée en OpenAPI 3.1 : importez-la dans Postman ou générez votre client.

Erreurs précises

400 : chaque champ en erreur. 422 : la liste exacte de ce qui manque pour le Tarif 595.

Sans doublon

En-tête Idempotency-Key : une requête rejouée ne crée jamais une deuxième facture.

Données en Suisse

Base hébergée en Suisse ; numéros AVS et d'assuré·e chiffrés.

Démarrer en 3 requêtes

Créez une clé dans Paramètres → Clés API (offres Solo et Studio) et envoyez-la dans l'en-tête Authorization. La clé donne accès à un seul compte ; elle n'est montrée qu'une fois.

1. Créer l'élève

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. Émettre la facture

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
  }'

S'il manque une donnée exigée par le Tarif 595, la réponse est 422 avec la liste missing (par exemple participant.insuredId) et rien n'est créé. Ajoutez ?dryRun=1 pour contrôler sans émettre.

3. Récupérer le PDF, ou l'envoyer à l'élève

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 '{}'

Idempotence

Ajoutez un en-tête Idempotency-Key (8 à 255 caractères, unique par opération) à vos requêtes POST. Pendant 24 heures, la même clé avec le même corps renvoie la réponse d'origine (en-tête Idempotent-Replayed: true) sans rien recréer : après une coupure réseau, réessayez sans risque de facture en double. Même clé avec un autre corps : 422. Requête d'origine encore en cours : 409.

Limites et erreurs

  • 120 requêtes par minute et par clé ; au-delà, 429 avec Retry-After.
  • Erreurs en JSON : { "error": "…", "code": "…", "fields": [{ "path": "birthdate", "message": "…" }] }.
  • 402 PLAN_LIMIT : offre Découverte, 10 factures par mois atteintes. 404 : objet inconnu ou d'un autre compte.
  • Chaque réponse porte un X-Request-Id : citez-le si vous écrivez au support.
  • Facture émise : jamais modifiée. Annulez-la, puis émettez la facture corrigée avec cancelsId.

Référence

É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

Réponses : 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).

Réponses : 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_…

Réponses : 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_…

Réponses : 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_…

Réponses : 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).

Réponses : 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

Réponses : 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).

Réponses : 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)

Réponses : 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).

Réponses : 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_…

Réponses : 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_…

Réponses : 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_…

Réponses : 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).

Réponses : 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).

Réponses : 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).

Réponses : 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é.

Réponses : 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)

Réponses : 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).

Schémas complets (corps, réponses) dans la spécification OpenAPI. Une question, une intégration à faire ? contact@zen595.ch