Saltar para o conteúdo principal
POST
curl
O endpoint Criar uma Bank Link da Didit inicia uma execução da Bank Link no seu servidor, para ligar um banco ou renovar uma ligação, e devolve o url alojado. Todos os campos têm um valor predefinido, pelo que o pedido mais simples é {} mais o que pretender. Guarde o id devolvido junto do seu utilizador e confirme o resultado por si próprio com Obter uma Bank Link ou com o webhook bank.link.completed. Consulte o início rápido e a Bank Link.

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, obtida em Developers -> API keys na Business Console. A chave principal tem acesso total. Uma chave com nome pode ter o âmbito limitado: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou apenas a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que não foi enviada nenhuma chave, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe os URLs de imagem, vídeo e PDF como null, e uma chave sem escrita em sessões recebe os links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.

Cabeçalhos

Idempotency-Key
string

Chave opcional, à sua escolha, para garantir a segurança de novas tentativas numa operação, com até 255 caracteres (um UUID funciona). Um pedido repetido com a mesma chave, endpoint, parâmetros de query e corpo recebe a primeira resposta, com o mesmo código de estado e o mesmo corpo, e não é executado nem faturado uma segunda vez. A mesma chave com outro endpoint, outros parâmetros de query ou outro corpo devolve 409 idempotency_key_reused. Enquanto o primeiro pedido ainda estiver em execução, devolve 409 idempotency_key_in_progress com Retry-After. Um pedido falhado (qualquer 4xx ou 5xx) não é guardado, pelo que pode ser enviado novamente com a mesma chave. As chaves pertencem à sua aplicação, quer chame a API com uma chave de API, quer com um token de acesso. Consulte Novas tentativas e idempotência.

Required string length: 1 - 255

Corpo

application/json

Crie uma ligação bancária (Bank Link). O pedido mais pequeno é {} mais o que pretender: todos os campos têm um valor predefinido.

mode
enum<string>
padrão:connect

connect (predefinido) cria uma nova conexão. renew requer connection_id e reutiliza as definições dessa conexão.

Opções disponíveis:
connect,
renew
connection_id
string<uuid>

A ligação a renovar. Apenas com mode: renew.

access
enum<string>
padrão:one_time

one_time (predefinido) lê os dados uma única vez. ongoing mantém o acesso aberto até que o consentimento termine ou alguém o interrompa. Quando institution_id está definido, um banco que não consegue manter o acesso aberto responde com 400 ongoing_access_not_available antes de qualquer ecrã. Sem ele, o seletor de bancos lista apenas os bancos que conseguem.

Opções disponíveis:
one_time,
ongoing
country
string

Opcional. Sem este campo, a pessoa escolhe entre os países que a sua aplicação ativou. Tem de ser um país que o Bank Link serve; qualquer outro, incluindo ZZZ, responde com 400 invalid_request e field: country. Um corpo de pedido vazio continua válido.

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

Banco opcional a pré-selecionar, obtido de list_institutions. Ignora o seletor.

Maximum string length: 64
segment
enum<string>
padrão:any

Filtra o seletor e indica ao banco qual o acesso a abrir, quando o banco os separa. Predefinição any.

Opções disponíveis:
personal,
business,
any
data
enum<string>[]

O que ler. accounts está sempre incluído: nome, tipo, moeda, identificadores e o nome do titular quando o banco o partilha. Predefinido ["accounts"].

Maximum array length: 3
Opções disponíveis:
accounts,
balances,
transactions
history_days
integer
padrão:90

Dias de histórico de transações a pedir, de 1 a 365, por predefinição 90. O banco pode entregar menos: cada conta indica o que entregou em history_coverage. Não pode ser enviado em conjunto com history_from.

Intervalo necessário: 1 <= x <= 365
history_from
string<date>

Data de início do histórico a pedir, em vez de history_days. Não pode ser enviada com history_days: ambos juntos respondem 400 history_window_ambiguous. Uma data anterior a 365 dias, ou no futuro, responde 400 window_not_available.

extended_history
enum<string>
padrão:standard

allow_extra_auth permite que um banco que pede uma confirmação adicional disponibilize histórico mais antigo.

Opções disponíveis:
standard,
allow_extra_auth

Apenas para ligações contínuas. Número de dias para pedir ao banco que mantenha o acesso aberto, 1 ou mais. Predefinição: o máximo que o banco permite. A ligação indica a data que o banco concedeu efetivamente em consent.expires_at. Com access: one_time, responde com 400 invalid_request e field: consent_days.

Intervalo necessário: 1 <= x <= 32767
ownership
object

Comparação opcional do titular da conta com uma pessoa ou uma empresa.

end_user
object

A pessoa ou empresa que liga a conta.

redirect_url
string<uri>

Para onde o navegador vai no fim, com link_id, status e um state assinado (apenas para apresentação: o webhook e get_link são a referência autoritativa). Numa aplicação de sandbox, um endereço http simples de localhost, 127.0.0.1 ou [::1] (qualquer porta e caminho, sem credenciais, sem fragmento) não precisa de registo. Qualquer outro endereço responde 400 redirect_url_not_registered: o registo de outros endereços ainda não está disponível. Sem redirect_url, a pessoa termina na página de resultados da própria Didit.

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

Aceite, mas não utilizado atualmente: reservado para o Bank Link incorporado da Didit, que ainda não foi lançado. Origens HTTPS, até 50.

Maximum array length: 50
language
string

Código de idioma opcional, como es ou pt-BR. Caso contrário, o idioma do navegador.

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

A sua referência, devolvida na ligação e na conexão.

Maximum string length: 255
expires_in
integer
padrão:3600

Tempo de vida da ligação em segundos, de 300 a 86400. Predefinido: 3600.

Intervalo necessário: 300 <= x <= 86400
duplicates
enum<string>
padrão:reuse

reuse (predefinido) conclui uma ligação que remete para contas que já partilha como uma renovação dessa ligação. allow cria uma segunda ligação independente.

Opções disponíveis:
reuse,
allow
allow_one_time_fallback
boolean
padrão:false

Com ongoing, permite que a pessoa continue com uma leitura pontual num banco que não consegue manter o acesso aberto, depois de confirmar o acesso reduzido no próprio ecrã do banco. A cotação mostra o custo. Apenas com access: ongoing: com acesso pontual, responde com 400 invalid_request e field: allow_one_time_fallback.

accept_reduced_grant
boolean
padrão:false

Quando o banco ou a pessoa concede menos do que pediu, conclua a ligação e cobre apenas os âmbitos concedidos. Caso contrário, a ligação termina em failed com reduced_grant e nada é cobrado.

sandbox
object

Apenas aplicações sandbox: escolhe o cliente do Didit Test Bank. Ignorado numa aplicação de produção.

Resposta

A ligação foi criada.

Uma execução do Bank Link para uma pessoa: ligar um banco ou renovar uma ligação. Confirme pessoalmente a ligação com get_link: nunca confie num id enviado pelo navegador.

id
string<uuid>
obrigatório

Identificador do link.

mode
enum<string>
obrigatório
Opções disponíveis:
connect,
renew
access
enum<string>
obrigatório
Opções disponíveis:
one_time,
ongoing
status
enum<string>
obrigatório

Estado do link. completed, cancelled, expired e failed são estados finais.

Opções disponíveis:
created,
opened,
connecting,
completed,
cancelled,
expired,
failed
url
string<uri> | null
obrigatório

A página alojada para onde enviar a pessoa. Devolvida apenas quando a ligação é criada; null nas leituras seguintes, porque o token não é guardado.

client_token
string | null
obrigatório

O token do Bank Link incorporado da Didit, que ainda não foi disponibilizado: abra url hoje. Devolvido apenas quando a ligação é criada; null nas leituras seguintes. Tem uma única finalidade e uma duração curta. Não contém dados pessoais. Nunca o registe.

expires_at
string<date-time>
obrigatório

Quando uma ligação não resgatada deixa de funcionar.

connection_id
string<uuid> | null
obrigatório

A ligação criada ou renovada por esta hiperligação, quando status é completed.

check_id
string<uuid> | null
obrigatório

O resultado da verificação de propriedade desta ligação, quando foi pedido ownership.compare com valor diferente de none.

reused
boolean
obrigatório

true quando a ligação foi concluída como renovação de uma ligação existente, porque a pessoa já partilha exatamente estas contas (duplicates: reuse). Nada é cobrado duas vezes.

error
object | null
obrigatório

Motivo da falha da ligação, quando status é failed. Caso contrário, null.

quote
object
obrigatório

O preço de uma ligação, fixado na criação. O valor cobrado é o da cotação. As leituras nunca são faturadas.

vendor_data
string | null
obrigatório

A sua referência do pedido.

Última modificação em 22 de novembro de 2026