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
Requisição HTTP
POST https://api-mtls.sandbox.bankly.com.br/pix/claims
--curl--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 |
---|---|
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. |
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 |
---|---|---|
type | string | Obrigatório. Tipo de pedido, que pode ser "PORTABILITY", para portabilidade, e "OWNERSHIP", para posse. |
addressingKey | object | Obrigatório. Objeto que deverá conter os dados da chave de endereçamento. |
addressingKey.type | string | Obrigatório. Tipo de chave, o qual pode ser: CPF, CNPJ, PHONE e EMAIL. |
addressingKey.value | string | Obrigatório. Valor da chave. |
claimer | object | Obrigatório. Objeto que contém os dados da conta do reivindicador. |
claimer.branch | string | Obrigatório. Número da agência bancária. |
claimer.number | string | Obrigatório. Número da conta. |
claimer.bank | object | Obrigatório. Objeto que deverá conter os dados do banco do reivindicador. |
claimer.bank.name | string | Obrigatório. Nome da instituição de pagamento. |
claimer.bank.ispb | string | Obrigatório. ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
{
"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 |
---|---|---|
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 os dados da chave de endereçamento. |
addressingKey.type | string | Tipo de chave, o qual pode ser: CPF, CNPJ, PHONE e EMAIL. |
addressingKey.value | string | Valor da chave. |
claimer | object | Objeto que contém os dados do banco e da conta do reivindicador. |
claimer.branch | string | Número da agência bancária. |
claimer.number | string | Número da conta. |
claimer.bank | object | Objeto que contém os dados do banco do reivindicador. |
claimer.bank.name | string | Nome da instituição de pagamento. |
claimer.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
status | string | Situação do pedido de reivindicação, o qual pode ser: OPEN (aberto), WAITING_RESOLUTION (aguardando resolução), CONFIRMED (confirmado), CANCELLED (cancelado) ou COMPLETED (completado). |
createdAt | string | Data de criação do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ. |
resolutionLimitDate | string | Data limite para o doador de portabilidade realizar ações, como concluir ou cancelar o pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ. |
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 aaaa-mm-ddTHH:mm:ss.sssZ. |
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. |
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 | Descrição |
---|---|---|
400 | USER_ID_REQUIRED | Certifique-se de que o header x-bkly-pix-user-id foi informado. |
404 | CLAIM_NOT_FOUND | Pedido de reinvindicação não encontrado. |
422 | INVALID_USER_ID_DOCUMENT_NUMBER | 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 | Não é possível reivindicar a portabilidade e a posse de uma chave do tipo EVP. |
422 | 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 | Não é possível reivindicar a posse de uma chave do tipo CNPJ. |
422 | CLAIM_CAN_ONLY_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 | 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 | O vínculo com a chave reivindicada já existe. |
422 | CLAIM_ALREADY_EXISTS_FOR_ENTRY | A reivindicação já existe para essa chave de endereçamento. |
422 | INVALID_CLAIM | Há campos com preenchimento incorreto. |
Válido lembrar que a API também poderá retornar erros comuns entre todos os endpoints.
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 13 days ago