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 (Request)
Requisição HTTP
GET https://api-mtls.sandbox.bankly.com.br/pix/claims?documentNumber={{document_number}}&claimsFrom={{Claimer}}&status
--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:
| Scope | Descrição |
|---|---|
pix.claims.read | Concede acesso para consultar pedidos de portabilidade de chaves ou de reivindicação da 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. Insira apenas números, sem formatação. | Insira somente números, sem formatação. |
x-correlation-id | Se 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:
| Nome | Tipo | Descrição |
|---|---|---|
documentNumber | query | Obrigatório. Documento do titular da conta. |
claimsFrom | query | Obrigató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 ao cliente (doador) por outra instituição. |
status | query | Situação do pedido 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á sucesso na consulta.
Sendo bem-sucedido, o retorno irá trazer uma lista com 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 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 o banco 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.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco do reivindicador. |
donor | object | Objeto que contém informações sobre a conta do doador. |
donor.branch | string | Número da agência. |
donor.number | string | Número da conta. |
donor.bank | object | Objeto que contém informações sobre o banco do doador. |
donor.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco do doador. |
status | string | Situação do pedido de reivindicação. |
confirmReason | string | Motivo da confirmação do pedido de reinvindicação, que 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). |
cancelReason | string | Motivo do cancelamento do pedido de reinvindicação. |
canceleddBy | string | Autor 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). |
createdAt | string | Data de criação do pedido de reivindicação, no formato ISO 8601 - UTC. |
updatedAt | string | Data de atualização do pedido de reivindicação, no formato ISO 8601 - UTC. |
resolutionLimitDate | string | Data limite para o doador realizar ações, como concluir ou cancelar o pedido de reivindicação, 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. |
confirmedAt | string | Data de confirmação do pedido de reivindicação, no formato ISO 8601 - UTC. |
completedAt | string | Data em que o pedido de reivindicação foi completado, no formato ISO 8601 - UTC. |
canceledAt | string | Data de cancelamento do pedido de reivindicação, no formato ISO 8601 - UTC. |
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
| 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. |
| WAITING_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. |
Motivo do cancelamento do pedido de reinvindicação
| Motivo | Descrição |
|---|---|
| CLAIMER_REQUEST | Cancelado pelo reivindicador. |
| DONOR_REQUEST | Cancelado pelo doador (somente portabilidade). |
| ACCOUNT_CLOSURE | Esse tipo de cancelamento ocorre caso uma conta seja encerrada e esta possua chaves com pedido de portabilidade em aberto. |
| FRAUD | Cancelado pelo doador (somente posse). |
| DEFAULT_OPERATION | Cancelado 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 code | Código | Mensagem | Descrição |
|---|---|---|---|
| 404 | CLAIM_NOT_FOUND | Claim 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.
Updated 7 days ago