Savoir · Technique

Émettre des documents depuis votre système

L’intégration par l’interface REST : accès, déroulement, cas d’erreur et révocation, avec des exemples à reproduire.

3 min de lecture·Pour votre informatique et votre partenaire logiciel

Lorsque des documents sont créés régulièrement, à l’arrivée d’une collaboratrice ou pour chaque macaron autorisé, personne ne devrait les émettre à la main. Votre système RH, CRM ou métier s’en charge par l’interface REST de VeriGate.

Ce que permet l’interface

Consulter les données d’un type de document : lesquelles existent et lesquelles sont obligatoires.
Créer une offre : VeriGate répond avec un lien que la personne ouvre avec le swiyu Wallet.
Consulter l’état d’une offre : ouverte, retirée, échue.
Lister les documents émis, les suspendre, les réactiver et les révoquer.

Tout ce que fait la console pour émettre est ainsi aussi à la disposition de votre système. La conception reste dans la console.

L’accès : un par type de document

Votre système reçoit un accès technique selon OAuth 2.0 (Client Credentials). Il est valable pour un seul type de document de votre organisation. Un système RH qui émet des cartes de légitimation ne peut donc pas émettre d’autorisations d’accès, même par erreur.

Chaque appel est journalisé avec l’accès qui l’a effectué. Les valeurs des données ne figurent pas dans le journal.

Le déroulement en quatre appels

Les exemples utilisent l’organisation valmodele et le type de document macaron. Vous recevez vos propres identifiants avec l’accès.

1. Obtenir un jeton

POST https://id.verigate.ch/realms/verigate-providers/protocol/openid-connect/token
grant_type=client_credentials
client_id=…
client_secret=…

2. Créer une offre

POST https://api.verigate.ch/api/provider/v1/tenants/valmodele/credential-types/macaron/offers
Authorization: Bearer …
Idempotency-Key: 4711

{ "claims": { "given_name": "Marc",
              "family_name": "Rochat",
              "zone": "B",
              "plaque": "VD 482 117",
              "valid_until": "2027-12-31" } }

La réponse contient l’identifiant de l’offre, le lien pour le wallet et la durée de validité de l’offre :

{ "requestId": "8f3c…",
  "state": "OFFERED",
  "offerDeeplink": "swiyu://…",
  "expiresAt": "2026-10-28T09:15:00Z" }

Vous envoyez le lien par e-mail ou vous l’affichez comme code QR dans votre propre portail.

3. Consulter l’état

GET …/credential-types/macaron/offers/8f3c…

OFFERED signifie : pas encore retirée. Avec ISSUED, le document est dans le wallet, et la réponse indique son identifiant credentialRef. EXPIRED et FAILED clôturent l’offre ; une nouvelle est possible à tout moment.

4. Révoquer lorsqu’il n’est plus valable

POST …/credential-types/macaron/credentials/{credentialRef}/state
{ "state": "REVOKED" }

SUSPENDED suspend temporairement, VALID réactive un document suspendu. Un document révoqué le reste.

Conçu pour les répétitions

Les réseaux tombent en panne, des appels dépassent le délai, et votre système réessaie. C’est pourquoi la création d’une offre exige un Idempotency-Key, par exemple le numéro de la demande. Si la même clé arrive deux fois, votre système reçoit l’offre déjà créée au lieu d’en générer une deuxième. Si la même clé arrive avec d’autres données, VeriGate refuse avec 409, au lieu d’écarter l’une des deux versions sans le dire.

Chaque accès a un contingent : 60 appels en écriture et 600 en lecture par minute. S’il est dépassé, VeriGate répond avec 429 et indique dans Retry-After quand reprendre.

Description et test

L’interface est entièrement décrite en OpenAPI. Votre partenaire logiciel peut en générer du code et développer avec une organisation de test avant que de vrais documents soient émis.

Ce qui vient ensuite

Émission, état, révocationTout ce qui figure dans cet article.
Disponible
Lancer des vérifications et des déroulements depuis votre systèmePar exemple « Vérifier l’e-ID, puis émettre » depuis votre portail, sans console.
Prévu

Parler de l’intégration