Atualização cadastral
stable
Este endpoint possibilita a atualização de determinados dados cadastrais de clientes do tipo pessoa física.
As informações que podem ser atualizadas são:
- Telefone (desde que o novo número não esteja ativo em outro cadastro);
- E-mail (desde que o novo e-mail não esteja ativo em outro cadastro);
- Nome social;
- Endereço;
- Ocupação;
- Nível de exposição política do cliente;
- Renda declarada.
Nota
O endpoint de atualização cadastral não altera o status e nem o perfil do cliente, pois, para isso, é necessário realizar uma nova análise KYC. Para mais informações, consulte a documentação Onboarding de pessoa física.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- O cliente possua um cadastro aprovado no sistema (status APPROVED).
Requisição
Requisição HTTP
PATCH 'https://api-mtls.sandbox.bankly.com.br/customers/{documentNumber}'
curl --location
--request PATCH 'https://api-mtls.sandbox.bankly.com.br/customers/{documentNumber}' \
--header 'api-version: 1' \
--header 'Content-Type: application/json' \
--data-raw ' {
"data": {
"email": "[email protected]",
"socialName": "",
"phone": {
"countryCode": "+55",
"number": "23415162342"
},
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"buildingNumber": "2500",
"complement": "",
"neighborhood": "Alter do Chão",
"city": "Santarém",
"state": "PA",
"country": "Brasil"
},
"declaredIncome": "LESS_THAN_ONE_THOUSAND",
"assertedIncome": {
"currency": "BRL",
"value": 500000
},
"pep": {
"level": "NONE"
},
"occupation": "OCP0001"
}
}'
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 |
---|---|
customer.update | Concede acesso para atualização cadastral de cliente pessoa física. |
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-correlation-id | Informe um GUID, 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 | path | Obrigatório. Número do documento CPF do cliente pessoa física. |
Corpo da requisição (Body)
No body, envie os seguintes campos em formato JSON:
Nome | Tipo | Descrição | Especificação |
---|---|---|---|
email | string | Novo endereço de e-mail. Recordamos que um mesmo e-mail não poderá ser usado por dois clientes. | — |
socialName | string | Nome social, ou seja, a forma pela qual o cliente gostaria de ser chamado, sem caracteres especiais. | — |
phone | objeto | Objeto onde devem ser informados os novos dados de telefone do cliente. Recordamos que um mesmo número de telefone não poderá ser usado por dois clientes. | — |
phone.countryCode | string | Código DDI do país. Atente-se à lista de países bloqueados para Onboarding. | — |
phone.number | string | Número de telefone incluindo DDD. | — |
address | objeto | Objeto onde devem ser informados novos os dados de endereço do cliente. | — |
address.zipcode | string | Código postal do endereço. | — |
address.addressLine | string | Logradouro (nome da rua, avenida etc.). | Máximo de 256 caracteres. |
address.buildingNumber | string | Número do imóvel com até 10 caracteres (se não existir, substitua por “S/N”). | — |
address.complement | string | Complemento do endereço. | — |
address.neighborhood | string | Nome do bairro ou distrito. | Máximo de 256 caracteres. |
address.city | string | Nome da cidade. | Máximo de 256 caracteres. Devem-se evitar acentos e outros caracteres especiais. |
address.state | string | Sigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: MG. | — |
address.country | string | Sigla do país conforme a ISO 3166-2. Exemplo: BR. | — |
declaredIncome | string | Faixa de renda atualizada declarada pelo cliente. Importante: campo obsoleto em produção a partir do dia 27/11/2023. Deve ser substituído pelo objeto assertedIncome . | — |
assertedIncome | object | Objeto que contém dados da renda do cliente. | — |
assertedIncome.value | number | Valor em Reais da renda declarada pelo cliente. | O valor mínimo para esse campo é de: 0.00, e o valor máximo: 99999999999999.99 (até 14 caracteres antes do ponto e até dois caracteres após o ponto). |
assertedIncome.currency | string | Moeda da renda declarada. | O valor padrão é BRL. |
pep | objeto | Objeto onde deve ser informado o nível de exposição política do cliente atualizado, atendendo à Circular nº 3.978. | — |
pep.level | string | Nível de exposição política do cliente: "NONE" (o cliente não é e nem tem vínculo com pessoa exposta politicamente), "SELF" (o cliente é pessoa exposta politicamente) e "RELATED" (o cliente tem vínculo familiar, possui sociedade ou é estreito colaborador de pessoa exposta politicamente). | — |
occupation | string | Código de ocupação do cliente atualizado. | — |
Importante
Não é preciso enviar os campos referentes aos dados que não serão atualizados. Porém, ao atualizar uma informação representada por um objeto, é obrigatório enviar todas as suas propriedades (como é o caso do telefone, por exemplo).
{
"data": {
"email": "[email protected]",
"socialName": "",
"phone": {
"countryCode": "+55",
"number": "23415162342"
},
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"buildingNumber": "2500",
"complement": "",
"neighborhood": "Alter do Chão",
"city": "Santarém",
"state": "PA",
"country": "Brasil"
},
"declaredIncome": "LESS_THAN_ONE_THOUSAND",
"assertedIncome": {
"currency": "BRL",
"value": 500000
},
"pep": {
"level": "NONE"
},
"occupation": "OCP0001"
}
}
Países bloqueados para Onboarding
Reafirmando o compromisso do Bankly com a segurança, prevenção à lavagem de dinheiro e combate ao terrorismo, vetamos o registro de clientes cujos DDIs sejam provenientes dos países listados abaixo:
Países bloqueados
Código DDI | País |
---|---|
008 | Albânia |
070 | Bósnia e Herzegovina |
100 | Bulgária |
108 | Burundi |
112 | Bielorrússia |
140 | República Centro-Africana |
178 | República do Congo |
180 | República Democrática do Congo |
191 | Croácia |
192 | Cuba |
364 | Irã |
368 | Iraque |
408 | Coréia do Norte |
422 | Líbano |
434 | Líbia |
499 | Montenegro |
642 | Romênia |
643 | Federação Russa |
688 | Sérvia |
705 | Eslovênia |
706 | Somália |
716 | Zimbábue |
728 | Sudão do Sul |
729 | Sudão |
760 | Síria |
807 | República da Macedônia do Norte |
862 | Venezuela |
887 | Iémen |
(Fonte: dados agrupados com base nas listas do Conselho Nacional das Nações Unidas - CSNU e do Office of Foreign Assets Control - OFAC)
Resposta (Response)
O status code 200 indicará que o cadastro foi alterado com sucesso.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
Nome | Tipo | Descrição |
---|---|---|
data | object | Objeto que encapsula o corpo de retorno da requisição. |
data.documentNumber | string | Número de documento de CPF. (Obsoleto. Considere o campo document.value ). |
data.document | object | Objeto que contém informações sobre o documento do cliente. |
data.document.value | string | Número do documento. |
data.document.type | string | Tipo do documento. No caso, “CPF”. |
data.profile | string | Perfil do cliente, baseado no registro do cliente, o qual pode ser "SIMPLE" ou "COMPLETE". |
data.status | string | Status do registro do cliente. |
data.registerName | string | Nome conforme consta no documento de identificação (RG, CNH, RNE, DNI ou CRNM) do cliente. |
data.socialName | string | Nome social informado no registro do cliente ou atualizado. |
data.phone | objeto | Objeto que contém informações sobre o telefone do cliente, informado em seu registro ou atualizado. |
data.phone.countryCode | string | Código DDI do país. |
data.phone.number | string | Número de telefone incluindo DDD. |
data.address | objeto | Objeto que contém informações sobre o endereço do cliente, informado em seu registro ou atualizado. |
data.address.zipcode | string | Código postal do endereço. |
data.address.addressLine | string | Logradouro (nome da rua, avenida etc.). |
data.address.buildingNumber | string | Número do imóvel. |
data.address.complement | string | Complemento do endereço |
data.address.neighborhood | string | Nome do bairro ou distrito. |
data.address.city | string | Nome da cidade. |
data.address.state | string | Sigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: MG. |
data.address.country | string | Sigla do país conforme a ISO 3166-2. Exemplo: BR. |
data.email | string | E-mail de contato do cliente, informado em seu registro ou atualizado. |
data.motherName | string | Nome da mãe informado no registro do cliente. |
data.declaredIncome | string | Faixa de renda declarada pelo cliente, informada em seu registro ou atualizada. |
data.assertedIncome | object | Objeto que contém dados da renda do cliente. |
data.assertedIncome.currency | number | Valor em Reais da renda declarada pelo cliente. |
data.assertedIncome.value | string | Moeda da renda declarada. O valor padrão é BRL. |
data.confirmedIncome | string | Indica se o valor informado da renda foi confirmado no bureau de informação. O valor padrão desse campo é "null". |
data.occupation | string | Código de ocupação do cliente, informado em seu registro ou atualizado. |
data.pep | objeto | Objeto que contém o nível de exposição política do cliente, informado em seu registro ou atualizado. |
data.pep.level | string | Nível de exposição política do cliente: "NONE" (o cliente não é e nem tem vínculo com pessoa exposta politicamente), "SELF" (o cliente é pessoa exposta politicamente) e "RELATED" (o cliente tem vínculo familiar, possui sociedade ou é estreito colaborador de pessoa exposta politicamente). |
data.pep.verified | boolean | Indica se a situação de vínculo com pessoa politicamente exposta foi verificada no bureau de informação. O valor padrão desse campo é "false". |
data.documentation | object | Objeto que contém as informações referente aos documentos enviados para análise. Essas referências são retornadas no endpoint de Envio e análise de documentos pessoais. |
data.documentation.selfie | string | Token retornado na análise da Selfie. |
data.documentation.idCardFront | string | Token retornado na análise da frente do documento. |
data.documentation.idCardBack | string | Token retornado na análise do verso do documento. |
data.birthDate | datetime | Data de nascimento do cliente, no formato ISO 8601 - UTC. |
data.createdAt | datetime | Data do primeiro registro do cliente, no formato ISO 8601 - UTC. |
data.updatedAt | datetime | Data da atualização do registro do cliente, no formato ISO 8601 - UTC. |
Nota
Além do objeto
data
, o retorno trará uma lista (array of objects
) que contém objetos referente ao HATEOS. Eles representam as possíveis operações que podem ser realizadas dentro do contexto do customer.
{
"data": {
"documentNumber": "47742663023",
"document": {
"value": "47742663023",
"type": "CPF"
},
"profile": "COMPLETE",
"status": "APPROVED",
"registerName": "Nísia Floresta",
"socialName": "",
"phone": {
"countryCode": "55",
"number": "23415162342"
},
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"buildingNumber": "2500",
"complement": "",
"neighborhood": "Alter do Chão",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"email": "[email protected]",
"motherName": "Dionísia Gonçalves Pinto",
"declaredIncome": "LESS_THAN_ONE_THOUSAND",
"assertedIncome": {
"currency": "BRL",
"value": 500000
},
"confirmedIncome": "",
"occupation": "OCP0001",
"pep": {
"level": "NONE",
"verified": true
},
"documentation": {
"selfie": "ce1849509a3f4625867ead5768d5b068",
"idCardFront": "9c1974193d96446e84833742aed1db62",
"idCardBack": "71bb6d35ee7644fe8ef2b8e81eb19f98"
},
"birthDate": "1810-10-12T20:49:18.591Z",
"createdAt": "2023-01-04T20:49:18.591Z",
"updatedAt": "2023-01-54T20:49:18.591Z"
},
"links": [
{
"url": "/api/customers/{documentNumber}",
"rel": "update_customer",
"method": "PATCH"
},
{
"url": "/api/customers/{documentNumner}",
"rel": "get_customer",
"method": "GET"
},
{
"url": "/api/customers/{documentNumber}/cancel",
"rel": "cancel_customer",
"method": "PATCH"
},
{
"url": "/api/customers/{documentNumber}",
"rel": "replace_customer",
"method": "PUT"
}
]
}
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 | CUSTOMER_NOT_FOUND | Customer not found. | Cliente não encontrado. |
422 | CUSTOMER_AWAIT_EVALUATION | Customer await evaluation. | O registro do cliente está em análise. |
422 | CUSTOMER_REGISTRATION_CANCELED | Customer registration was canceled. | O registro do cliente foi cancelado. |
422 | CUSTOMER_REGISTRATION_REPROVED | Customer registration was reproved. | O registro do cliente foi reprovado. |
422 | CUSTOMER_BLOCKED | Customer is blocked. | O registro do cliente foi bloqueado. |
422 | CUSTOMER_REVOKED | Customer is revoked. | O registro do cliente foi revogado. |
422 | INVALID_OCCUPATION | Occupation provided is invalid. | O código de ocupação do cliente é inválido. |
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 |
---|---|
CUSTOMER_WAS_UPDATED | O cadastro do cliente foi atualizado. |
Updated 6 months ago