# Primeiros passos com a API de KYC Onboarding

> Este documento irá ajudá-lo a começar a utilizar a API de KYC Onboarding.

## Criando uma nova chave de API

O primeiro passo para começar a integrar com a API é criar uma nova chave de API.

### Passo 1 - Criar um novo aplicativo

Vá para `Api/Plugins` na barra lateral e clique em `Nova API/Plugin`.

:::caution
Caso você não esteja visualizando o sidebar API/Plugins é necessário ter a permissão correta, veja com o admin da sua empresa.
:::

### Passo 2 - Nome da integração

Dentro da tela de criação, coloque um nome para a integração e selecione `API` para integrações backend.

### Passo 3 - Criando a chave

Clique em `Salvar` para criar a nova chave de API.

### Passo 4 - Fator de autenticação

Para que a API possa ser utilizada, é necessário colocar um fator duplo de autenticação para garantir maior segurança na geração de chaves.

### Passo 5 - Copiando o AppID

Após criar a nova chave, copie o **AppID** para utilizar em suas integrações.

## Como utilizar a API

Todas as `requests` e `responses` da API usam o formato JSON.

Para que a requisição seja válida, é necessário enviar o `AppID` no header `Authorization` da requisição.

Não utilize o prefixo `Bearer`. Envie o valor bruto do `AppID` no header.

```json
{
  "Authorization": "<AppID>"
}
```

Exemplo:

```sh
curl -X POST https://api.woovi.com/api/v1/kyc/onboarding \
  -H "Content-Type: application/json" \
  -H "Authorization: SEU_APPID_AQUI" \
  -d '{"taxID": "51.238.607/0002-26"}'
```

### Requisitos

- A empresa deve possuir as features **BAAS** e **KYC_ONBOARDING_LINK** habilitadas
- A aplicação deve possuir o scope **`KYC_ONBOARDING_POST`**

## Onboarding 100% via API

Se você quer conduzir o onboarding inteiro pelo seu produto — documentos, sócios, autenticação Pix, BC Protege+, envio para análise e resposta a RFI — sem mandar o cliente para o link hospedado, siga o guia [Onboarding KYC 100% via API](./api-onboarding-full-api.mdx). Os padrões gerais (upload + `fileId`, `correlationID`, idempotência, webhooks) estão em [Como construir integrações 100% via API com a Woovi](../../apis/api-driven-integrations.md).

## Restrições de API

- Todas as requisições devem ser criptografadas usando `https`
- As chaves de API são extremamente poderosas e devem ser armazenadas com cuidado extra
- Não compartilhe chaves com terceiros
- Não reutilize chaves entre ambientes
- Apenas gere chaves quando for necessário
- Desative chaves não utilizadas

## Erros de autenticação

Pode ocorrer de você receber uma resposta com o HTTP Status `401`, que está relacionado a um AppID inválido.

```json
{
  "error": "Unauthorized"
}
```

Caso a empresa não possua a feature BAAS habilitada, você receberá o HTTP Status `403`:

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

Caso seja inválido, é recomendado gerar um novo AppID da sua aplicação e adicionar novamente em seu sistema.

## URL Base

| Ambiente | URL |
|----------|-----|
| Produção | `https://api.woovi.com/api/v1/kyc/onboarding` |

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