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:

ScopeDescrição
customer.updateConcede acesso para atualização cadastral de cliente pessoa física.

Cabeçalhos (Headers)

NomeDescriçã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-correlation-idInforme um GUID, sendo um novo cada requisição.

Parâmetros da rota (Path)

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

NomeTipoDescrição
documentNumberpathObrigató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:

NomeTipoDescriçãoEspecificação
emailstring Novo endereço de e-mail. Recordamos que um mesmo e-mail não poderá ser usado por dois clientes.
socialNamestringNome social, ou seja, a forma pela qual o cliente gostaria de ser chamado, sem caracteres especiais.
phoneobjetoObjeto 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.countryCodestringCódigo DDI do país. Atente-se à lista de países bloqueados para Onboarding.
phone.numberstringNúmero de telefone incluindo DDD.
addressobjetoObjeto onde devem ser informados novos os dados de endereço do cliente.
address.zipcodestringCódigo postal do endereço.
address.addressLine stringLogradouro (nome da rua, avenida etc.).Máximo de 256 caracteres.
address.buildingNumber stringNúmero do imóvel com até 10 caracteres (se não existir, substitua por “S/N”).
address.complementstringComplemento do endereço.
address.neighborhoodstringNome do bairro ou distrito.Máximo de 256 caracteres.
address.citystringNome da cidade.Máximo de 256 caracteres. Devem-se evitar acentos e outros caracteres especiais.
address.state stringSigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: MG.
address.countrystringSigla do país conforme a ISO 3166-2. Exemplo: BR.
declaredIncome stringFaixa 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.
assertedIncomeobjectObjeto que contém dados da renda do cliente.
assertedIncome.valuenumberValor 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.currencystringMoeda da renda declarada.O valor padrão é BRL.
pepobjetoObjeto onde deve ser informado o nível de exposição política do cliente atualizado, atendendo à Circular nº 3.978.
pep.levelstringNí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).
occupationstringCó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 DDIPaís
008Albânia
070Bósnia e Herzegovina
100Bulgária
108Burundi
112Bielorrússia
140República Centro-Africana
178República do Congo
180República Democrática do Congo
191Croácia
192Cuba
364Irã
368Iraque
408Coréia do Norte
422Líbano
434Líbia
499Montenegro
642Romênia
643Federação Russa
688Sérvia
705Eslovênia
706Somália
716Zimbábue
728Sudão do Sul
729Sudão
760Síria
807República da Macedônia do Norte
862Venezuela
887Ié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:

NomeTipoDescrição
dataobjectObjeto que encapsula o corpo de retorno da requisição.
data.documentNumberstringNúmero de documento de CPF. (Obsoleto. Considere o campo document.value).
data.documentobjectObjeto que contém informações sobre o documento do cliente.
data.document.valuestringNúmero do documento.
data.document.typestringTipo do documento. No caso, “CPF”.
data.profilestringPerfil do cliente, baseado no registro do cliente, o qual pode ser "SIMPLE" ou "COMPLETE".
data.statusstring Status do registro do cliente.
data.registerNamestringNome conforme consta no documento de identificação (RG, CNH, RNE, DNI ou CRNM) do cliente.
data.socialName stringNome social informado no registro do cliente ou atualizado.
data.phoneobjetoObjeto que contém informações sobre o telefone do cliente, informado em seu registro ou atualizado.
data.phone.countryCodestringCódigo DDI do país.
data.phone.numberstringNúmero de telefone incluindo DDD.
data.addressobjetoObjeto que contém informações sobre o endereço do cliente, informado em seu registro ou atualizado.
data.address.zipcodestringCódigo postal do endereço.
data.address.addressLine stringLogradouro (nome da rua, avenida etc.).
data.address.buildingNumber stringNúmero do imóvel.
data.address.complementstringComplemento do endereço
data.address.neighborhoodstringNome do bairro ou distrito.
data.address.citystringNome da cidade.
data.address.state stringSigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: MG.
data.address.countrystringSigla do país conforme a ISO 3166-2. Exemplo: BR.
data.emailstringE-mail de contato do cliente, informado em seu registro ou atualizado.
data.motherNamestringNome da mãe informado no registro do cliente.
data.declaredIncomestring Faixa de renda declarada pelo cliente, informada em seu registro ou atualizada.
data.assertedIncomeobjectObjeto que contém dados da renda do cliente.
data.assertedIncome.currencynumberValor em Reais da renda declarada pelo cliente.
data.assertedIncome.valuestringMoeda da renda declarada. O valor padrão é BRL.
data.confirmedIncomestringIndica se o valor informado da renda foi confirmado no bureau de informação. O valor padrão desse campo é "null".
data.occupationstring Código de ocupação do cliente, informado em seu registro ou atualizado.
data.pepobjetoObjeto que contém o nível de exposição política do cliente, informado em seu registro ou atualizado.
data.pep.levelstringNí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.verifiedbooleanIndica 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.documentationobjectObjeto 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.selfiestringToken retornado na análise da Selfie.
data.documentation.idCardFrontstringToken retornado na análise da frente do documento.
data.documentation.idCardBackstring Token retornado na análise do verso do documento.
data.birthDatedatetime Data de nascimento do cliente, no formato ISO 8601 - UTC.
data.createdAtdatetimeData do primeiro registro do cliente, no formato ISO 8601 - UTC.
data.updatedAtdatetimeData 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 CodeCódigoMensagemDescrição
404CUSTOMER_NOT_FOUNDCustomer not found.Cliente não encontrado.
422CUSTOMER_AWAIT_EVALUATIONCustomer await evaluation.O registro do cliente está em análise.
422CUSTOMER_REGISTRATION_CANCELEDCustomer registration was canceled.O registro do cliente foi cancelado.
422CUSTOMER_REGISTRATION_REPROVEDCustomer registration was reproved.O registro do cliente foi reprovado.
422CUSTOMER_BLOCKEDCustomer is blocked.O registro do cliente foi bloqueado.
422CUSTOMER_REVOKEDCustomer is revoked.O registro do cliente foi revogado.
422INVALID_OCCUPATIONOccupation 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 eventoDescrição
CUSTOMER_WAS_UPDATEDO cadastro do cliente foi atualizado.