Criação de pedido de reivindicação

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 campo conclusionLimitDate), 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.

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.

Criação de pedido de reivindicação

📘
Nota

Pré-requisito

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

Resposta (Response)

🚧
Importante

Possíveis status

👍
Dica

Erros

Eventos

📘Nota

Pré-requisito

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

Resposta (Response)

🚧Importante

Possíveis status

👍Dica

Erros

Eventos

📘
Nota

🚧
Importante

👍
Dica