Vai al contenuto principale
Questo documento introduce un’API di riconoscimento e verifica delle informazioni della carta d’identità, che può convalidare la veridicità e la coerenza del nome e del numero della carta d’identità inserendo un’immagine della carta d’identità o il nome e il numero della carta d’identità. Questa interfaccia è utilizzata per convalidare la veridicità e la coerenza del nome e del numero della carta d’identità; è possibile fornire le informazioni necessarie per la verifica inserendo il nome e il numero della carta d’identità o caricando una foto del lato anteriore della carta d’identità.

​
Processo di richiesta

Per utilizzare l’API, è necessario prima richiedere il servizio corrispondente sulla pagina API di riconoscimento e verifica delle informazioni della carta d’identità; una volta entrati nella pagina, fare clic sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere; dopo aver effettuato il login, si tornerà automaticamente alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare gratuitamente questa API.

​
Utilizzo di base

Per prima cosa, è necessario comprendere il modo di utilizzo di base, che consiste nell’inserire il link dell’immagine della carta d’identità per ottenere il risultato di verifica elaborato; è necessario semplicemente passare un campo image_url, e possiamo quindi compilare il contenuto corrispondente nell’interfaccia, come mostrato nell’immagine:

Si può notare che qui abbiamo impostato le intestazioni della richiesta, tra cui:
  • accept: il formato della risposta desiderata, qui impostato su application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, abbiamo impostato il corpo della richiesta, che include:
  • image_url: il link dell’immagine della carta d’identità da elaborare.
  • encryption: opzionale, parametro di crittografia per campi sensibili (se è necessario inviare dati crittografati).
Dopo aver effettuato la selezione, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” è possibile effettuare un test; come mostrato nell’immagine sopra, abbiamo ottenuto il seguente risultato: 
{
  "result": "0",
  "description": "Nome e numero della carta d'identità corrispondono",
  "name": "Nome sulla carta d'identità",
  "id_card": "Numero della carta d'identità",
  "sex": "Sesso sulla carta d'identità",
  "nation": "Nazionalità sulla carta d'identità",
  "birth": "Data di nascita sulla carta d'identità",
  "address": "Indirizzo sulla carta d'identità"
}
Il risultato restituito contiene diversi campi, descritti come segue:
  • result, codice del risultato di verifica, le condizioni di costo sono le seguenti.
    • Codici di risultato a pagamento:
      • 0: Nome e numero della carta d’identità corrispondono
      • -1: Nome e numero della carta d’identità non corrispondono
    • Codici di risultato non a pagamento:
      • -2: Numero della carta d’identità non valido (lunghezza, cifra di controllo, ecc. non corretti)
      • -3: Nome non valido (lunghezza, formato, ecc. non corretti)
      • -4: Anomalia del servizio del database dei documenti
      • -5: Nessun record di questa carta d’identità nel database
      • -6: Sistema di confronto autoritativo in fase di aggiornamento, riprovare più tardi
      • -7: Numero di verifiche superato il limite giornaliero.
  • description, risultato della verifica tra nome e numero della carta d’identità.
  • name, informazioni sul nome nella carta d’identità; se non è stata caricata l’immagine della carta d’identità, sarà vuoto.
  • id_card, informazioni sul numero della carta d’identità; se non è stata caricata l’immagine della carta d’identità, sarà vuoto.
  • sex, informazioni sul sesso nella carta d’identità; se non è stata caricata l’immagine della carta d’identità, sarà vuoto.
  • nation, informazioni sulla nazionalità nella carta d’identità; se non è stata caricata l’immagine della carta d’identità, sarà vuoto.
  • birth, informazioni sulla data di nascita nella carta d’identità; se non è stata caricata l’immagine della carta d’identità, sarà vuoto.
  • address, informazioni sull’indirizzo nella carta d’identità; se non è stata caricata l’immagine della carta d’identità, sarà vuoto.
Si può notare che le informazioni sul nome e sul numero della carta d’identità sono coerenti e valide, e sono state estratte anche altre informazioni utilizzando la tecnologia OCR e mostrate. Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, ad esempio il codice CURL è il seguente: 
curl -X POST 'https://api.acedata.cloud/identity/idcard/ocr' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": {image_url}
}'
Il codice di integrazione in Python è il seguente: 
import requests

url = "https://api.acedata.cloud/identity/idcard/ocr"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "image_url": {image_url}
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
Verifica delle informazioni personalizzate

Offriamo anche un modo per verificare senza rivelare le informazioni dell’immagine della carta d’identità; è possibile semplicemente inserire il nome name e il numero della carta d’identità id_card per convalidare la veridicità e la coerenza del nome e del numero della carta d’identità; di seguito sono riportate le informazioni specifiche inserite:

Cliccando su “Esegui” si ottiene il seguente risultato: 
{
    "address": "",
    "birth": "",
    "description": "Nome e numero della carta d'identità corrispondono",
    "id_card": "Numero della carta d'identità",
    "name": "Nome sulla carta d'identità",
    "nation": "",
    "result": "0",
    "sex": ""
 }
In questo modo, dal risultato non vengono rivelate altre informazioni riservate, e si può comunque completare la verifica della veridicità e della coerenza del nome e del numero della carta d’identità.

​
Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:
  • 400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
  • 429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.
  • 500 api_error: Errore interno del server, qualcosa è andato storto sul server.

​
Esempio di risposta di errore

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusione

Attraverso questo documento, hai appreso come utilizzare l’API di riconoscimento e verifica delle informazioni della carta d’identità per convalidare la veridicità e la coerenza del nome e del numero della carta d’identità in base all’immagine o alle informazioni fornite. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.