Completando o pedido de reivindicação

stable

Depois que a requisição de reivindicação de portabilidade ou posse de chave é enviada, a instituição que a recebeu dará um retorno ao Bankly, confirmando ou não a doação da chave.

Caso o parceiro tenha reivindicado a portabilidade de uma chave, o pedido sempre será completado automaticamente após a confirmação do recebimento por parte da instituição doadora.

Porém, se o parceiro reivindicou a posse de uma chave, ele deverá completar o pedido por meio do endpoint a seguir.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que:

• A reivindicação de posse apresente o status CONFIRMED. O status pode ser verificado por meio do endpoint Consulta dos pedidos de reivindicação;
• O parceiro possua o hash gerado na criação do código TOTP (em caso de reivindicação de chaves do tipo e-mail e telefone).

Requisição

Requisição HTTP

HTTP

PATCH https://api-mtls.sandbox.bankly.com.br/pix/claims/{claimId}/complete

cURL

--curl--request PATCH \
--url 'https://api-mtls.sandbox.bankly.com.br/pix/claims/{{claimId}}/complete' \ 
--header 'api-version: 1' \ 
--header 'x-bkly-pix-user-id: {{documentNumber}}' \ 
--header 'x-bkly-transactional-hash: {{hash}}' \ 
--header 'Accept: application/json' \ 
--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.claims.complete	Concede acesso para completar um pedido de reivindicaçã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 cliente que está fazendo a requisição. Insira apenas números, sem formatação.
x-bkly-transactional-hash	O envio desse campo no header da requisição é obrigatório apenas para reivindicação de chaves do tipo e-mail e telefone. Ele deve ser preenchido com o hash gerado na criação do código TOTP.

❗️

Atenção

Somente será possível completar o pedido de posse de chaves do tipo e-mail e telefone após a validação da identidade do cliente via código TOTP.

Parâmetros da rota (Path)

No path desta requisição envie o seguinte campo:

Nome	Tipo	Descrição
claimId	path	Obrigatório. Identificador único do pedido. Esse valor é retornado na criação de pedido de reivindicação, no evento PIX_CLAIM_WAS_CONFIRMED e na consulta dos pedidos de reivindicação.

Corpo da requisição (Body)

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

Resposta (Response)

O status code 200 indicará que o pedido foi completado com sucesso.
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.ispb	string	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
donor	object	Objeto que contém os dados do banco e da conta do doador.
donor.branch	string	Número da agência bancária.
donor.number	string	Número da conta.
donor.bank	object	Objeto que contém os dados do banco do doador.
donor.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).
previousStatus	string	Status que o pedido de reinvindicação apresentava em etapa anterior.
confirmReason	string	Motivo da confirmação do pedido de reinvindicação, o qual pode ser: DONOR_REQUEST, retornado quando o dono da chave realiza a doação para o reivindicador, ou DEFAULT_OPERATION, quando o sistema confirma a doação de uma chave que já completou 15 dias em WAITING_RESOLUTION (somente em caso de posse).
confirmedBy	string	Autor da confirmação do pedido, que pode ser: DONOR, retornado quando o dono da chave realiza a doação para o reivindicador, ou SYSTEM, quando o sistema confirma a doação de uma chave que já completou 15 dias em WAITING_RESOLUTION (somente em caso de posse).
createdAt	string	Data de criação do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ.
updatedAt	string	Data de atualizaçã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.
confirmedAt	string	Data de confirmação do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ.
completedAt	string	Data em que o pedido de reivindicação foi completado, no formato aaaa-mm-ddTHH:mm:ss.sssZ.

JSON

{
    "claimId": "265a48f8-8cb3-4cf4-9170-c65fd83fccc3",
    "type": "OWNERSHIP",
    "addressingKey": {
        "type": "PHONE",
        "value": "[phone]"
    },
    "claimer": {
        "branch": "0001",
        "number": "15164",
        "bank": {
            "ispb": "13140088"
        }
    },
    "donor": {
        "branch": "1",
        "number": "540108",
        "bank": {
            "ispb": "13140088"
        }
    },
    "status": "COMPLETED",
    "previousStatus": "CONFIRMED",
    "confirmReason": "DONOR_REQUEST",
    "confirmedBy": "DONOR",
    "createdAt": "2023-05-22T19:48:06.921+00:00",
    "updatedAt": "2023-05-22T20:00:35.8177484Z",
    "resolutionLimitDate": "2023-05-29T19:47:00+00:00",
    "conclusionLimitDate": "2023-06-05T19:47:00+00:00",
    "confirmedAt": "2023-05-22T19:54:06.18+00:00",
    "completedAt": "2023-05-22T20:00:35.8177483Z"
}

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
422	INVALID_CLAIM_OPERATION	O status atual da reivindicação não permite realizar essa operação.
422	CLAIM_STATUS_DOES_NOT_ALLOW_COMPLETION	O status atual da reivindicação não permite que ela seja completada.
422	CLAIM_CANNOT_BE_COMPLETED_BY_DONOR	A reivindicação não pode ser completada pelo doador.
422	CLAIM_CAN_ONLY_BE_COMPLETED_BY_CLAIMER_ACCOUNT_HOLDER	A reivindicação de posse só pode ser completada pelo titular da conta do reivindicador.
422	CLAIM_ALREADY_COMPLETED	A reivindicação já foi completada.
422	INVALID_STATUS_TO_COMPLETE_CLAIM	A reivindicação não pode ser completada quando o status for diferente de CONFIRMED.
422	OWNERSHIP_CLAIM_CONCLUSION_DATE_NOT_ENDED	A data de conclusão da reivindicação de posse não foi encerrada.

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_COMPLETED	O processo de reivindicação foi concluído.