> ## Documentation Index
> Fetch the complete documentation index at: https://docs.killb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usuários

> Entendendo gerenciamento de usuários e KYC na KillB

## O que é um Usuário?

Um **Usuário** na KillB representa um indivíduo ou entidade empresarial que pode realizar transações ramp. Os usuários são obrigados a completar a verificação Know Your Customer (KYC) ou Know Your Business (KYB) antes de transacionar.

<Info>
  Toda transação na KillB deve estar associada a um usuário verificado para cumprir requisitos regulatórios.
</Info>

## Tipos de Usuário

<Tabs>
  <Tab title="PERSON">
    Usuários individuais (pessoas físicas)

    **Informações Requeridas:**

    * Nome completo (primeiro, meio, último)
    * Data de nascimento
    * Email e telefone
    * Endereço físico
    * ID emitido pelo governo
    * Nacionalidade e cidadania

    **Casos de Uso:**

    * Remessas pessoais
    * Investimentos individuais
    * Compras de cripto pessoais

    **Exemplo:**

    ```json theme={null}
    {
      "type": "PERSON",
      "data": {
        "firstName": "João",
        "lastName": "Silva",
        "dateOfBirth": "1990-05-15",
        "email": "joao@example.com",
        "phone": "+5511987654321",
        "document": {
          "type": "CPF",
          "number": "12345678900",
          "issuedCountryCode": "BR"
        }
      }
    }
    ```
  </Tab>

  <Tab title="COMPANY">
    Entidades empresariais e corporações

    **Informações Requeridas:**

    * Nome da empresa e nome comercial
    * Número de registro
    * Estrutura legal
    * Endereço comercial
    * ID fiscal (NIT, EIN, RFC, etc.)
    * Informações do proprietário

    **Casos de Uso:**

    * Pagamentos empresariais
    * Tesouraria corporativa
    * Transações B2B
    * Serviços de folha de pagamento

    **Exemplo:**

    ```json theme={null}
    {
      "type": "COMPANY",
      "data": {
        "companyName": "Acme Corp SAS",
        "tradeName": "Acme",
        "registeredNumber": "900123456",
        "legalStructure": "LLC",
        "email": "business@acme.com",
        "document": {
          "type": "NIT",
          "number": "900123456-1",
          "issuedCountryCode": "CO"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Status do Usuário

Os usuários podem ter diferentes status:

| Status     | Descrição                     | Pode Transacionar? |
| ---------- | ----------------------------- | ------------------ |
| `ACTIVE`   | Usuário verificado e aprovado | ✅ Sim              |
| `PENDING`  | Documentos KYC sob revisão    | ❌ Não              |
| `REJECTED` | Verificação KYC falhou        | ❌ Não              |

<Tip>
  Controle todas as operações com `status === ACTIVE`. Se um usuário estiver `PENDING`, envie-o para `complianceUrl` para completar a verificação.
</Tip>

## Documentos Requeridos

### Documentos de Pessoa

<Tabs>
  <Tab title="Colômbia">
    * **NUIP** (Número Único de Identificación Personal)
    * **Cédula de Ciudadanía** (CC)
    * **Passaporte**
    * **Carteira de Motorista**
  </Tab>

  <Tab title="México">
    * **INE** (Instituto Nacional Electoral)
    * **IFE** (versão antiga do INE)
    * **Passaporte**
    * **RFC** (Tax ID)
    * **CURP** (ID do Registro de População)
  </Tab>

  <Tab title="Brasil">
    * **CPF** (Cadastro de Pessoas Físicas)
    * **RG** (Registro Geral)
    * **CNH** (Carteira Nacional de Habilitação)
    * **Passaporte**
  </Tab>

  <Tab title="Outros Países">
    * **Passaporte** (Universalmente aceito)
    * **Carteira de Identidade Nacional**
    * **DNI** (Documento Nacional de Identidad)
  </Tab>
</Tabs>

### Documentos da Empresa

* **NIT** (Colômbia) - Número de identificação fiscal
* **RFC** (México) - Registro federal de contribuintes
* **EIN** (EUA) - Número de identificação do empregador
* **CNPJ** (Brasil) - Cadastro Nacional da Pessoa Jurídica
* **CUIT** (Argentina) - Código único de identificação tributária

## ID Externo

O campo `externalId` permite que você vincule usuários KillB ao seu próprio sistema de usuários:

```json theme={null}
{
  "type": "PERSON",
  "externalId": "user_abc123_do_meu_sistema",
  "data": { ... }
}
```

**Benefícios:**

* Mapear usuários KillB para seu banco de dados
* Evitar criação de usuário duplicado
* Simplificar buscas de usuário
* Manter integridade referencial

<Tip>
  Use seu ID de usuário interno como `externalId` para fácil mapeamento entre sistemas.
</Tip>

## Propriedades do Usuário

### Campos Principais

| Campo           | Tipo   | Obrigatório | Descrição                       |
| --------------- | ------ | ----------- | ------------------------------- |
| `id`            | UUID   | Auto        | ID do usuário gerado pela KillB |
| `type`          | Enum   | ✅           | PERSON ou COMPANY               |
| `status`        | Enum   | Auto        | ACTIVE, PENDING, REJECTED       |
| `customerId`    | UUID   | Auto        | Seu ID de cliente               |
| `externalId`    | String | Opcional    | ID do usuário no seu sistema    |
| `complianceUrl` | URL    | Auto        | Portal de verificação KYC       |

### Campos Específicos de Pessoa

* `firstName`, `middleName`, `lastName`
* `dateOfBirth`
* `nationality`, `citizenship`
* `employmentStatus`, `occupation`
* `employerName`, `employmentDescription`

### Campos Específicos de Empresa

* `companyName`, `tradeName`
* `registeredNumber`
* `legalStructure` (LLC, C\_CORP, S\_CORP, etc.)
* `establishedOn`
* `naics`, `naicsDescription`
* `mainOwnerUser`, `ownerUsers[]`

## Perfil de Investimento

Os usuários devem fornecer um perfil de investimento para fins de compliance:

```json theme={null}
{
  "investmentProfile": {
    "primarySourceOfFunds": "EMPLOYMENT",
    "primarySourceOfFundsDescription": "Software engineer salary",
    "totalAssets": "TEN_TO_100K",
    "usdValueOfFiat": "TEN_TO_100K",
    "monthlyDeposits": "UPTO_5",
    "monthlyWithdrawals": "UPTO_5",
    "monthlyInvestmentDeposit": "ONE_TO_100K",
    "monthlyInvestmentWithdrawal": "UPTO_1K",
    "usdValueOfCrypto": "TEN_TO_100K",
    "monthlyCryptoDeposits": "UPTO_5",
    "monthlyCryptoWithdrawals": "UPTO_5"
  }
}
```

### Opções de Origem de Fundos

* `EMPLOYMENT` - Salário/remuneração
* `SAVINGS` - Poupança pessoal
* `INVESTMENT` - Renda de investimentos
* `COMPANY` - Receita empresarial
* `REAL_ESTATE` - Renda imobiliária
* `TRUST` - Fundo fiduciário
* `OTHER` - Outras fontes

## Perfil KYC

Informações de prevenção à lavagem de dinheiro e compliance:

```json theme={null}
{
  "kycProfile": {
    "fundsSendReceiveJurisdictions": ["CO", "US", "MX"],
    "engageInActivities": ["NONE"]
  }
}
```

### Atividades Proibidas

Os usuários devem confirmar que não participam de:

* `ADULT_ENTERTAINMENT`
* `DRUGS`
* `FIREARMS`
* `GAMBLING`
* `MARIJUANA`
* `TUMBLING` (mistura de criptoativos)

## Gerenciando Usuários

### Criar um Usuário

```bash theme={null}
POST /api/v2/users
```

Veja o [Guia de Criação de Usuário](/pt/guides/users/create-user) para exemplos detalhados.

### Consultar Usuários

```bash theme={null}
GET /api/v2/users?type=PERSON&email=usuario@example.com
```

**Opções de Filtro:**

* `type` - PERSON ou COMPANY
* `firstName`, `lastName`, `email`
* `externalId` - Seu ID de sistema
* `customerId` - Filtrar por cliente

### Atualizar Usuário

```bash theme={null}
PATCH /api/v2/users/{userId}
```

Atualize informações do usuário, faça upload de documentos adicionais ou modifique dados de perfil.

### Excluir Usuário

```bash theme={null}
DELETE /api/v2/users/{userId}
```

<Warning>
  A exclusão de usuário é uma exclusão suave. Os dados do usuário são retidos para compliance mas marcados como inativos.
</Warning>

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Coletar Informações Precisas" icon="clipboard-check">
    * Valide formatos de dados antes do envio
    * Garanta que os nomes correspondam exatamente aos IDs do governo
    * Use formato correto de número de telefone (+\[código do país]\[número])
    * Verifique endereços de email
    * Confirme que os endereços estão completos e precisos
  </Accordion>

  <Accordion title="Usar IDs Externos" icon="link">
    * Sempre forneça um `externalId`
    * Use seu ID de usuário interno
    * Permite buscas e reconciliação fáceis
    * Previne criação de usuário duplicado
  </Accordion>

  <Accordion title="Lidar com Estados KYC" icon="hourglass">
    * Verifique `status` antes de permitir transações
    * Guie usuários para o próximo passo de verificação
    * Monitore `complianceUrl` para atualizações KYC
  </Accordion>

  <Accordion title="Armazenar IDs de Usuário" icon="database">
    * Armazene o `userId` da KillB no seu banco de dados
    * Faça o mapeamento com o seu `externalId`
    * Faça cache dos dados do usuário de forma adequada
    * Sincronize mudanças de status via webhooks
  </Accordion>
</AccordionGroup>

## Perguntas Comuns

<AccordionGroup>
  <Accordion title="Uma pessoa pode ter múltiplos perfis de usuário?">
    Não. Cada indivíduo único deve ter apenas um perfil de usuário. Use o mesmo ID de usuário para todas as transações.
  </Accordion>

  <Accordion title="Quanto tempo leva a verificação KYC?">
    * **L0-L1:** Instantâneo (automatizado)\n    - **L2:** 1-24 horas (automatizado + revisão manual)\n    - **L3-L4:** 1-5 dias úteis (due diligence aprimorada)
  </Accordion>

  <Accordion title="Posso atualizar informações do usuário após a criação?">
    Sim, use o endpoint PATCH `/api/v2/users/{id}`. Alguns campos exigem nova verificação.
  </Accordion>

  <Accordion title="O que acontece se o KYC for rejeitado?">
    O status do usuário se torna `REJECTED` e ele não pode transacionar. Verifique o campo `note` para os motivos da rejeição. O usuário pode reenviar as informações corrigidas.
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Crie Seu Primeiro Usuário" icon="user-plus" href="/pt/guides/users/create-user">
    Siga o guia passo a passo para criar usuários
  </Card>

  <Card title="Entendendo Contas" icon="wallet" href="/pt/concepts/accounts">
    Aprenda sobre contas bancárias e carteiras
  </Card>

  <Card title="Referência da API" icon="code" href="/pt/api-reference/endpoint/users-create">
    Veja a documentação completa da API de Usuários
  </Card>
</CardGroup>