Consulta de chaves para transferência

stable

Este endpoint permite realizar a consulta no DICT de todas as informações vinculadas à chave Pix que receberá uma transferência ou pagamento.

Essa consulta é um pré-requisito para realizar transações via Pix e abrange todas as chaves cadastradas no Bacen, não apenas aquelas vinculadas às contas Bankly.

Condições para consulta

Como mecanismo de prevenção a ataques de leitura, o DICT possui um controle de requisições baseado em consultas de chaves que não possuam liquidação e consultas inválidas.

Caso o Bankly identifique a recorrência de consultas sem vínculo com transações Pix, o uso do serviço será bloqueado.

❗️

Atenção

O DICT não deve ser utilizado para consulta cadastral e nem para qualquer outra finalidade que não seja transacionar para uma chave Pix. Para mais informações, consulte a documentação Manual Operacional do Diretório de Identificadores de Contas Transacionais (DICT).

Requisição

Requisição HTTP

HTTP

GET https://api-mtls.sandbox.bankly.com.br/pix/entries/{{addressingKeyValue}}

cURL

curl --request GET \ 
     --url 'https://api-mtls.sandbox.bankly.com.br/pix/entries/{{addressingKeyValue}}' \
     --header 'Accept: application/json' \
     --header 'api-version: 1.0' \
     --header 'x-bkly-pix-user-id: {{userDocument}}' \
     --header 'x-correlation-id: {{GUID}}' \ 
     --header 'Authorization: Bearer {{Token}}'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:

Scope	Descrição
pix.entries.read	Concede acesso para consultar chaves de endereçamento.

Cabeçalhos (Headers)

Nome	Descrição
api-version	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.
Authorization	Obrigatório. Token de autorização do tipo Bearer.
x-bkly-pix-user-id	Obrigatório. Número do documento do usuário que está fazendo a requisição. Insira apenas números, sem formatação.
x-correlation-id	Se desejar, informe um GUID, sendo um novo cada requisição.

🚧

Importante

Só será possível realizar a consulta por chave se o x-bkly-pix-user-id do payer estiver cadastrado em nossa base de dados. Caso contrário, será retornado o erro 403 - FORBIDDEN.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

Nome	Tipo	Descrição
addressingKeyValue	path	Obrigatório. Valor da chave de endereçamento a ser consultada. Veja na tabela a seguir as possibilidades de preenchimento.

Chave de endereçamento

Chave	Instrução de preenchimento
CPF	11 dígitos, sem formatação.
CNPJ	14 dígitos, sem formatação.
E-mail	Todos os caracteres em minúsculo. Tamanho máximo de 72 caracteres.
Phone (número de telefone celular)	Composto por símbolo ‘+’, seguido pelo código do país, DDD e número de celular com até nove dígitos. Ex.: [phone].
EVP	Tamanho máximo de 36 caracteres. Exemplo: 123e4967-e89b-12d3-a456-426655440000.

Corpo da requisição (Body)

Não é necessário enviar campos no body desta requisição.

Resposta (Response)

O status code 200 indicará sucesso na consulta.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
endToEndId	string	Identificador único do Pix. Ele será utilizado quando o parceiro realizar um pagamento ou transferência via Pix.
addressingKey	object	Objeto que contém os dados da chave de endereçamento.
addressingKey.type	string	Tipo de chave Pix.
addressingKey.value	string	Valor da chave.
holder	object	Objeto que contém os dados do titular da conta.
holder.type	string	Tipo de titular da conta (CUSTOMER ou BUSINESS).
holder.name	string	Nome do titular da conta conforme consta no documento de identificação.
holder.socialName	string	Nome pelo qual o titular gostaria de ser chamado. Saiba mais consultando a Cartilha do nome social. Este campo somente será retornado em caso de consulta de chave de pessoa física.
holder.tradingName	string	Nome fantasia da empresa. Este campo somente será retornado em caso de consulta de chave de pessoa jurídica.
holder.document	object	Objeto que contém os dados do documento do titular da conta.
holder.document.type	string	Número do documento.
holder.document.value	string	Tipo do documento, o qual pode ser "CPF ou "CNPJ”.
status	string	Descreve o status da chave de endereçamento.
createdAt	string	Data de criação da chave, no formato ISO 8601 - UTC.
ownedAt	string	Última data em que a chave foi vinculada a uma conta, no formato ISO 8601 - UTC.

🚧

Importante

O campo endToEndId possui duração de 15 minutos e só poderá ser utilizado em uma única transferência.

Consulta de chave - PF

{
    "endToEndId": "E1314008820210629151241054156224",
    "addressingKey": {
        "type": "CPF",
        "value": "***426630**"
    },
    "holder": {
        "type": "CUSTOMER",
        "name": "Nísia Floresta",
        "socialName": "Nísia Floresta",
        "document": {
            "value": "***426630**",
            "type": "CPF"
        }
    },
    "status": "OWNED",
    "createdAt": "2020-11-06T01:07:12.351+00:00",
    "ownedAt": "2020-11-06T01:07:12.337+00:00"
}

Consulta de chave - PJ

{
    "endToEndId": "E1314008820210629151241054156224",
    "addressingKey": {
        "type": "EVP",
        "value": "73275ad1-ae06-4407-b488-d86c9f502bac"
    },
    "holder": {
        "type": "BUSINESS",
        "name": "Nísia Floresta",
        "tradingName": "Editora Nísia Floresta",
        "document": {
            "value": "*456070001",
            "type": "CNPJ"
        }
    },
    "status": "OWNED",
    "createdAt": "2020-11-06T01:07:12.351+00:00",
    "ownedAt": "2020-11-06T01:07:12.337+00:00"
}

👍

Dica

Para simular uma requisição nesse endpoint, acesse o API Reference.

Status da chave de endereçamento

Status	Descrição
Owned	A chave pertence à conta.
Excluded	A chave foi excluída e não está mais vinculada a nenhuma conta.
Locked_By_Claim	A chave está bloqueada por um processo de portabilidade/reivindicação e não pode ser alterada ou excluída.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status code	Código	Mensagem	Descrição
404	ENTRY_NOT_FOUND	Entry not found.	Chave não encontrada.
408	REQUEST_TOOK_TOO_LONG_TO_RESPOND	Request took too long to respond. Please, wait 1 minute to try again.	A solicitação demorou muito para ser respondida. Aguarde alguns instantes para tentar novamente.
422	INVALID_USER_ID	Ensure that the x-bkly-pix-user-id header is a valid CPF or CNPJ document.	User id inválido. Verifique se o header x-bkly-pix-user-id é um CPF ou CNPJ válido.
422	PERMISSION_NOT_GRANTED	Permission not granted to perform the operation.	Permissão não concedida para realizar a operação.
422	MAXIMUM_ENTRIES_COUNT_REGISTERED_FOR_ACCOUNT	Account has reached the maximum entries count registered.	A quantidade de chaves registradas já atingiu o limite máximo.
422	ENTRY_ALREADY_EXISTS_TO_SAME_ACCOUNT	Entry already in use to same account. Consider making change account request.	Chave já em uso na mesma conta.
422	ENTRY_ALREADY_EXISTS_TO_ANOTHER_HOLDER	Entry already exists to another holder. Consider making claim request.	Chave já cadastrada por outro titular. Considere fazer uma solicitação de reivindicação.
422	ENTRY_ALREADY_EXISTS_TO_SAME_OWNER_INTO_ANOTHER_PLAYER	Entry already in use to same owner in another player. Consider making portability request.	Chave já em uso pelo mesmo dono em outra instituição financeira. Considere fazer o pedido de portabilidade.
422	ENTRY_LOCKED_BY_CLAIM	Entry is locked when claim request is being process.	A chave é bloqueada quando a solicitação de reivindicação está sendo processada.
422	REQUEST_NOT_ALLOWED_OUT_OF_BUSINESS_PERIOD	Request not not allowed out of business period.	Solicitação não permitida fora do período comercial.
422	EVP_ENTRY_CANNOT_REGISTER_SHORT_INTERVAL	Entry of type EVP cannot be registered in a short interval of time. Please wait a minute and try again.	Não é permitido cadastrar mais de uma chave do tipo EVP em um curto intervalo de tempo.
422	ANY_ENTRY_FOUND_TO_ACCOUNT	Not exists entries to account.	Nenhuma chave encontrada para a conta.
422	ANY_ENTRY_FOUND_TO_HOLDER	Not exists entry to holder.	Nenhuma chave encontrada para o titular.
422	ENTRY_ALREADY_EXISTS_TO_SAME_HOLDER_AND_ANOTHER_ACCOUNT	Entry already in use to same holder but to another account. Consider making portability request.	Chave já em uso pelo mesmo titular, mas em outra conta. Considere fazer o pedido de portabilidade.
429	RATE_LIMIT_REQUESTS_EXCEEDED	Rate limit exceeded and blocked by provider.	Limite de requisições excedido e bloqueado pelo provedor (trinta requisições por minuto no máximo e quatro requisições por segundo).
429	RATE_LIMIT_REQUESTS_EXCEEDED_BY_BACEN	Rate limit requests exceeded and blocked by BACEN.	Limite de requisições excedido e bloqueado pelo Bacen.
500	INTERNAL_ERROR	An unknown error occurs when processing the transaction.	Ocorreu um erro desconhecido ao processar a transação.
503	SERVICE_UNAVAILABLE	Service temporarily unavailable.	Serviço temporariamente indisponível.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.