> ## 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.

# Visão Geral de Contas

> Entendendo e gerenciando contas de pagamento

## O que são Contas?

Contas representam destinos ou origens de fundos em transações ramp. Os usuários podem ter múltiplas contas de diferentes tipos para suportar vários métodos de pagamento e casos de uso.

<Info>
  Cada conta está vinculada a um usuário específico e deve ser verificada antes de usar em transações.
</Info>

## Tipos de Conta

<CardGroup cols={2}>
  <Card title="Contas Bancárias" icon="building-columns" href="/pt/guides/accounts/bank-accounts">
    **PSE, SPEI, ACH, Wire**

    Contas bancárias fiat tradicionais para receber moeda local.

    Use para: Off-ramps (cripto → fiat)
  </Card>

  <Card title="Carteiras Cripto" icon="wallet" href="/pt/guides/accounts/crypto-wallets">
    **USDC/USDT em múltiplas redes**

    Endereços de carteira blockchain para receber criptomoeda.

    Use para: On-ramps (fiat → cripto)
  </Card>
</CardGroup>

## Início Rápido

<Steps>
  <Step title="Criar Usuário">
    Usuários devem existir antes de adicionar contas

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

  <Step title="Escolher Tipo de Conta">
    Conta bancária para off-ramps, carteira para on-ramps
  </Step>

  <Step title="Criar Conta">
    Enviar detalhes da conta

    ```bash theme={null}
    POST /api/v2/accounts
    ```
  </Step>

  <Step title="Aguardar Verificação">
    O status da conta muda para ACTIVE após verificação
  </Step>

  <Step title="Usar em Ramps">
    Referenciar ID da conta ao criar ramps
  </Step>
</Steps>

## Criando Contas

### Exemplo de Conta Bancária

```json theme={null}
{
  "type": "PSE",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "bank-account-1",
  "data": {
    "firstName": "João",
    "lastName": "Silva",
    "email": "joao@example.com",
    "phone": "+5511987654321",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "BR",
    "document": {
      "type": "CPF",
      "number": "12345678900",
      "issuedCountryCode": "BR"
    }
  }
}
```

### Exemplo de Conta de Carteira

```json theme={null}
{
  "type": "WALLET",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "wallet-1",
  "data": {
    "firstName": "João",
    "lastName": "Silva",
    "email": "joao@example.com",
    "phone": "+5511987654321",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "BR",
    "document": {
      "type": "CPF",
      "number": "12345678900",
      "issuedCountryCode": "BR"
    }
  }
}
```

## Consultando Contas

### Obter Todas as Contas do Usuário

```bash theme={null}
GET /api/v2/accounts/userId/{userId}
```

```javascript theme={null}
const getUserAccounts = async (userId) => {
  const response = await fetch(
    `https://sandbox.killb.app/api/v2/accounts/userId/${userId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return await response.json();
};
```

### Pesquisar Contas

```bash theme={null}
GET /api/v2/accounts?userId=user-id&type=WALLET
```

**Filtros:**

* `ids` - IDs de conta específicos (separados por vírgula)
* `userId` - Filtrar por usuário
* `type` - Tipo de conta
* `accountNumber` - Número da conta bancária
* `address` - Endereço da carteira
* `limit`, `page` - Paginação

## Atualizando Contas

Campos limitados podem ser atualizados após a criação:

```bash theme={null}
PATCH /api/v2/accounts/{accountId}
```

<CodeGroup>
  ```json Atualizar Conta PSE theme={null}
  {
    "type": "PSE",
    "data": {
      "accountNumber": "9876543210",
      "bankCode": "0002",
      "type": "checking"
    }
  }
  ```

  ```json Atualizar Carteira theme={null}
  {
    "type": "WALLET",
    "data": {
      "address": "0xNOVO_ENDERECO_AQUI",
      "network": "SOLANA"
    }
  }
  ```
</CodeGroup>

<Note>
  Atualizar certos campos pode exigir re-verificação e definir o status da conta de volta para PENDING.
</Note>

## Excluindo Contas

```bash theme={null}
DELETE /api/v2/accounts/{accountId}
```

<Warning>
  Contas usadas em ramps pendentes ou em processamento não podem ser excluídas.
</Warning>

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Validar Antes de Criar" icon="check-double">
    ```javascript theme={null}
    // Verificar se código do banco existe
    const banks = await getBanks('BR');
    const validBank = banks.find(b => b.code === bankCode);

    // Validar formato do endereço da carteira
    const isValidAddress = /^0x[a-fA-F0-9]{40}$/.test(address);

    // Verificar duplicatas
    const existing = await findAccount({ userId, address });
    ```
  </Accordion>

  <Accordion title="Usar IDs Externos" icon="hashtag">
    ```javascript theme={null}
    {
      "externalId": `${yourUserId}-wallet-polygon-usdc`,
      // Facilita buscas e previne duplicatas
    }
    ```
  </Accordion>

  <Accordion title="Lidar com Atrasos de Verificação" icon="clock">
    ```javascript theme={null}
    if (account.status === 'PENDING') {
      showMessage('Verificação da conta em andamento');
      // Verifique novamente em 1 hora ou aguarde webhook
    }
    ```
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Contas Bancárias" icon="building-columns" href="/pt/guides/accounts/bank-accounts">
    Configure contas bancárias para diferentes países
  </Card>

  <Card title="Carteiras Cripto" icon="wallet" href="/pt/guides/accounts/crypto-wallets">
    Configure contas de carteira de criptomoeda
  </Card>

  <Card title="Contas Pré-Financiadas" icon="bolt" href="/pt/guides/accounts/pre-fund-accounts">
    Habilite liquidações instantâneas
  </Card>

  <Card title="Referência da API" icon="code" href="/api-reference/endpoint/accounts-create">
    Documentação completa da API de Contas
  </Card>
</CardGroup>