Consulta dos pedidos de reivindicação

stable

O endpoint de consulta de pedidos de reivindicação permite:

  • Acompanhar as solicitações de reivindicação de posse ou portabilidade de chaves realizadas pelos clientes dos parceiros Bankly;
  • Verificar se há pedidos de reivindicação provenientes de outras instituições financeiras direcionados aos clientes dos parceiros Bankly.

Requisição

Requisição HTTP

GET https://api-mtls.sandbox.bankly.com.br/pix/claims?documentNumber={{document_number}}&claimsFrom={{Claimer}}&status
--curl--request GET \
	  --url 'https://api-mtls.sandbox.bankly.com.br/pix/claims?documentNumber={{document_number}}&claimsFrom={{Claimer}}' \ 
	  --header 'accept: application/json' \ 
	  --header 'api-version: 1'
	  --header 'x-correlation-id: {{GUID}}' \ 
	  --header 'Authorization: {{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:

ScopeDescrição
pix.claims.readConcede acesso para consultar pedidos de portabilidade de chaves ou de reivindicação da posse para outra instituição.

Cabeçalhos (Headers)

NomeDescriçãoEspecificação
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
x-bkly-pix-user-idObrigatório. Número do documento do usuário que está fazendo a requisição. Insira apenas números, sem formatação.Insira apenas números, sem formatação.
x-correlation-idSe desejar, informe um GUID v4, sendo um novo cada requisição.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

NomeTipoDescrição
documentNumberqueryObrigatório. Documento do titular da conta.
claimsFromqueryObrigatório. Deve-se informar "Claimer", para obter dados de pedidos reivindicação abertos pelo cliente (reivindicador), e "Donor", para consultar as chaves que foram solicitadas por outra instituição ao cliente (doador).
statusquerySituação do pedido de reivindicação. Consulte a tabela dos possíveis status do pedido de portabilidade ou posse no final da página.

Corpo da requisição (Body)

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

Resposta (Response)

O status code 200 indicará sucesso na consulta.
Sendo bem-sucedido, o retorno irá trazer uma lista com os seguintes campos em formato JSON:

NomeTipoDescrição
claimIdstringIdentificaçã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.
typestringTipo de reivindicação, que pode ser PORTABILITY (portabilidade) ou OWNERSHIP (posse).
addressingKeyobjectObjeto que contém os dados da chave de endereçamento.
addressingKey.typestringTipo de chave, o qual pode ser: CPF, CNPJ, PHONE e EMAIL.
addressingKey.valuestringValor da chave.
claimerobjectObjeto que contém os dados do banco e da conta do reivindicador.
claimer.branchstringNúmero da agência bancária.
claimer.numberstringNúmero da conta.
claimer.bankobjectObjeto que contém os dados do banco do reivindicador.
claimer.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
donorobjectObjeto que contém os dados do banco e da conta do doador.
donor.branchstringNúmero da agência bancária.
donor.numberstringNúmero da conta.
donor.bankobjectObjeto que contém os dados do banco do doador.
donor.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
statusstringSituação do pedido de reivindicação. Consulte a tabela dos possíveis status do pedido de portabilidade ou posse no final da página.
confirmReasonstringMotivo 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).
confirmedBystringAutor 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).
cancelReasonstringMotivo do cancelamento do pedido de reinvindicação.
canceleddBystringAutor do cancelamento do pedido de reinvindicação, que pode ser: DONOR (doador), CLAIMER (reivindicador) ou SYSTEM (apenas em caso de portabilidade, quando o pedido completa sete dias com o status WAITING_RESOLUTION, o sistema realiza o cancelamento).
createdAtstringData de criação do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ.
updatedAtstringData de atualização do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ.
resolutionLimitDatestringData limite para o doador realizar ações, como concluir ou cancelar o pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ.
conclusionLimitDatestringData 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.
confirmedAtstringData de confirmação do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ.
completedAtstringData em que o pedido de reivindicação foi completado, no formato aaaa-mm-ddTHH:mm:ss.sssZ.
canceledAtstringData de cancelamento do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ.

📘

Nota

Os campos retornados poderão variar, de acordo com a situação (status) em que o pedido de reivindicação se encontra.

O Retorno 1 traz detalhes dos pedidos de reivindicação de chaves abertos por um cliente do parceiro Bankly (caso em que o cliente é o reivindicador).

Já o Retorno 2 refere-se a um pedido de reivindicação proveniente de outra instituição financeira para um cliente do parceiro Bankly (nesse caso, o cliente é o doador).

[
    {
        "claimId": "7b457d2c-a024-43fe-9cca-845405d6661f",
        "type": "PORTABILITY",
        "addressingKey": {
            "type": "PHONE",
            "value": "+5523415162342"
        },
        "claimer": {
            "branch": "0001",
            "number": "15164",
            "bank": {
                "ispb": "13140088"
            }
        },
        "status": "OPEN",
        "createdAt": "2023-01-23T18:31:30.639+00:00",
        "resolutionLimitDate": "2023-01-30T18:31:30.639+00:00",
        "conclusionLimitDate": "2023-02-06T18:31:30.639+00:00"
    },
    {
        "claimId": "2c29fffc-0305-4a0b-acaa-e7edfda0968a",
        "type": "OWNERSHIP",
        "addressingKey": {
            "type": "PHONE",
            "value": "+5523415162341"
        },
        "claimer": {
            "branch": "0001",
            "number": "15164",
            "bank": {
                "ispb": "13140088"
            }
        },
        "status": "OPEN",
        "createdAt": "2023-01-23T18:38:24.667+00:00",
        "resolutionLimitDate": "2023-01-30T18:38:24.667+00:00",
        "conclusionLimitDate": "2023-02-06T18:38:24.667+00:00"
    },
    {
        "claimId": "71d74c4f-764c-4746-bca0-b7348782e10c",
        "type": "OWNERSHIP",
        "addressingKey": {
            "type": "EMAIL",
            "value": "[email protected]"
        },
        "claimer": {
            "branch": "0001",
            "number": "15164",
            "bank": {
                "ispb": "13140088"
            }
        },
        "status": "OPEN",
        "createdAt": "2023-01-23T18:39:25.748+00:00",
        "resolutionLimitDate": "2023-01-30T18:39:25.748+00:00",
        "conclusionLimitDate": "2023-02-06T18:39:25.748+00:00"
    }
]
[ 
    { 
        "claimId": "e6aeef23-e7e9-48de-9343-9386e8763204", 
        "type": "OWNERSHIP", 
        "addressingKey": { 
            "type": "EMAIL", 
            "value": "[email protected]" 
        }, 
        "claimer": { 
            "branch": "0001", 
            "number": "2222222", 
            "bank": { 
                "ispb": "18236120" 
            } 
        }, 
        "donor": { 
            "branch": "0001", 
            "number": "123456", 
            "bank": { 
                "ispb": "15164" 
            } 
        }, 
        "status": "WAITING_RESOLUTION", 
        "createdAt": "2022-06-23T13:15:15.508+00:00", 
        "updatedAt": "2022-06-23T13:34:31.18+00:00", 
        "resolutionLimitDate": "2022-06-30T13:15:15.508+00:00", 
        "conclusionLimitDate": "2022-07-07T13:15:15.508+00:00" 
    }, 
    { 
        "claimId": "2c8c792c-1264-45a5-a350-6470950622db", 
        "type": "PORTABILITY", 
        "addressingKey": { 
            "type": "EMAIL", 
            "value": "[email protected]" 
        }, 
        "claimer": { 
            "branch": "0001", 
            "number": "12345678", 
            "bank": { 
                "ispb": "18236120" 
            } 
        }, 
        "donor": { 
            "branch": "0001", 
            "number": "15164", 
            "bank": { 
                "ispb": "13140088" 
            } 
        }, 
        "status": "CANCELED", 
        "cancelReason": "DONOR_REQUEST", 
        "canceledBy": "DONOR", 
        "createdAt": "2022-05-27T17:50:48.196+00:00", 
        "updatedAt": "2022-05-31T00:15:39.282+00:00", 
        "resolutionLimitDate": "2022-06-03T17:50:48.196+00:00", 
        "conclusionLimitDate": "2022-06-10T17:50:48.196+00:00", 
        "canceledAt": "2022-05-31T00:15:39.282+00:00" 
    }
]

Possíveis status

StatusDescrição
OPENSolicitação aberta pelo reivindicador, mas ainda não recebida pelo doador.
WAITING_RESOLUTIONA reivindicação já foi recebida pelo doador e está aguardando a resolução.
CONFIRMEDO 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.
WAITING_VALIDATIONApó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).
CANCELEDO 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.
COMPLETEDO pedido de portabilidade ou posse foi completado com sucesso e que chave foi transferida para o Bankly.

Motivo do cancelamento do pedido de reinvindicação

MotivoDescrição
CLAIMER_REQUESTCancelado pelo reivindicador.
DONOR_REQUESTCancelado pelo doador (somente portabilidade).
ACCOUNT_CLOSUREEsse tipo de cancelamento ocorre caso uma conta seja encerrada e esta possua chaves com pedido de portabilidade em aberto.
FRAUDCancelado pelo doador (somente posse).
DEFAULT_OPERATIONCancelado pelo sistema. Esse tipo de cancelamento ocorre quando o pedido completa sete dias com o status WAITING_RESOLUTION (somente para portabilidade).

👍

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 codeCódigoMensagemDescrição
404CLAIM_NOT_FOUNDClaim not found.Pedido de reinvindicação não encontrado.

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

Este endpoint não possui eventos relacionados a ele.