Clientes

Um cliente é o titular (pessoa física ou jurídica) dono de uma ou mais contas. Ao criar um cliente, a VULCI Banco abre a primeira conta e roda a análise de conformidade. O parceiro só enxerga os clientes que ele mesmo criou.

Cadastrar cliente

Cria o titular e a primeira conta em uma única operação.

POST /api/partner/v1/customers
Authorization: Bearer {{access_token}}
Content-Type: application/json
Idempotency-Key: {{uuid}}

{
  "document": "56936427200",
  "name": "Maria de Souza",
  "password": "S3nh@Forte!2026",
  "email": "maria@exemplo.com.br",
  "phone": "+5511999998888",
  "user_type": "member_pf",
  "account_type": "payment"
}

• Escopo: customer:create
• Obrigatórios: document, name, password.
• Opcionais: email, phone, login, user_type, account_type, kyc.

Campo document

O document (CPF ou CNPJ) é gravado como identificador do titular. Formato aceito: CPF com 11 dígitos ou CNPJ com 14 (o novo CNPJ alfanumérico segue o padrão de 12 posições alfanuméricas em maiúsculas seguidas de 2 dígitos). Envie apenas os dígitos, sem pontos, barras ou hífens. Um documento fora desse formato responde 422.

Tipo de titular (user_type)

user_type	Titular
member_pf (padrão)	Pessoa física
member_pj	Pessoa jurídica

Se omitido, assume member_pf.

Tipo de conta (account_type)

Veja a lista de tipos aceitos em Contas e saldo. Se omitido, assume payment.

Resposta 201:

{
  "data": {
    "id": 25165,
    "name": "Maria de Souza",
    "document": "56936427200",
    "status": "active",
    "partner_id": "6b70e220-63e8-462b-bd5e-dfb96e4bbb7f",
    "kyc": {
      "outcome": "active",
      "edd_required": false,
      "sanctions_hit": false,
      "pep_hit": false,
      "compliance_case_id": "c38a0710-bcf1-47c9-ab88-f0a275cee9ed"
    },
    "accounts": [
      { "id": 10024283, "kind": 3, "account_type": "payment", "agency": "0001", "account_number": "119341-4", "status": "active" }
    ]
  }
}

Conta em análise

A criação passa por verificação de conformidade. Quando a análise aponta risco (sanções ou PEP), o kyc.outcome vem "blocked", o kyc.edd_required vem true e a conta nasce bloqueada para movimentação até a conclusão. Acompanhe pelo status da conta.

Consultar cliente

GET /api/partner/v1/customers/{id}
Authorization: Bearer {{access_token}}

• Escopo: customer:read

{
  "data": {
    "id": 25165,
    "name": "Maria de Souza",
    "document": "56936427200",
    "status": "active",
    "partner_id": "6b70e220-...",
    "kyc": { "status": "active", "risk_level": "low", "is_pep": false, "last_reviewed_at": "2026-07-11T02:25:00Z", "edd_required": false },
    "accounts": [ { "id": 10024283, "kind": 3, "account_type": "payment", "agency": "0001", "account_number": "119341-4", "status": "active" } ]
  }
}

Um id desconhecido ou de outro parceiro responde 404.

Abrir conta adicional

Um mesmo titular pode ter várias contas.

POST /api/partner/v1/customers/{id}/accounts
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_type": "savings" }

• Escopo: account:write
• Aceita account_type (obrigatório o valor ser válido), agency e account_number (opcionais).

Resposta 201:

{ "data": { "id": 10024284, "kind": 3, "account_type": "savings", "agency": "0001", "account_number": "119342-2", "status": "active" } }

Um account_type fora da lista responde 422 com invalid account_type. Um cliente de outro parceiro responde 404.