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

# Requisitos por País

> Obtenha os campos de validação e tipos de documento exigidos por país para fluxos de onboarding KYC e KYB no modelo universal de entidades gu1.

## Visão Geral

Os endpoints de requisitos por país ajudam os desenvolvedores a entender quais campos são obrigatórios para a criação de entidades em diferentes países. Cada país possui regras de validação específicas, formatos de identificação fiscal e campos obrigatórios.

Isso elimina o método de tentativa e erro ao criar entidades e fornece orientação clara sobre quais dados são necessários.

Para **empresas**, os campos de endereço fiscal (ex.: `domicilioFiscal`, `direccion`, `address`) são **opcionais** na criação. Você pode criar apenas com identificação fiscal e razão social e preencher o endereço depois via edição manual ou enrichments do país (ex.: ARCA na Argentina).

## Países Suportados

gu1 atualmente suporta **16 países** com validação abrangente:

<CardGroup cols={3}>
  <Card title="🇦🇷 Argentina" icon="flag">
    Validação de CUIT
  </Card>

  <Card title="🇧🇷 Brasil" icon="flag">
    Validação de CNPJ
  </Card>

  <Card title="🇲🇽 México" icon="flag">
    Validação de RFC
  </Card>

  <Card title="🇨🇱 Chile" icon="flag">
    Validação de RUT
  </Card>

  <Card title="🇨🇴 Colômbia" icon="flag">
    Validação de NIT
  </Card>

  <Card title="🇵🇪 Peru" icon="flag">
    Validação de RUC
  </Card>

  <Card title="🇺🇾 Uruguai" icon="flag">
    Validação de RUT
  </Card>

  <Card title="🇪🇨 Equador" icon="flag">
    Validação de RUC
  </Card>

  <Card title="🇵🇾 Paraguai" icon="flag">
    Validação de RUC
  </Card>

  <Card title="🇧🇴 Bolívia" icon="flag">
    Validação de NIT
  </Card>

  <Card title="🇻🇪 Venezuela" icon="flag">
    Validação de RIF
  </Card>

  <Card title="🇺🇸 Estados Unidos" icon="flag">
    Validação de EIN
  </Card>

  <Card title="🇨🇦 Canadá" icon="flag">
    Validação de BN
  </Card>

  <Card title="🇪🇸 Espanha" icon="flag">
    Validação de CIF
  </Card>

  <Card title="🇵🇹 Portugal" icon="flag">
    Validação de NIPC
  </Card>

  <Card title="🇪🇪 Estônia" icon="flag">
    Validação de Registrikood
  </Card>
</CardGroup>

***

## Obter Todos os Países

```
GET http://api.gu1.ai/entities/country-requirements
```

Recupere uma lista de todos os países suportados.

### Exemplo de Resposta

```json theme={null}
{
  "success": true,
  "countries": [
    { "code": "AR", "name": "Argentina" },
    { "code": "BR", "name": "Brazil" },
    { "code": "MX", "name": "Mexico" },
    { "code": "US", "name": "United States" },
    ...
  ],
  "total": 16
}
```

***

## Obter Requisitos Específicos por País

```
GET http://api.gu1.ai/entities/country-requirements/:countryCode
```

Obtenha requisitos de validação detalhados para um país específico.

### Parâmetros de Rota

<ParamField path="countryCode" type="string" required>
  Código de país ISO 3166-1 alpha-2 (por exemplo, "AR", "BR", "US")
</ParamField>

### Campos de Resposta

<ResponseField name="success" type="boolean">
  Indica se a solicitação foi bem-sucedida
</ResponseField>

<ResponseField name="country" type="object">
  Detalhes de validação do país

  <Expandable title="propriedades de country">
    <ResponseField name="code" type="string">
      Código ISO do país
    </ResponseField>

    <ResponseField name="name" type="string">
      Nome do país
    </ResponseField>

    <ResponseField name="taxIdName" type="string">
      Nome local para identificação fiscal (por exemplo, "CUIT", "CNPJ", "RFC")
    </ResponseField>

    <ResponseField name="taxIdFormat" type="string">
      Padrão de expressão regular para validação de identificação fiscal
    </ResponseField>

    <ResponseField name="requiredFields" type="array">
      Lista de nomes de campos de atributos obrigatórios
    </ResponseField>

    <ResponseField name="optionalFields" type="array">
      Lista de nomes de campos de atributos opcionais. Para empresas, inclui campos de endereço fiscal que podem ser preenchidos depois.
    </ResponseField>

    <ResponseField name="registries" type="array">
      Lista de registros oficiais para este país
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="documentation" type="object">
  Exemplo de payload de solicitação

  <Expandable title="propriedades de documentation">
    <ResponseField name="example" type="object">
      Exemplo completo de como criar uma entidade para este país
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Exemplos

### Obter Requisitos da Argentina

<CodeGroup>
  ```bash cURL theme={null}
  curl http://api.gu1.ai/entities/country-requirements/AR \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://api.gu1.ai/entities/country-requirements/AR', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  console.log(data.country);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'http://api.gu1.ai/entities/country-requirements/AR',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  requirements = response.json()
  print(requirements['country'])
  ```
</CodeGroup>

### Exemplo de Resposta

```json theme={null}
{
  "success": true,
  "country": {
    "code": "AR",
    "name": "Argentina",
    "taxIdName": "CUIT",
    "taxIdFormat": "^\\d{2}-\\d{8}-\\d{1}$",
    "requiredFields": [
      "cuit",
      "razonSocial"
    ],
    "optionalFields": [
      "domicilioFiscal",
      "iibb",
      "actividadPrincipal",
      "fechaInicioActividades"
    ],
    "registries": [
      "AFIP",
      "IGJ",
      "RPC"
    ]
  },
  "documentation": {
    "example": {
      "type": "company",
      "externalId": "company_123",
      "name": "Example Company",
      "countryCode": "AR",
      "taxId": "Example CUIT",
      "attributes": {
        "cuit": "Example cuit",
        "razonSocial": "Example razonSocial",
        "domicilioFiscal": "Example domicilioFiscal"
      }
    }
  }
}
```

***

## Exemplos Específicos por País

### 🇦🇷 Argentina (CUIT)

```json theme={null}
{
  "type": "company",
  "externalId": "company_ar_001",
  "name": "Tech Solutions Argentina",
  "countryCode": "AR",
  "taxId": "30-71234567-8",
  "attributes": {
    "cuit": "30-71234567-8",
    "razonSocial": "Tech Solutions S.A.",
    "domicilioFiscal": "Av. Corrientes 1234, CABA",
    "iibb": "901-123456-7",
    "actividadPrincipal": "Desarrollo de Software"
  }
}
```

Criação mínima de empresa (endereço opcional):

```json theme={null}
{
  "type": "company",
  "externalId": "company_ar_minimal",
  "name": "Tech Solutions Argentina",
  "countryCode": "AR",
  "taxId": "30-71234567-8",
  "attributes": {
    "cuit": "30-71234567-8",
    "razonSocial": "Tech Solutions S.A."
  }
}
```

### 🇧🇷 Brasil (CNPJ)

```json theme={null}
{
  "type": "company",
  "externalId": "company_br_001",
  "name": "Tech Solutions Brasil",
  "countryCode": "BR",
  "taxId": "12.345.678/0001-90",
  "attributes": {
    "cnpj": "12.345.678/0001-90",
    "razaoSocial": "Tech Solutions Ltda",
    "enderecoFiscal": "Av. Paulista, 1000 - São Paulo, SP",
    "inscricaoEstadual": "123.456.789.012",
    "cnae": "6201-5/00"
  }
}
```

### 🇲🇽 México (RFC)

```json theme={null}
{
  "type": "company",
  "externalId": "company_mx_001",
  "name": "Tech Solutions México",
  "countryCode": "MX",
  "taxId": "TSM980101ABC",
  "attributes": {
    "rfc": "TSM980101ABC",
    "razonSocial": "Tech Solutions S.A. de C.V.",
    "domicilioFiscal": "Av. Reforma 123, Ciudad de México",
    "regimenFiscal": "601"
  }
}
```

### 🇺🇸 Estados Unidos (EIN)

```json theme={null}
{
  "type": "company",
  "externalId": "company_us_001",
  "name": "Tech Solutions Inc",
  "countryCode": "US",
  "taxId": "12-3456789",
  "attributes": {
    "ein": "12-3456789",
    "legalName": "Tech Solutions Inc.",
    "address": "123 Main St, San Francisco, CA 94102",
    "stateOfIncorporation": "Delaware",
    "naicsCode": "541511"
  }
}
```

### 🇪🇸 Espanha (CIF)

```json theme={null}
{
  "type": "company",
  "externalId": "company_es_001",
  "name": "Tech Solutions España",
  "countryCode": "ES",
  "taxId": "A12345678",
  "attributes": {
    "cif": "A12345678",
    "razonSocial": "Tech Solutions S.L.",
    "direccionFiscal": "Calle Gran Vía 1, Madrid",
    "cnae": "6201"
  }
}
```

***

## Respostas de Erro

### 404 - País Não Suportado

```json theme={null}
{
  "success": false,
  "error": {
    "code": "COUNTRY_NOT_SUPPORTED",
    "message": "Country code 'XX' is not supported",
    "details": {
      "countryCode": "XX",
      "supportedCountries": ["AR", "BR", "MX", ...]
    }
  }
}
```

***

## Melhores Práticas

<AccordionGroup>
  <Accordion icon="lightbulb" title="Consultar Antes de Criar">
    Sempre consulte os requisitos do país antes de criar entidades para garantir que você colete todos os dados necessários de seus usuários antecipadamente.
  </Accordion>

  <Accordion icon="database" title="Armazenar em Cache os Requisitos">
    Os requisitos por país raramente mudam. Considere armazená-los em cache em sua aplicação para reduzir as chamadas à API.
  </Accordion>

  <Accordion icon="shield-check" title="Validar do Lado do Cliente">
    Use o padrão regex de `taxIdFormat` para validar identificações fiscais no lado do cliente antes de enviar para a API.
  </Accordion>

  <Accordion icon="language" title="Localizar Nomes de Campos">
    Exiba os nomes de campos no idioma do usuário. A API retorna nomes de campos locais (por exemplo, "razonSocial" para Argentina em vez de "legalName").
  </Accordion>
</AccordionGroup>

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Criar Entidade" icon="plus" href="/api-reference/entities/create">
    Use os requisitos para criar uma entidade corretamente validada
  </Card>

  <Card title="Validar Identificações Fiscais" icon="check" href="/en/api-reference/entities/country-requirements">
    Valide as identificações fiscais antes de criar a entidade
  </Card>
</CardGroup>