Sapere · Tecnica

Emettere documenti dal vostro sistema

Il collegamento tramite l’interfaccia REST: accesso, procedura, casi di errore e revoca, con esempi da riprodurre.

3 min di lettura·Per il vostro reparto informatico e il vostro partner software

Quando i documenti nascono regolarmente, all’arrivo di una collaboratrice o per ogni contrassegno autorizzato, nessuno dovrebbe emetterli a mano. Se ne occupa il vostro sistema HR, CRM o gestionale tramite l’interfaccia REST di VeriGate.

Cosa può fare l’interfaccia

Consultare i dati di un tipo di documento: quali esistono e quali sono obbligatori.
Creare un’offerta: VeriGate risponde con un link che la persona apre con la swiyu Wallet.
Consultare lo stato di un’offerta: aperta, ritirata, scaduta.
Elencare i documenti emessi, sospenderli, riattivarli e revocarli.

Tutto ciò che la console fa per emettere è così a disposizione anche del vostro sistema. La creazione resta nella console.

L’accesso: uno per tipo di documento

Il vostro sistema riceve un accesso tecnico secondo OAuth 2.0 (Client Credentials). Vale per un solo tipo di documento della vostra organizzazione. Un sistema HR che emette tesserini identificativi non può quindi emettere autorizzazioni di accesso, nemmeno per errore.

Ogni chiamata viene protocollata con l’accesso che l’ha effettuata. I valori dei dati non compaiono nel protocollo.

La procedura in quattro chiamate

Gli esempi usano l’organizzazione valmodello e il tipo di documento contrassegno. Ricevete i vostri identificativi con l’accesso.

1. Ottenere un token

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

2. Creare un’offerta

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

{ "claims": { "given_name": "Marco",
              "family_name": "Rossi",
              "zona": "B",
              "targa": "TI 482 117",
              "valid_until": "2027-12-31" } }

La risposta contiene l’identificativo dell’offerta, il link per il wallet e la durata di validità dell’offerta:

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

Inviate il link per e-mail o lo mostrate come codice QR nel vostro portale.

3. Consultare lo stato

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

OFFERED significa: non ancora ritirata. Con ISSUED il documento è nel wallet, e la risposta indica il suo identificativo credentialRef. EXPIRED e FAILED chiudono l’offerta; una nuova è possibile in ogni momento.

4. Revocare quando non è più valido

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

SUSPENDED sospende temporaneamente, VALID riattiva un documento sospeso. Un documento revocato resta revocato.

Pensata per le ripetizioni

Le reti si interrompono, le chiamate vanno in timeout e il vostro sistema riprova. Per questo la creazione di un’offerta richiede un Idempotency-Key, ad esempio il numero della domanda. Se la stessa chiave arriva due volte, il vostro sistema riceve l’offerta già creata invece di generarne una seconda. Se la stessa chiave arriva con altri dati, VeriGate rifiuta con 409, invece di scartare in silenzio una delle due versioni.

Ogni accesso ha un contingente: 60 chiamate in scrittura e 600 in lettura al minuto. Se viene superato, VeriGate risponde con 429 e indica in Retry-After quando riprendere.

Descrizione e test

L’interfaccia è interamente descritta in OpenAPI. Il vostro partner software può generarne il codice e sviluppare con un’organizzazione di test prima che vengano emessi documenti reali.

Cosa viene dopo

Emissione, stato, revocaTutto ciò che è in questo articolo.
Disponibile
Avviare verifiche e procedure dal vostro sistemaAd esempio «Verificare l’e-ID, poi emettere» dal vostro portale, senza console.
Previsto

Parlare del collegamento