Vai al contenuto principale
POST
curl
L’endpoint Create a Bank Link avvia un’esecuzione di Bank Link sul tuo server, per collegare una banca o rinnovare una connessione, e restituisce l’url ospitato. Ogni campo ha un valore predefinito, quindi la richiesta più semplice è {} più ciò che ti serve. Conserva l’id restituito associato al tuo utente e verifica tu stesso l’esito con Ottieni un link bancario oppure con il webhook bank.link.completed. Vedi la guida rapida e Bank Link.

Autorizzazioni

x-api-key
string
header
obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere ambiti limitati: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o solo alle sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 significa che la chiave è errata, revocata o scaduta; 403 significa che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo esterno alla sua lista IP; 404 su una route di sessione significa che la sessione è al di fuori dei workflow o degli stati consentiti alla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permesso di scrittura sulle sessioni riceve i link e i token delle sessioni come null. Vedi https://docs.didit.me/console/api-keys.

Intestazioni

Idempotency-Key
string

Chiave facoltativa per la sicurezza dei nuovi tentativi, da scegliere per una singola operazione, fino a 255 caratteri (va bene un UUID). Una richiesta ripetuta con la stessa chiave, lo stesso endpoint, la stessa query e lo stesso body riceve la prima risposta, con lo stesso status e lo stesso body, e non viene eseguita né fatturata una seconda volta. Con la stessa chiave ma un altro endpoint, query o body viene restituito 409 idempotency_key_reused; mentre la prima richiesta è ancora in esecuzione, viene restituito 409 idempotency_key_in_progress con Retry-After. Una richiesta non riuscita (qualsiasi 4xx o 5xx) non viene memorizzata, quindi puoi inviarla di nuovo con la stessa chiave. Le chiavi appartengono alla tua applicazione, sia che tu chiami con una chiave API sia con un token di accesso. Vedi Nuovi tentativi e idempotenza.

Required string length: 1 - 255

Corpo

application/json

Crea un Bank Link. La richiesta minima è {} più ciò che vuoi: ogni campo ha un valore predefinito.

mode
enum<string>
predefinito:connect

connect (predefinito) crea una nuova connessione. renew richiede connection_id e riutilizza le impostazioni di quella connessione.

Opzioni disponibili:
connect,
renew
connection_id
string<uuid>

La connessione da rinnovare. Solo con mode: renew.

access
enum<string>
predefinito:one_time

one_time (predefinito) legge i dati una sola volta. ongoing mantiene aperto l'accesso finché il consenso non termina o qualcuno non lo interrompe. Con institution_id impostato, una banca che non può mantenere aperto l'accesso restituisce 400 ongoing_access_not_available prima di qualsiasi schermata. Senza di esso, il selettore delle banche elenca solo quelle che lo consentono.

Opzioni disponibili:
one_time,
ongoing
country
string

Facoltativo. Senza questo campo, la persona sceglie tra i paesi abilitati nella tua applicazione. Deve essere un paese servito da Bank Link; qualsiasi altro, incluso ZZZ, restituisce 400 invalid_request con field: country. Un corpo di richiesta vuoto resta valido.

Pattern: ^[A-Z]{3}$
institution_id
string

Banca facoltativa da preselezionare, da list_institutions. Salta il selettore.

Maximum string length: 64
segment
enum<string>
predefinito:any

Filtra il selettore e indica alla banca quale accesso aprire nei casi in cui la banca li distingue. Predefinito any.

Opzioni disponibili:
personal,
business,
any
data
enum<string>[]

Cosa leggere. accounts è sempre incluso: nome, tipo, valuta, identificativi e nome del titolare, dove la banca lo condivide. Predefinito ["accounts"].

Maximum array length: 3
Opzioni disponibili:
accounts,
balances,
transactions
history_days
integer
predefinito:90

Giorni di storico delle transazioni da richiedere, da 1 a 365, con valore predefinito 90. La banca potrebbe fornirne meno: ogni conto riporta in history_coverage quanto ha effettivamente fornito. Non può essere inviato insieme a history_from.

Intervallo richiesto: 1 <= x <= 365
history_from
string<date>

Data di inizio della cronologia da richiedere, al posto di history_days. Non può essere inviata insieme a history_days: l'invio di entrambi i parametri risponde 400 history_window_ambiguous. Una data più vecchia di 365 giorni, o futura, risponde 400 window_not_available.

extended_history
enum<string>
predefinito:standard

allow_extra_auth consente a una banca che chiede un'ulteriore conferma di rilasciare lo storico più datato.

Opzioni disponibili:
standard,
allow_extra_auth

Solo per accesso continuo. Quanti giorni chiedere alla banca di mantenere aperto l'accesso, 1 o più. Predefinito: il periodo più lungo consentito dalla banca. La connessione riporta in consent.expires_at la data che la banca ha effettivamente concessa. Con access: one_time restituisce 400 invalid_request con field: consent_days.

Intervallo richiesto: 1 <= x <= 32767
ownership
object

Confronto facoltativo del titolare del conto con una persona o un'azienda.

end_user
object

La persona o l'azienda che collega il conto.

redirect_url
string<uri>

Dove va il browser alla fine, con link_id, status e uno state firmato (solo per la visualizzazione: il webhook e get_link sono quelli autorevoli). In un'applicazione sandbox un indirizzo http semplice di localhost, 127.0.0.1 o [::1] (qualsiasi porta e percorso, senza credenziali, senza frammento) non richiede registrazione. Qualsiasi altro indirizzo restituisce 400 redirect_url_not_registered: la registrazione di altri indirizzi non è ancora disponibile. Senza redirect_url la persona termina sulla pagina dei risultati di Didit.

Maximum string length: 2048
allowed_origins
string<uri>[]

Accettato ma non usato oggi: riservato alla Bank Link integrata di Didit, che non è ancora disponibile. Origini HTTPS, fino a 50.

Maximum array length: 50
language
string

Codice lingua facoltativo, come es o pt-BR. In assenza, viene usata la lingua del browser.

Maximum string length: 16
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
vendor_data
string

Il tuo riferimento, restituito nel link e nella connessione.

Maximum string length: 255
expires_in
integer
predefinito:3600

Durata del link in secondi, da 300 a 86400. Predefinita: 3600.

Intervallo richiesto: 300 <= x <= 86400
duplicates
enum<string>
predefinito:reuse

reuse (predefinito) completa un link che rimanda a conti già condivisi come rinnovo di quella connessione. allow crea una seconda connessione indipendente.

Opzioni disponibili:
reuse,
allow
allow_one_time_fallback
boolean
predefinito:false

Con ongoing, consente alla persona di proseguire con una lettura una tantum presso una banca che non può mantenere aperto l'accesso, dopo aver confermato l'accesso ridotto nella propria schermata. Il preventivo mostra quanto costa. Solo con access: ongoing: con accesso una tantum restituisce 400 invalid_request con field: allow_one_time_fallback.

accept_reduced_grant
boolean
predefinito:false

Quando la banca o la persona concede meno di quanto richiesto, completa il link e addebita solo gli ambiti concessi. Altrimenti il link termina con failed e reduced_grant e non viene addebitato nulla.

sandbox
object

Solo per le applicazioni sandbox: seleziona il cliente Didit Test Bank. Viene ignorato in un'applicazione in produzione.

Risposta

Il link è stato creato.

Un'esecuzione di Bank Link per una persona: collega una banca oppure rinnova una connessione. Conferma tu stesso un link con get_link: non fidarti mai di un id inviato dal browser.

id
string<uuid>
obbligatorio

Identificativo del link.

mode
enum<string>
obbligatorio
Opzioni disponibili:
connect,
renew
access
enum<string>
obbligatorio
Opzioni disponibili:
one_time,
ongoing
status
enum<string>
obbligatorio

Stato del link. completed, cancelled, expired e failed sono stati definitivi.

Opzioni disponibili:
created,
opened,
connecting,
completed,
cancelled,
expired,
failed
url
string<uri> | null
obbligatorio

La pagina ospitata a cui inviare la persona. Restituita solo alla creazione del link; null nelle letture successive, perché il token non viene memorizzato.

client_token
string | null
obbligatorio

Il token per il Bank Link incorporato di Didit, che non è ancora disponibile: apri url oggi. Viene restituito solo alla creazione del link; null nelle letture successive. Ha uno scopo unico e una validità breve. Non contiene dati personali. Non registrarlo mai nei log.

expires_at
string<date-time>
obbligatorio

Quando un link non riscattato smette di funzionare.

connection_id
string<uuid> | null
obbligatorio

La connessione creata o rinnovata da questo link, quando status è completed.

check_id
string<uuid> | null
obbligatorio

L'esito dell'assetto proprietario di questo link, quando ha richiesto ownership.compare diverso da none.

reused
boolean
obbligatorio

true quando il link è stato completato come rinnovo di una connessione esistente, perché la persona condivide già esattamente questi conti (duplicates: reuse). Nessun importo viene addebitato due volte.

error
object | null
obbligatorio

Perché il link non è riuscito, quando status è failed. Altrimenti null.

quote
object
obbligatorio

Il prezzo di un link, fissato al momento della creazione. Il costo addebitato è quello del preventivo. Le letture non addebitano nulla.

vendor_data
string | null
obbligatorio

Il tuo riferimento della richiesta.

Ultima modifica il 22 novembre 2026