Atualização cadastral

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.

Atualização cadastral

📘
Nota

Pré-requisito

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

🚧
Importante

Países bloqueados para Onboarding

Resposta (Response)

📘
Nota

👍
Dica

Erros

Eventos

📘Nota

Pré-requisito

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

🚧Importante

Países bloqueados para Onboarding

Resposta (Response)

📘Nota

👍Dica

Erros

Eventos

📘
Nota

🚧
Importante

📘
Nota

👍
Dica