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 (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.	Informe somente números, sem caracteres especiais.

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 do pedido de portabilidade ou posse. Esse valor deverá ser utilizado todas as vezes que for realizado 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 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.
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.