# Como criar um onboarding KYC via API?

> Para iniciar o processo de KYC (Know Your Customer) de um merchant, você utiliza o _endpoint_ `POST /api/v1/kyc/onboarding`.

Este endpoint cria um registro de conta (AccountRegister) e retorna um link de onboarding que deve ser enviado ao merchant para que ele preencha seus dados cadastrais.

:::info
Antes de usar este endpoint, garanta que sua empresa possui as features **BAAS** e **KYC_ONBOARDING_LINK** habilitadas e que sua aplicação tenha o scope **`KYC_ONBOARDING_POST`**. Veja [Primeiros passos com a API de KYC Onboarding](./api-getting-started.mdx) para detalhes.
:::

:::tip Referência completa
Para o schema, parâmetros e exemplos interativos, veja a [API Reference](/api#tag/kyc/POST/api/v1/kyc/onboarding).
:::

## Campos

### Obrigatórios

- **`taxID`**: CNPJ da empresa do merchant. Aceita formato com ou sem máscara (ex: `XX.XXX.XXX/0001-XX` ou `XXXXXXXXXXXXXX`). Validado como CNPJ.

:::tip Conta de pessoa física
Para abrir uma conta PF (CPF), use o mesmo _endpoint_ com `taxIDType: "BR:CPF"`. Veja [Como criar uma conta PF (pessoa física)?](./api-onboarding-conta-pf.mdx).
:::

### Opcionais

- **`correlationID`**: Identificador único para idempotência. Se não informado, o CNPJ será usado como correlationID. Se a mesma `correlationID` for enviada novamente, a API retorna o link existente (200) ao invés de criar um novo.
- **`website`**: Site do merchant. Se informado, é persistido no AccountRegister e o merchant não precisa redigitá-lo no formulário de onboarding.
- **`businessDescription`**: Descrição da atividade do merchant. Se informado, é persistido no AccountRegister e **destrava automaticamente a etapa `COMPANY_DATA`** do formulário — o merchant não precisa redigitá-lo. Útil quando o parceiro BaaS já coletou essa informação no próprio funil.
- **`representatives`**: Array de sócios/representantes da empresa. Cada representante deve conter:
  - **`taxID`**: CPF do representante. Validado como CPF. Aceita formato com ou sem máscara.

:::info Não-destrutivo
`website` e `businessDescription` só são preenchidos quando estão vazios no AccountRegister. Em uma chamada idempotente (mesmo `correlationID`), um valor já informado pelo merchant **nunca é sobrescrito**.
:::

## Exemplo

O body da sua requisição será semelhante a este exemplo:

```json
{
  "taxID": "XX.XXX.XXX/0001-XX",
  "correlationID": "my-unique-id",
  "website": "https://loja-do-merchant.com.br",
  "businessDescription": "Loja de roupas e acessórios femininos",
  "representatives": [
    { "taxID": "XXX.XXX.XXX-XX" },
    { "taxID": "XXX.XXX.XXX-XX" }
  ]
}
```

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `201` e no `body` da resposta, retornaremos o link de onboarding e os dados do registro de conta.

Retornaremos a seguinte resposta de exemplo:

```json
{
  "linkOnboarding": "https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...",
  "accountRegister": {
    "status": "PENDING",
    "officialName": "RAZAO_SOCIAL_DA_EMPRESA",
    "tradeName": "NOME_FANTASIA_DA_EMPRESA",
    "taxID": {
      "taxID": "XXXXXXXXXXXXXX",
      "type": "BR:CNPJ"
    },
    "correlationID": "my-unique-id",
    "representatives": [
      {
        "name": "NOME_DO_SOCIO",
        "taxID": {
          "taxID": "XXXXXXXXXXX",
          "type": "BR:CPF"
        }
      }
    ]
  }
}
```

:::info
Os campos `officialName`, `tradeName` e `representatives[].name` são preenchidos automaticamente pelo enriquecimento de dados quando disponíveis.
:::

## Idempotência

A API é idempotente pelo campo `correlationID`. Se você enviar a mesma `correlationID` para a mesma empresa, a API retornará **200 OK** com o link de onboarding existente, sem criar um novo registro.

```sh
# Primeira chamada → 201 Created
curl -X POST https://api.woovi.com/api/v1/kyc/onboarding \
  -H "Content-Type: application/json" \
  -H "Authorization: SEU_APPID_AQUI" \
  -d '{"taxID": "XX.XXX.XXX/0001-XX", "correlationID": "order-123"}'

# Segunda chamada com mesmo correlationID → 200 OK (mesmo link)
curl -X POST https://api.woovi.com/api/v1/kyc/onboarding \
  -H "Content-Type: application/json" \
  -H "Authorization: SEU_APPID_AQUI" \
  -d '{"taxID": "XX.XXX.XXX/0001-XX", "correlationID": "order-123"}'
```

## Códigos de resposta

| Status | Descrição |
|--------|-----------|
| `200` | Onboarding já existe para este `correlationID` (idempotente) |
| `201` | Onboarding criado com sucesso |
| `400` | Input inválido (taxID ausente ou CNPJ inválido) |
| `401` | Credenciais inválidas |
| `403` | Empresa sem feature BAAS ou KYC_ONBOARDING_LINK habilitada |
| `405` | Método HTTP não permitido (use POST) |
| `409` | Já existe um onboarding para este CNPJ com outro correlationID |

### Exemplos de erro

```json
{
  "error": "Invalid input: taxID is required"
}
```

```json
{
  "error": "Invalid CNPJ"
}
```

```json
{
  "error": "An onboarding already exists for this taxID"
}
```

```json
{
  "error": "Method Not Allowed. Use POST to create an onboarding."
}
```

```json
{
  "error": "Company does not have BaaS feature enabled"
}
```

## Exemplos em código

  

**Shell + cURL**

```sh
curl 'https://api.woovi.com/api/v1/kyc/onboarding' -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: SEU_APPID_AQUI" \
    --data-binary '{
      "taxID": "XX.XXX.XXX/0001-XX",
      "correlationID": "my-unique-id",
      "representatives": [
        { "taxID": "XXX.XXX.XXX-XX" }
      ]
    }'
```

  
  

**JavaScript + Fetch**

```js
const appId = 'SEU_APPID_AQUI';

const response = await fetch('https://api.woovi.com/api/v1/kyc/onboarding', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': appId,
  },
  body: JSON.stringify({
    taxID: 'XX.XXX.XXX/0001-XX',
    correlationID: 'my-unique-id',
    representatives: [
      { taxID: 'XXX.XXX.XXX-XX' },
    ],
  }),
});

const data = await response.json();

console.log(data.linkOnboarding);
// https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5...
```

  

## Fluxo completo

1. **Chamada da API** → Cria o onboarding e retorna o `linkOnboarding`
2. **Envie o link ao merchant** → O merchant acessa o formulário e preenche os dados
3. **Merchant preenche o cadastro** → Dados da empresa, endereço, contrato social, documentos dos sócios
4. **Merchant submete** → O status muda para `IN_REVIEW`
5. **Análise** → A equipe analisa os documentos (pode levar até 72h)
6. **Aprovação/Rejeição** → O status muda para `APPROVED` ou `REJECTED`