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

# Contas conectadas

> Faça o onboarding dos seus próprios clientes finais (vendedores e compradores) em KYB/KYC pela API, servidor a servidor.

As contas conectadas permitem que você — o integrador — execute KYB (empresas) ou KYC (pessoas físicas) **em nome dos seus próprios clientes finais**, servidor a servidor, sem redirecionar ninguém para um fluxo hospedado. Cada conta conectada é um recebedor no nosso parceiro de liquidação que é privado da sua organização e vinculado a um modo (teste ou produção).

Dois papéis:

* **`seller`** — uma empresa ou pessoa física que vai *receber* pagamentos e liquidar na sua própria conta bancária/PIX. Na aprovação, a Caratuva provisiona os trilhos de liquidação para que o vendedor fique *pronto para repasses*.
* **`buyer`** — um pagador que você verifica antes de um pagamento.

<Note>
  Esta é a superfície de onboarding/verificação. A v1 deixa um **vendedor** conectado pronto para repasses (recebedor verificado + carteira de off-ramp + destino PIX registrado), mas rotear os fundos de um pedido de pagamento para um vendedor conectado — e permitir que um comprador conectado pague sem refazer o KYC — são etapas posteriores. O KYC do comprador para o fluxo de pagamento hospedado permanece inalterado ([Buyer KYC](/pt-BR/buyer-kyc)).
</Note>

## Autenticação e escopos

Todas as rotas usam sua chave de API (`X-API-Key: pk_<test|live>_...`). O prefixo da chave fixa o modo — uma conta conectada criada com uma chave `pk_test_` é invisível em produção e roteia para o sandbox do parceiro de liquidação. As rotas exigem o escopo correspondente (chaves sem escopos definidos não têm restrição, por compatibilidade retroativa):

| Escopo                     | Concede                                        |
| -------------------------- | ---------------------------------------------- |
| `connected_accounts:write` | create, ToS, upload-url, submit, payout-config |
| `connected_accounts:read`  | get, list                                      |

## O ciclo de vida

```
create ──▶ (tos-session ▶ tos-accepted) ──▶ [upload-url …] ──▶ submit ──▶ verifying ──▶ approved | rejected
                                                                                    │
                                                                 seller approved ───▶ settlement provisioned
                                                                                    └▶ payout-config (PIX)
```

Valores de `status`: `created` (casca local, ainda sem recebedor) · `verifying` (enviado ao parceiro de liquidação) · `approved` · `rejected`.

## 1. Criar

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/connected-accounts \
  -H "X-API-Key: $CARATUVA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "role": "seller",
    "entityType": "business",
    "externalId": "merchant-42",
    "legalName": "Acme Comércio LTDA",
    "country": "BR"
  }'
```

| Campo                                                   | Tipo                       | Obrigatório | Observações                                                                                                                                        |
| ------------------------------------------------------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `role`                                                  | `seller` \| `buyer`        | sim         | O que o cliente final fará depois de verificado.                                                                                                   |
| `entityType`                                            | `business` \| `individual` | sim         | Seleciona o caminho de verificação no `submit`.                                                                                                    |
| `externalId`                                            | string (1–200)             | não         | Sua chave primária para este cliente final. Único por `(org, mode)`. Recriar com o mesmo valor retorna a conta existente — seguro sob retentativa. |
| `email`, `legalName`, `displayName`, `country`, `taxId` | string                     | não         | Dicas de identidade; finalizadas no `submit`.                                                                                                      |

Retorna um `ConnectedAccount` com `status: "created"`.

## 2. Termos de Serviço (por cliente final)

Nosso parceiro de liquidação exige a aceitação dos Termos de Serviço antes que um recebedor possa ser criado. Crie uma sessão, direcione seu cliente final para a URL e registre o `tos_id` vindo do redirecionamento.

```bash theme={null}
# Mint a session
curl -X POST https://api.caratuva.com/v1/connected-accounts/{id}/tos-session \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "redirectUrl": "https://app.example.com/onboarding/{id}/tos-done" }'
# -> { "url": "https://...", "idempotencyKey": "..." }

# After the redirect carries ?tos_id=...
curl -X POST https://api.caratuva.com/v1/connected-accounts/{id}/tos-accepted \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "tosId": "tos_..." }'
```

O `tos-accepted` exige que uma sessão tenha sido criada primeiro (ela vincula o redirecionamento a esta conta, fechando a janela de replay do `tos_id` entre contas). Você também pode passar o `tosId` diretamente no `submit`; ele deve corresponder ao valor registrado.

## 3. Documentos (opcional)

Forneça suas próprias URLs HTTPS pré-hospedadas no corpo do `submit`, **ou** crie URLs de upload assinadas e de curta duração:

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/connected-accounts/{id}/upload-url \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "kind": "id_doc_front", "contentType": "image/jpeg" }'
# -> { uploadUrl, publicUrl, uploadHeaders, uploadMethod, expiresAt }
```

`kind`: `selfie` · `id_doc_front` · `id_doc_back` · `proof_of_address` · `incorporation_doc` · `proof_of_ownership_doc`. Para beneficiários finais de empresas, passe `ownerIndex` (um inteiro baseado em zero, 0–20). Faça o PUT dos bytes para `uploadUrl` com os headers retornados e, em seguida, passe `publicUrl` no `submit`. Retorna `503 KycStorageDisabled` se o armazenamento de documentos não estiver configurado — use URLs pré-hospedadas nesse caso.

## 4. Enviar ao parceiro de liquidação

Um único endpoint; os campos exigidos dependem de `(role, entityType)`. Campos ausentes retornam `400 ConnectedAccountMissingFields` com os caminhos problemáticos.

**Vendedor empresa** (`createKyb`, CNPJ brasileiro):

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/connected-accounts/{id}/submit \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "email": "ops@acme.com.br", "legalName": "Acme Comércio LTDA", "cnpj": "12345678000199" }'
```

**Pessoa física** (`createKyc`):

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/connected-accounts/{id}/submit \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane", "lastName": "Doe",
    "dateOfBirth": "1990-04-12",
    "idDocCountry": "US", "idDocType": "PASSPORT",
    "selfieFile": "https://...", "idDocFrontFile": "https://..."
  }'
```

**Comprador empresa** (`createBuyerKyb`) exige `legalName`, `formationDate`, `taxId`, `website`, `country`, campos de endereço, `incorporationDocFile`, `proofOfOwnershipDocFile` e ao menos um beneficiário final em `owners[]` (`role`, nome, `dateOfBirth`, `taxId`, endereço, `idDocType`, `selfieFile`, `idDocFrontFile`, `proofOfAddressDocType`, `proofOfAddressDocFile`).

O `submit` é idempotente enquanto a conta está `verifying`/`approved` — ele retorna o envio atual em vez de criar um segundo recebedor. No sandbox, o KYB é aprovado automaticamente; o KYC fica em `verifying` e é concluído via webhook.

## 5. Destino de repasse do vendedor (PIX)

Depois que um vendedor é aprovado, registre onde ele recebe os pagamentos. A chave PIX bruta é enviada ao nosso parceiro de liquidação e nunca é armazenada pela Caratuva.

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/connected-accounts/{id}/payout-config \
  -H "X-API-Key: $CARATUVA_API_KEY" -H "content-type: application/json" \
  -d '{ "pixKey": "acme@pix.example.com", "accountHolderName": "Acme Comércio LTDA" }'
```

Apenas para vendedores, e a conta precisa estar `approved` primeiro (caso contrário, `400 ConnectedAccountNotApproved`). Depois disso, a conta reporta `payoutConfigured: true`.

## Consultar

```bash theme={null}
curl https://api.caratuva.com/v1/connected-accounts/{id} -H "X-API-Key: $CARATUVA_API_KEY"
curl "https://api.caratuva.com/v1/connected-accounts?role=seller&status=approved&limit=50" \
  -H "X-API-Key: $CARATUVA_API_KEY"
```

O objeto `ConnectedAccount` inclui `status`, `receiverId`, `tosAccepted`, `payoutConfigured` e `approvedAt` / `rejectedAt`. A listagem é paginada por cursor (`nextCursor`), filtrável por `role` e `status`.

## Como as atualizações de status chegam

A decisão de verificação do parceiro de liquidação chega ao webhook de entrada assinado da Caratuva; a Caratuva resolve o recebedor para a sua conta conectada e atualiza o status dela (de forma idempotente). Uma decisão terminal (`approved`/`rejected`) também expurga quaisquer documentos que a Caratuva tenha armazenado para a conta.

Para observar o resultado hoje, faça **polling** em `GET /v1/connected-accounts/:id` (ou `GET /v1/connected-accounts?status=verifying`) até que `status` seja terminal. No sandbox, o KYB de vendedor empresa é aprovado automaticamente e de forma síncrona no `submit`, então a resposta do `submit` já carrega `approved`.

<Note>
  *Eventos* de webhook de saída para mudanças de status de contas conectadas (por exemplo, `connected_account.approved`) são uma etapa posterior — diferentemente dos pedidos de pagamento, uma conta conectada não está vinculada à linha do tempo de uma fatura. Por enquanto, faça polling nos endpoints de consulta.
</Note>