Criação de pedido de reivindicação
stable
O endpoint de reivindicação de chaves Pix possibilita solicitar a portabilidade ou a posse de uma chave Pix, de acordo com a necessidade de seu cliente.
Nota
Após a criação de um pedido de reivindicação de posse de chave Pix, é necessário completar o pedido.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- O cliente possua uma conta ativa.
Requisição (Request)
Requisição HTTP
POST https://api-mtls.sandbox.bankly.com.br/pix/claims
--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/pix/claims' \
--header 'api-version: 1.0' \
--header 'x-bkly-pix-user-id: {{document_number}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
"type": "PORTABILITY",
"addressingKey": {
"type": "CPF",
"value": "47742663023"
},
"claimer": {
"branch": "0001",
"number": "15164",
"bank": {
"name": "Acesso Soluções de Pagamento S.A",
"ispb": "13140088"
}
}
}'
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.claims.create | Concede acesso para criar um pedido de portabilidade de chaves ou reivindicar a posse para outra instituição. |
Cabeçalhos (Headers)
Nome | Descrição | Especificaçã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 somente números, sem formatação. |
Parâmetros da rota (Path)
Não é necessário enviar parâmetros no path desta requisição.
Corpo da requisição (Body)
No body, envie os seguintes campos em formato JSON:
Nome | Tipo | Descrição | Especificação |
---|---|---|---|
type | string | Obrigatório. Tipo de reivindicação, que pode ser "PORTABILITY" (portabilidade) ou "OWNERSHIP" (posse). | — |
addressingKey | object | Obrigatório. Objeto que deverá conter informações sobre a chave de endereçamento. | — |
addressingKey.type | string | Obrigatório. Tipo de chave, que pode ser "CPF", "CNPJ", "PHONE" ou "EMAIL". | — |
addressingKey.value | string | Obrigatório. Valor da chave. | — |
claimer | object | Obrigatório. Objeto que deverá conter informações sobre a conta do reivindicador. | — |
claimer.branch | string | Obrigatório. Número da agência. | — |
claimer.number | string | Obrigatório. Número da conta. | — |
claimer.bank | object | Obrigatório. Objeto que deverá conter informações sobre o banco do reivindicador. | — |
claimer.bank.name | string | Obrigatório. Nome do banco. | — |
claimer.bank.ispb | string | Obrigatório. ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco reivindicador. | O campo deve conter oito caracteres. Portanto, se o ISPB do banco contiver apenas seis dígitos, por exemplo, complete-o com zeros à esquerda. Exemplo: "00123456". |
{
"type": "PORTABILITY",
"addressingKey": {
"type": "CPF",
"value": "47742663023"
},
"claimer": {
"branch": "0001",
"number": "15164",
"bank": {
"name": "Acesso Soluções de Pagamento S.A",
"ispb": "13140088"
}
}
}
{
"type": "OWNERSHIP",
"addressingKey": {
"type": "PHONE",
"value": "{{phone_number}}"
},
"claimer": {
"branch": "0001",
"number": "123456",
"bank": {
"name": "Acesso Soluções de Pagamento S.A",
"ispb": "13140088"
}
}
}
Resposta (Response)
O status code 201 indicará sucesso na criação do pedido de reinvindicação.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
Nome | Tipo | Descrição | Número máximo de caracteres |
---|---|---|---|
claimId | string | Identificação única de pedido de portabilidade ou posse. Esse valor deverá ser utilizado todas as vezes que você realizar uma operação referente a essa reivindicação, como consulta, cancelamento etc. | — |
type | string | Tipo de reivindicação, que pode ser "PORTABILITY" (portabilidade) ou "OWNERSHIP" (posse). | — |
addressingKey | object | Objeto que contém informações sobre a chave de endereçamento. | — |
addressingKey.type | string | Tipo de chave, que pode ser "CPF", "CNPJ", "PHONE" ou "EMAIL". | — |
addressingKey.value | string | Valor da chave. | — |
claimer | object | Objeto que contém informações sobre a conta do reivindicador. | — |
claimer.branch | string | Número da agência. | — |
claimer.number | string | Número da conta. | |
claimer.bank | object | Objeto que contém informações sobre o banco do reivindicador. | — |
claimer.bank.name | string | Nome do banco. | — |
claimer.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco reivindicador. | — |
status | string | Situação do pedido de reivindicação. | — |
createdAt | string | Data de criação do pedido de reivindicação, no formato ISO 8601 - UTC. | — |
resolutionLimitDate | string | Data limite para o doador de portabilidade realizar ações, como concluir ou cancelar o processo de portabilidade, no formato ISO 8601 - UTC. | — |
conclusionLimitDate | string | Data limite para o doador de posse e o reivindicador (tanto de posse como de portabilidade) confirmarem ou cancelarem o pedido, no formato ISO 8601 - UTC. | — |
Importante
No caso de reivindicação de portabilidade, se a instituição doadora não responder o pedido em sete dias (cujo limite é indicado no campo
resolutionLimitDate
), ele é automaticamente cancelado e a chave permanece na mesma conta onde está cadastrada. Já no fluxo de reivindicação de posse, se não houver uma resposta dentro de 14 dias (cujo limite é indicado no campoconclusionLimitDate
), a chave passará para quem a reivindicou.
{
"claimId": "265a48f8-8cb3-4cf4-9170-c65fd83fccc3",
"type": "PORTABILITY",
"addressingKey": {
"type": "CPF",
"value": "47742663023"
},
"claimer": {
"branch": "0001",
"number": "15164",
"bank": {
"name": "Acesso Soluções de Pagamento S.A",
"ispb": "13140088"
}
},
"status": "OPEN",
"createdAt": "2022-06-21T15:05:42.4626073Z",
"resolutionLimitDate": "2022-06-28T15:05:42.4626073Z",
"conclusionLimitDate": "2022-07-05T15:05:42.4626073Z"
}
{
"claimId": "265a48f8-8cb3-4cf4-9170-c65fd83fccc3",
"type": "OWNERSHIP",
"addressingKey": {
"type": "PHONE",
"value": "+5523415162342"
},
"claimer": {
"branch": "0001",
"number": "15164",
"bank": {
"name": "Acesso Soluções de Pagamento S.A",
"ispb": "13140088"
}
},
"status": "OPEN",
"createdAt": "2023-05-22T19:47:00.8196218Z",
"resolutionLimitDate": "2023-05-29T19:47:01.002Z",
"conclusionLimitDate": "2023-06-05T19:47:01.002Z"
}
Possíveis status
Status | Descrição |
---|---|
OPEN | Solicitação aberta pelo reivindicador, mas ainda não recebida pelo doador. |
WAITING_RESOLUTION | A reivindicação já foi recebida pelo doador e está aguardando a resolução. |
CONFIRMED | O doador confirmou o pedido de reivindicação e vai ceder a chave para a outra instituição. Isso implica a remoção da chave do DICT e da base interna do PSP doador. Está aguardando o reivindicador encerrar o processo. |
WATING_VALIDATION | Após a confirmação, indica-se que o ConclusionLimitDate foi atingido. A partir deste momento, a reivindicação passa a ter o status de WAITING_VALIDATION, permitindo ao reivindicador realizar a validação de posse (TOTP) e concluir a reivindicação. Isso é aplicável apenas para reivindicações de posse (OWNERSHIP). |
CANCELED | O doador ou reivindicador cancelou a reivindicação, mantendo o vínculo inalterado (conforme estava antes da reivindicação), tanto no DICT quanto na base interna do PSP. |
COMPLETED | O pedido de portabilidade ou posse foi completado com sucesso e que chave foi transferida para o Bankly. |
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint pode retornar erros específicos, conforme a tabela a seguir:
Status code | Código | Mensagem | Descrição |
---|---|---|---|
400 | USER_ID_REQUIRED | Ensure that the x-bkly-pix-user-id header was provided. | Certifique-se de que o header x-bkly-pix-user-id foi informado. |
404 | CLAIM_NOT_FOUND | Claim not found. | Pedido de reinvindicação não encontrado. |
422 | INVALID_USER_ID_DOCUMENT_NUMBER | Ensure that the x-bkly-pix-user-id header is the same as the given documentNumber. | Certifique-se de que o valor do header x-bkly-pix-user-id informado é o mesmo que o informado no campo documentNumber . |
422 | CANNOT_REGISTER_CLAIM_TO_EVP_TYPE | Cannot register portability claim and ownership claim to EVP type. | Não é possível reivindicar a portabilidade e a posse de uma chave do tipo EVP. |
422 | CANNOT_REGISTER_OWNERSHIP_CLAIM_TO_CPF_TYPE | Cannot register ownership claim to CPF type. | Não é possível reivindicar a posse de uma chave do tipo CPF. |
422 | CANNOT_REGISTER_OWNERSHIP_CLAIM_TO_CNPJ_TYPE | Cannot register ownership claim to CNPJ type. | Não é possível reivindicar a posse de uma chave do tipo CNPJ. |
422 | CLAIM_CAN_ONLY_BE_REGISTERED_BY_CLAIMER_ACCOUNT_HOLDER | Portability claim and ownership claim only can be registered by claimer account holder. | A reivindicação de portabilidade e de posse somente pode ser feita pelo titular da conta. |
422 | INVALID_CLAIM_TYPE_USED_ON_REQUEST | Requested claim type is inconsistent. This error occurs in situations where an attempt is made to create: A) ownership claim, but the existing bond is owned by the same person who claim or B) Portability claim, but the existing bond is owned by a different person from the one who claim. | O tipo de reivindicação informado é incorreto. Esse erro pode ocorrer quando a pessoa que reivindica a posse já é proprietária da chave (o correto seria solicitar a portabilidade). Ou então, quando a pessoa reivindica a portabilidade de uma chave que está em posse de outra pessoa (o correto seria solicitar a posse). |
422 | CLAIM_RESULTING_ENTRY_ALREADY_EXISTS | Bond that would result when processing the claim already exists, with the same key, participant and owner. | O vínculo com a chave reivindicada já existe. |
422 | CLAIM_ALREADY_EXISTS_FOR_ENTRY | Claim already exists for the addressing key. | A reivindicação já existe para essa chave de endereçamento. |
422 | INVALID_CLAIM | Exist invalid fields when trying to create the claim. | Há campos com preenchimento incorreto. |
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
Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:
Nome do evento | Descrição |
---|---|
PIX_CLAIM_WAS_REGISTERED | Um cliente do parceiro Bankly registrou um pedido de reivindicação de posse/portabilidade para outra instituição. |
Updated 24 days ago