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

# SUNAT

> Consulte informações de contribuintes peruanos (RUC) por RUC, documento de identidade ou nome.

Resolve informações de contribuintes peruanos a partir da SUNAT. Três consultas refletem
as abas de busca da própria SUNAT: por RUC, por documento de identidade e por
nome (razão social). As duas primeiras retornam o registro completo de um contribuinte;
a busca por nome retorna uma lista de correspondências.

## Por RUC

`POST /pe/sunat/ruc/v1`

| Campo | Tipo   | Notas                               |
| ----- | ------ | ----------------------------------- |
| `ruc` | string | **Obrigatório.** RUC de 11 dígitos. |

```bash theme={"dark"}
curl https://api.croma.run/pe/sunat/ruc/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ruc": "20100070970" }'
```

## Por documento

`POST /pe/sunat/document/v1`

| Campo             | Tipo   | Notas                                                                                 |
| ----------------- | ------ | ------------------------------------------------------------------------------------- |
| `document_type`   | string | Um de `dni`, `ce` (carné de extranjería), `passport`, `diplomatic`. O padrão é `dni`. |
| `document_number` | string | **Obrigatório.** De 6 a 16 caracteres alfanuméricos.                                  |

```bash theme={"dark"}
curl https://api.croma.run/pe/sunat/document/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "document_type": "dni", "document_number": "12345678" }'
```

## Por nome

`POST /pe/sunat/name/v1`

| Campo  | Tipo   | Notas                                                         |
| ------ | ------ | ------------------------------------------------------------- |
| `name` | string | **Obrigatório.** Nome ou razão social, de 3 a 100 caracteres. |

```bash theme={"dark"}
curl https://api.croma.run/pe/sunat/name/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "INVERSIONES GENERALES" }'
```

A busca por nome retorna até 30 correspondências (o limite da SUNAT). Quando `capped`
é `true`, os resultados estão incompletos: refine a consulta ou consulte diretamente o RUC
escolhido.

## Resposta

As consultas por RUC e por documento retornam um registro de contribuinte.

| Campo                                                                            | Notas                                                                                                                          |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `found`                                                                          | `true` quando um contribuinte corresponde; `false` quando a SUNAT não tem nenhum (os demais campos ficam então em null/vazio). |
| `ruc`                                                                            | O RUC de 11 dígitos.                                                                                                           |
| `name`                                                                           | Razão social ou nome completo.                                                                                                 |
| `type`                                                                           | Por exemplo, `SOCIEDAD ANONIMA`, `PERSONA NATURAL SIN NEGOCIO`.                                                                |
| `document_type`, `document_number`                                               | Documento de identidade subjacente (pessoas físicas).                                                                          |
| `trade_name`                                                                     | Nome fantasia, se houver.                                                                                                      |
| `registration_date`, `activities_start_date`                                     | Data de inscrição / início de atividades (`yyyy-mm-dd`).                                                                       |
| `status`                                                                         | Estado (por exemplo, `ACTIVO`, `BAJA DE OFICIO`).                                                                              |
| `condition`                                                                      | Condição (por exemplo, `HABIDO`).                                                                                              |
| `fiscal_address`                                                                 | Domicílio fiscal.                                                                                                              |
| `emission_system`, `accounting_system`                                           | Sistema de emissão / contabilidade.                                                                                            |
| `foreign_trade_activity`                                                         | Atividade de comércio exterior.                                                                                                |
| `economic_activities`                                                            | Lista de atividades CIIU (principal e secundárias).                                                                            |
| `payment_vouchers`                                                               | Comprovantes de pagamento autorizados.                                                                                         |
| `electronic_emission_systems`, `electronic_vouchers`, `electronic_emitter_since` | Detalhes de faturamento eletrônico.                                                                                            |
| `ple_affiliated_since`                                                           | Afiliado ao PLE desde.                                                                                                         |
| `registries`                                                                     | Cadastros aos quais o contribuinte pertence.                                                                                   |

A consulta por nome retorna `query`, `count`, `capped` e `contributors[]`, cada um
com `ruc`, `name`, `location` e `status`.

<Note>
  Estas consultas podem demorar mais que uma solicitação típica. São
  [trabalhos assíncronos](/pt/async-jobs). Por padrão, a solicitação espera de forma síncrona e retorna
  `{ data }`, ou você pode fazer polling / usar um `callback_url`.
</Note>

<Card title="Referência completa" icon="code" href="/pt/api-reference/overview">
  Esquemas, campos de resposta e um playground interativo.
</Card>