Confirmação de um pedido de reivindicação
stable
A confirmação de um pedido de reivindicação é uma etapa exclusiva do fluxo de doação de chaves. Ela ocorre quando outra instituição financeira faz ao cliente de nosso parceiro um pedido de reivindicação de portabilidade ou posse de uma chave.
Caso o cliente opte por ceder a chave solicitada, será necessário confirmar o pedido.
Ao confirmar um pedido de reivindicação, o vínculo da chave com o doador é removido.
Importante
Os pedidos de reivindicação de portabilidade ou posse são comunicados ao parceiro via eventos de webhoook. Para receber esses eventos, é preciso realizar a configuração dos webhooks.
Se desejar, o parceiro também poderá utilizar o endpoint de consulta de pedidos.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- O cliente de nosso parceiro tenha recebido um pedido de reivindicação de portabilidade ou posse de uma chave.
Requisição
Requisição HTTP
PATCH https://api-mtls.sandbox.bankly.com.br/pix/claims/{claimId}/confirm
curl--request PATCH \
--url 'https://api-mtls.sandbox.bankly.com.br/pix/claims/{{claimId}}/confirm' \
--header 'api-version: 1' \
--header 'x-bkly-pix-user-id: {{DOCUMENT_NUMBER}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
"reason": "DONOR_REQUEST"
}'
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.confirm | Concede acesso para confirmar 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 usuário que está fazendo a requisição. Insira apenas números, sem formatação. |
Parâmetros da rota (Path)
No path desta requisição envie os seguintes campos:
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)
No body, envie os seguintes campos em formato JSON:
Nome | Tipo | Descrição |
---|---|---|
reason | string | Obrigatório. Motivo pelo qual a confirmação está ocorrendo, que nesse caso deverá ser preenchido com DONOR_REQUEST (solicitação do cliente). |
{
"reason": "DONOR_REQUEST"
}
Resposta (Response)
O status code 200 indicará que o pedido foi confirmado 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. |
Importante
Os pedidos de reivindicação de portabilidade ou posse são comunicados ao parceiro via eventos de webhoook. Para receber esses eventos, é preciso realizar a configuração dos webhooks. Se desejar, o parceiro também poderá utilizar o endpoint de consulta de pedidos.
{
"claimId": "265a48f8-8cb3-4cf4-9170-c65fd83fccc3",
"type": "OWNERSHIP",
"addressingKey": {
"type": "PHONE",
"value": "+5531293323080"
},
"claimer": {
"branch": "0001",
"number": "15164",
"bank": {
"ispb": "13140088"
}
},
"donor": {
"branch": "1",
"number": "422316",
"bank": {
"ispb": "13140088"
}
},
"status": "CONFIRMED",
"previousStatus": "WAITING_RESOLUTION",
"confirmReason": "DONOR_REQUEST",
"confirmedBy": "DONOR",
"createdAt": "2023-05-22T19:48:06.921+00:00",
"updatedAt": "2023-05-22T19:54:06.1800233Z",
"resolutionLimitDate": "2023-05-29T19:47:00+00:00",
"conclusionLimitDate": "2023-06-05T19:47:00+00:00",
"confirmedAt": "2023-05-22T19:54:06.1800232Z"
}
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 | CLAIM_CANNOT_BE_CONFIRMED_BY_CLAIMER | A reivindicação não pode ser confirmada pelo reivindicador. |
422 | CLAIM_STATUS_DOES_NOT_ALLOW_CONFIRMATION | O status não permite realizar a confirmação. |
422 | CLAIM_CAN_ONLY_BE_CONFIRMED_BY_DONOR_ACCOUNT_HOLDER | A reivindicação de portabilidade ou de posse só pode ser confirmada pelo titular da conta do doador. |
422 | CLAIM_ALREADY_CONFIRMED | A reivindicação já foi confirmada. |
422 | INVALID_STATUS_TO_CONFIRM_CLAIM | Esse status não permite realizar a confirmação da reivindicação. |
422 | CONFIRMATION_REASON_NOT_INFORMED | A razão da confirmação não foi informada. |
422 | CONFIRMATION_REASON_INVALID_TO_PORTABILITY_CLAIM | A razão da confirmação é inválida para a reivindicação de portabilidade. |
422 | INVALID_STATUS_TO_CONFIRM_OWNERSHIP_CLAIM | Não é possível realizar a confirmação da reivindicação de posse quando o status é diferente de WAITING_RESOLUTION ou CONFIRMED. |
422 | CONFIRMATION_REASON_INVALID_TO_OWNERSHIP_CLAIM | A razão da confirmação é inválida para reivindicação de posse. |
422 | OWNERSHIP_CLAIM_RESOLUTION_DATE_NOT_ENDED | Como a data de resolução da reivindicação de posse ainda não expirou, não é possível utilizar a razão DEFAULT_OPERATION. |
422 | MAXIMUM_ENTRIES_COUNT_REGISTERED_FOR_CLAIMER | Número de vínculos associados à conta transacional excedeu o limite máximo. |
422 | REQUEST_NOT_ALLOWED_OUT_OF_BUSINESS_PERIOD | Serviço indisponível ou em manutenção. |
Válido lembrar que a API também poderá retornar erros comuns entre todos os endpoints.
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_CONFIRMED | O pedido de reivindicação foi confirmado. |
Updated 21 days ago