Saltar al contingut principal
POST
curl
L’endpoint Create a Bank Link de Didit inicia una execució de Bank Link al teu servidor, per connectar un banc o renovar una connexió, i retorna la url allotjada. Tots els camps tenen un valor per defecte, de manera que la sol·licitud més senzilla és {} més el que vulguis. Guarda l’id retornat amb el teu usuari i confirma tu mateix el resultat amb Obtén un enllaç bancari o amb el webhook bank.link.completed. Consulta l’inici ràpid i Bank Link.

Autoritzacions

x-api-key
string
header
requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau principal té accés complet. Una clau amb nom es pot limitar: cap, lectura o escriptura per recurs, limitada a alguns fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 vol dir que la clau és incorrecta, revocada o caducada; 403 vol dir que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud ve d'una adreça fora de la seva llista d'adreces IP; 404 en una ruta de sessió vol dir que la sessió queda fora dels fluxos de treball o estats de la clau. Una clau sense accés a multimèdia rep les URL d'imatges, vídeos i PDF com a null, i una clau sense escriptura de sessions rep els enllaços i els tokens de sessió com a null. Vegeu https://docs.didit.me/console/api-keys.

Capçaleres

Idempotency-Key
string

Clau opcional de seguretat per a reintents que tu tries per a una operació, de fins a 255 caràcters (un UUID funciona). Una sol·licitud repetida amb la mateixa clau, endpoint, consulta i cos rep la primera resposta, amb el mateix codi d'estat i el mateix cos, i no s'executa ni es factura una segona vegada. La mateixa clau amb un altre endpoint, consulta o cos retorna 409 idempotency_key_reused, i mentre la primera sol·licitud encara s'està processant, 409 idempotency_key_in_progress amb Retry-After. Una sol·licitud fallida (qualsevol 4xx o 5xx) no s'emmagatzema, de manera que pots tornar-la a enviar amb la mateixa clau. Les claus pertanyen a la teva aplicació, tant si crides amb una clau d'API com amb un token d'accés. Consulta Reintents i idempotència.

Required string length: 1 - 255

Cos

application/json

Crea un enllaç bancari. La sol·licitud més petita és {} més el que vulguis: tots els camps tenen un valor per defecte.

mode
enum<string>
predeterminat:connect

connect (per defecte) crea una connexió nova. renew necessita connection_id i reutilitza la configuració d'aquella connexió.

Opcions disponibles:
connect,
renew
connection_id
string<uuid>

La connexió que cal renovar. Només amb mode: renew.

access
enum<string>
predeterminat:one_time

one_time (per defecte) llegeix les dades una sola vegada. ongoing manté l'accés obert fins que acaba el consentiment o algú el para. Amb institution_id definit, un banc que no pot mantenir l'accés obert respon 400 ongoing_access_not_available abans de cap pantalla. Sense ell, el selector de bancs només mostra els bancs que ho poden fer.

Opcions disponibles:
one_time,
ongoing
country
string

Opcional. Sense aquest camp, la persona tria entre els països que la teva aplicació ha habilitat. Ha de ser un país que Bank Link atengui; qualsevol altre, inclòs ZZZ, respon 400 invalid_request amb field: country. Un cos de sol·licitud buit continua sent vàlid.

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

Banc opcional per preseleccionar, de list_institutions. Omet el selector.

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

Filtra el selector i indica al banc quin inici de sessió ha d'obrir allà on el banc els separa. Per defecte, any.

Opcions disponibles:
personal,
business,
any
data
enum<string>[]

Què llegir. accounts sempre s'inclou: nom, tipus, moneda, identificadors i el nom del titular si el banc el comparteix. Per defecte ["accounts"].

Maximum array length: 3
Opcions disponibles:
accounts,
balances,
transactions
history_days
integer
predeterminat:90

Dies d'historial de transaccions que es demanen, d'1 a 365, per defecte 90. El banc pot entregar menys: cada compte indica el que ha entregat a history_coverage. No es pot enviar juntament amb history_from.

Rang requerit: 1 <= x <= 365
history_from
string<date>

Data d'inici de l'historial que cal sol·licitar, en lloc de history_days. No es pot enviar juntament amb history_days: si s'envien totes dues, la resposta és 400 history_window_ambiguous. Una data anterior a 365 dies, o futura, respon 400 window_not_available.

extended_history
enum<string>
predeterminat:standard

allow_extra_auth permet que un banc que demana una confirmació addicional alliberi l'historial més antic.

Opcions disponibles:
standard,
allow_extra_auth

Només per a accés continu. Nombre de dies que cal demanar al banc que mantingui l'accés obert, 1 o més. Per defecte: el màxim que permet el banc. La connexió informa de la data que el banc ha concedit realment a consent.expires_at. Amb access: one_time respon 400 invalid_request amb field: consent_days.

Rang requerit: 1 <= x <= 32767
ownership
object

Comparació opcional del titular del compte amb una persona o una empresa.

end_user
object

La persona o l'empresa que connecta el compte.

redirect_url
string<uri>

On va el navegador al final, amb link_id, status i un state signat (només per mostrar: el webhook i get_link són les fonts autoritatives). En una aplicació de sandbox, una adreça http simple de localhost, 127.0.0.1 o [::1] (qualsevol port i camí, sense credencials ni fragment) no necessita registre. Qualsevol altra adreça respon 400 redirect_url_not_registered: encara no està disponible el registre d'altres adreces. Sense redirect_url, la persona acaba a la pàgina de resultats pròpia de Didit.

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

Acceptat però no utilitzat avui: reservat per al Bank Link integrat de Didit, que encara no s'ha publicat. Orígens HTTPS, fins a 50.

Maximum array length: 50
language
string

Codi d'idioma opcional, com es o pt-BR. Si no, s'usa l'idioma del navegador.

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

La vostra referència pròpia, retornada a l'enllaç i a la connexió.

Maximum string length: 255
expires_in
integer
predeterminat:3600

Durada de vida de l'enllaç en segons, de 300 a 86400. Per defecte, 3600.

Rang requerit: 300 <= x <= 86400
duplicates
enum<string>
predeterminat:reuse

reuse (per defecte) completa un enllaç que es resol amb comptes que ja comparteixes com una renovació d'aquesta connexió. allow crea una segona connexió independent.

Opcions disponibles:
reuse,
allow
allow_one_time_fallback
boolean
predeterminat:false

Amb ongoing, permet que la persona continuï amb una lectura única en un banc que no pot mantenir l'accés obert, després de confirmar l'accés reduït a la seva pròpia pantalla. El pressupost mostra el cost. Només amb access: ongoing: amb accés d'un sol ús respon 400 invalid_request amb field: allow_one_time_fallback.

accept_reduced_grant
boolean
predeterminat:false

Quan el banc o la persona concedeixen menys del que has sol·licitat, completa l'enllaç i cobra només els àmbits concedits. En cas contrari, l'enllaç acaba com a failed amb reduced_grant i no es cobra res.

sandbox
object

Només per a aplicacions de sandbox: tria el client de Didit Test Bank. S'ignora en una aplicació en producció.

Resposta

L'enllaç s'ha creat.

Una execució de Bank Link per a una persona: connectar un banc o renovar una connexió. Confirma tu mateix un enllaç amb get_link: no confiïs mai en un identificador enviat pel navegador.

id
string<uuid>
requerit

Identificador de l'enllaç.

mode
enum<string>
requerit
Opcions disponibles:
connect,
renew
access
enum<string>
requerit
Opcions disponibles:
one_time,
ongoing
status
enum<string>
requerit

Estat de l'enllaç. completed, cancelled, expired i failed són estats finals.

Opcions disponibles:
created,
opened,
connecting,
completed,
cancelled,
expired,
failed
url
string<uri> | null
requerit

La pàgina allotjada a la qual cal enviar la persona. Només es retorna en crear l'enllaç; és null en lectures posteriors, perquè el token no s'emmagatzema.

client_token
string | null
requerit

El token del Bank Link integrat de Didit, que encara no està disponible: obre url avui. Només es retorna en crear l'enllaç; null en lectures posteriors. Té un únic propòsit i és de vida curta. No conté dades personals. No el registris mai.

expires_at
string<date-time>
requerit

Quan deixa de funcionar un enllaç no utilitzat.

connection_id
string<uuid> | null
requerit

La connexió que aquest enllaç ha creat o renovat, quan status és completed.

check_id
string<uuid> | null
requerit

El resultat de titularitat d'aquest enllaç, quan s'ha sol·licitat ownership.compare amb un valor diferent de none.

reused
boolean
requerit

true quan l'enllaç s'ha completat com a renovació d'una connexió existent perquè la persona ja comparteix exactament aquests comptes (duplicates: reuse). No es cobra res dues vegades.

error
object | null
requerit

Per què ha fallat l'enllaç, quan status és failed. En cas contrari, null.

quote
object
requerit

El preu d'un enllaç, fixat en el moment de crear-lo. El preu cobrat és el de la cotització. Les lectures no es facturen mai.

vendor_data
string | null
requerit

La vostra referència de la sol·licitud.

Darrera modificació el 22 de novembre del 2026