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

# POST /cpf-cnpj-generator

> Gere números de CPF e CNPJ matematicamente válidos para testes e desenvolvimento.

## Endpoint

```
POST https://api.bunny.build/api/v1/cpf-cnpj-generator
```

## Autenticação

| Header         | Obrigatório | Valor                        |
| -------------- | ----------- | ---------------------------- |
| `X-API-Key`    | Sim         | Sua chave de API (`bun_...`) |
| `Content-Type` | Sim         | `application/json`           |

## Visão geral

Gere lotes de números de CPF (Cadastro de Pessoas Físicas) ou CNPJ (Cadastro Nacional da Pessoa Jurídica) matematicamente válidos para uso em ambientes de teste. Todos os documentos gerados passam pelo algoritmo oficial de verificação e podem ser retornados opcionalmente com máscaras de formatação padrão. São números sintéticos apenas para fins de teste e não correspondem a pessoas físicas ou jurídicas reais.

## Casos de uso

* Popular bancos de dados de teste e ambientes de QA com documentos brasileiros realistas
* Validar componentes de formulários em pipelines de CI sem usar dados reais
* Demonstrar comportamento de validação de formulários em demos ao vivo e protótipos
* Gerar fixtures para testes unitários e de integração

## Corpo da requisição

| Campo       | Tipo    | Obrigatório | Descrição                                                            |
| ----------- | ------- | ----------- | -------------------------------------------------------------------- |
| `type`      | string  | Não         | Tipo de documento: `"cpf"` ou `"cnpj"`. Padrão: `"cpf"`              |
| `count`     | integer | Não         | Número de documentos a gerar (1–100). Padrão: `1`                    |
| `formatted` | boolean | Não         | Retornar strings formatadas (ex: `"123.456.789-09"`). Padrão: `true` |

### Exemplo

```json theme={null}
{
  "type": "cpf",
  "count": 3,
  "formatted": true
}
```

## Resposta

### 200 OK

| Campo       | Tipo             | Descrição                                                                |
| ----------- | ---------------- | ------------------------------------------------------------------------ |
| `type`      | string           | Tipo de documento retornado                                              |
| `count`     | integer          | Número de documentos gerados                                             |
| `documents` | array de objetos | Cada entrada contém `raw` (sem formatação) e `formatted` (se solicitado) |
| `document`  | string           | Primeiro documento do lote (atalho para casos com `count: 1`)            |

**Exemplo**

```json theme={null}
{
  "type": "cpf",
  "count": 3,
  "documents": [
    { "raw": "12345678909", "formatted": "123.456.789-09" },
    { "raw": "98765432100", "formatted": "987.654.321-00" },
    { "raw": "11122233396", "formatted": "111.222.333-96" }
  ],
  "document": "123.456.789-09"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "'count' must be between 1 and 100."
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/cpf-cnpj-generator \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "cpf", "count": 3, "formatted": true}'
```