Requisitos por País

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:

🇦🇷 Argentina

Validação de CUIT

🇧🇷 Brasil

Validação de CNPJ

🇲🇽 México

Validação de RFC

🇨🇱 Chile

Validação de RUT

🇨🇴 Colômbia

Validação de NIT

🇵🇪 Peru

Validação de RUC

🇺🇾 Uruguai

Validação de RUT

🇪🇨 Equador

Validação de RUC

🇵🇾 Paraguai

Validação de RUC

🇧🇴 Bolívia

Validação de NIT

🇻🇪 Venezuela

Validação de RIF

🇺🇸 Estados Unidos

Validação de EIN

🇨🇦 Canadá

Validação de BN

🇪🇸 Espanha

Validação de CIF

🇵🇹 Portugal

Validação de NIPC

🇪🇪 Estônia

Validação de Registrikood

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

{
  "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

string

required

Código de país ISO 3166-1 alpha-2 (por exemplo, “AR”, “BR”, “US”)

Campos de Resposta

boolean

Indica se a solicitação foi bem-sucedida

object

Detalhes de validação do país

Show propriedades de country

string

Código ISO do país

string

Nome do país

string

Nome local para identificação fiscal (por exemplo, “CUIT”, “CNPJ”, “RFC”)

string

Padrão de expressão regular para validação de identificação fiscal

array

Lista de nomes de campos de atributos obrigatórios

array

Lista de nomes de campos de atributos opcionais. Para empresas, inclui campos de endereço fiscal que podem ser preenchidos depois.

array

Lista de registros oficiais para este país

object

Exemplo de payload de solicitação

Show propriedades de documentation

object

Exemplo completo de como criar uma entidade para este país

Exemplos

Obter Requisitos da Argentina

curl http://api.gu1.ai/entities/country-requirements/AR \
  -H "Authorization: Bearer YOUR_API_KEY"

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);

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'])

Exemplo de Resposta

{
  "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)

{
  "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):

{
  "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)

{
  "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)

{
  "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)

{
  "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)

{
  "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

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

Melhores Práticas

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.

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.

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.

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”).

​Visão Geral

​Países Suportados

🇦🇷 Argentina

🇧🇷 Brasil

🇲🇽 México

🇨🇱 Chile

🇨🇴 Colômbia

🇵🇪 Peru

🇺🇾 Uruguai

🇪🇨 Equador

🇵🇾 Paraguai

🇧🇴 Bolívia

🇻🇪 Venezuela

🇺🇸 Estados Unidos

🇨🇦 Canadá

🇪🇸 Espanha

🇵🇹 Portugal

🇪🇪 Estônia

​Obter Todos os Países

​Exemplo de Resposta

​Obter Requisitos Específicos por País

​Parâmetros de Rota

​Campos de Resposta

​Exemplos

​Obter Requisitos da Argentina

​Exemplo de Resposta

​Exemplos Específicos por País

​🇦🇷 Argentina (CUIT)

​🇧🇷 Brasil (CNPJ)

​🇲🇽 México (RFC)

​🇺🇸 Estados Unidos (EIN)

​🇪🇸 Espanha (CIF)

​Respostas de Erro

​404 - País Não Suportado

​Melhores Práticas

​Próximos Passos

Criar Entidade

Validar Identificações Fiscais

Visão Geral

Países Suportados

Obter Todos os Países

Exemplo de Resposta

Obter Requisitos Específicos por País

Parâmetros de Rota

Campos de Resposta

Exemplos

Obter Requisitos da Argentina

Exemplo de Resposta

Exemplos Específicos por País

🇦🇷 Argentina (CUIT)

🇧🇷 Brasil (CNPJ)

🇲🇽 México (RFC)

🇺🇸 Estados Unidos (EIN)

🇪🇸 Espanha (CIF)

Respostas de Erro

404 - País Não Suportado

Melhores Práticas

Próximos Passos