CADASTRO, RECADASTRAMENTO E ATUALIZAÇÃO CADASTRAL PF V2

Base URL: https://sandbox-nikos-api.nikos.com.br/api/v2
Autenticação: Authorization: Bearer <token>. Todos os endpoints exigem usuário autenticado.

ESCOLHA O MÉTODO CORRETO

Criação — POST /accounts/clients/pf/
Use para CPF ainda não cadastrado. Cria usuário, perfil, conta ativa e conta virtual. Retorna 201 Created.

Recadastramento — PUT /accounts/clients/pf/{cpf}/
Use para CPF existente, com o cadastro completo revisado. Atualiza dados mutáveis, fecha o recadastramento ativo e retorna 200 OK.

Atualização cadastral — PATCH /accounts/clients/pf/{cpf}/
Use apenas para os blocos que mudaram. Atualiza seletivamente, sem renovar a validade cadastral, e retorna 200 OK.

POST não é idempotente: se o CPF já existir, retorna 409 Conflict; não atualiza o cadastro. Para PUT, envie Idempotency-Key; reenvio idêntico é tratado pelo mecanismo de idempotência. Em PUT e PATCH, o CPF da URL prevalece sobre eventual CPF no corpo.

CORPO DA REQUISIÇÃO: NOVE BLOCOS

No POST e no PUT, os blocos obrigatórios devem ser enviados completos. No PATCH, envie somente os blocos alterados, exceto pelas regras específicas abaixo.

1. client_identification — obrigatório no POST/PUT
name (máx. 200), cpf (11 dígitos com DV válido), email, birth_date e mobile_phone (opcional; 11 dígitos). A pessoa deve ter ao menos 18 anos e a data de nascimento não pode ser futura.

2. personal_data — obrigatório no POST/PUT
nationality_id, gender (M ou F), marital_status_id, mother_name, father_name (opcional), birth_country e birth_city_ibge (string de 7 dígitos, obrigatório para nationality_id=1). Para estado civil 2 (casado) ou 6 (união estável), envie spouse.name e spouse.cpf.

3. identification_document — opcional
type_id, number, issuing_authority_id, issuing_uf, issue_date, expiration_date e cnh_security_code. CNH (type_id=2) exige cnh_security_code; documentos que requerem UF emissora exigem issuing_uf. Emissão não pode ser futura e validade não pode preceder a emissão.

4. residential_address — obrigatório no POST/PUT
zip_code (8 dígitos), street, number, neighborhood, city_ibge (string de 7 dígitos existente) e complement (opcional). No PATCH, o bloco é all-or-none: se enviado, contenha todos os campos obrigatórios.

5. professional_data — obrigatório no POST/PUT
occupation_id, employment_status (employed, self_employed, unemployed ou retired), company_name e employer_cnpj (opcionais). Para employment_status=employed, company_name é obrigatório; se informado, o CNPJ deve ser válido.

6. financial_data — obrigatório no POST/PUT
Envie as faixas net_asset e mensal_earnings. Os complementos aceitos são net_asset_value, mensal_earnings_other e total_other_assets_value.
• net_asset_value só é aceito quando net_asset=6.
• total_other_assets_value é obrigatório quando net_asset=0 e mensal_earnings=0.
• Valores monetários não podem ser negativos.
• gross_annual_income e total_financial_investments foram removidos e são rejeitados com 400.
• No PATCH, financial_data é all-or-none e exige net_asset e mensal_earnings quando presente.

7. bank_accounts — opcional
Lista de contas com bank_code, branch, account_number, account_digit, account_type (CC ou CP), is_joint_account, is_second_holder_main e co_holder_cpf. Conta conjunta exige co_holder_cpf válido. Não envie contas duplicadas pela combinação banco/agência/número/dígito/tipo.

8. suitability — opcional no POST/PUT; proibido no PATCH
Envie form_version_id e answers com choice_id. O questionário valida versão, escolhas e cobertura de perguntas obrigatórias. Sem questionário, accept_suitability_terms=true pode enquadrar automaticamente como Conservador apenas para novo cliente ou cliente sem investimentos de risco; nos demais casos o perfil fica Sem Perfil.

9. declarations_and_terms — obrigatório no POST/PUT
politically_exposed_person, us_person, qualified_investor, accept_suitability_terms e accept_registration_terms. Todos são booleanos. accept_registration_terms deve ser true; no POST/PUT, accept_suitability_terms é obrigatório.

RECADASTRAMENTO: CAMPOS IMUTÁVEIS E REGRAS DE NEGÓCIO

No PUT, o payload completo continua obrigatório, mas CPF, data de nascimento, nacionalidade, naturalidade (birth_city_ibge) e nome da mãe não são alterados pela persistência. São atualizáveis endereço, ocupação, empresa/CNPJ, contas bancárias, dados financeiros, telefone e e-mail. O recadastramento é recusado com 400 para perfil cancelado ou sem contas ativas.

RESPOSTAS E ERROS

201 Created (POST): retorno inclui user_profile_id, user_account_id, user_virtual_account_id, expiration_date e dados de suitability; há header Location.
200 OK (PUT/PATCH): mesma estrutura de retorno.
400 Bad Request: payload inválido, regra de negócio, suitability inválido ou campo removido.
404 Not Found: CPF inexistente em PUT/PATCH.
409 Conflict: CPF já existente no POST ou conflito de idempotência no PUT.

Os erros de validação são retornados em message e extra.fields.