Visão geral

A API do Mapfolio fornece acesso programático a dados de empresas suíças através de uma interface RESTful. Todos os endpoints são documentados usando a especificação OpenAPI 3.0, garantindo consistência e facilidade de integração.

Começando

Autenticação

A API do Mapfolio usa autenticação por chave API. Você pode obter sua chave API nas suas configurações da conta.

Cabeçalho da chave API:

X-API-Key: mapf_sua_chave_api_aqui

Token Bearer (Alternativa):

Authorization: Bearer mapf_sua_chave_api_aqui

URL base

Todas as solicitações da API devem ser feitas para:

https://mapfolio.app

Limitação de taxa

As solicitações da API são limitadas por taxa para garantir uso justo:

Solicitações autenticadas: 1000 solicitações por hora por chave API
Solicitações não autenticadas: 10 solicitações por hora por endereço IP

As informações de limitação de taxa estão incluídas nos cabeçalhos de resposta:

X-RateLimit-Limit: Número máximo de solicitações permitidas
X-RateLimit-Remaining: Solicitações restantes na janela atual
X-RateLimit-Reset: Timestamp Unix quando o limite é redefinido

Endpoints disponíveis

Busca de empresas

Busque empresas com opções de filtragem avançadas:

Busca de texto em nomes de empresas
Filtrar por cantão (cantões suíços)
Filtrar por status da empresa
Suporte à paginação

Detalhes da empresa

Recupere informações detalhadas sobre empresas específicas:

Dados do perfil da empresa
Informações de localização
Status legal
Detalhes de registro

Estatísticas

Acesse estatísticas agregadas sobre empresas suíças:

Contagens gerais de empresas
Estatísticas em nível de cantão
Distribuições baseadas em letras
Contagens de combinações de duas letras

Autocompletar

Obtenha sugestões de autocompletar para:

Nomes de empresas
Cidades
Códigos postais

Empresas aleatórias

Recupere amostras aleatórias de empresas para testes e exploração.

Formato de resposta

Todas as respostas bem-sucedidas da API seguem uma estrutura consistente:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

As respostas de erro incluem informações detalhadas:

{
  "error": "Mensagem de erro",
  "details": "Detalhes adicionais do erro"
}

Códigos de erro

400 Bad Request: Parâmetros de solicitação inválidos
401 Unauthorized: Chave API ausente ou inválida
403 Forbidden: Permissões insuficientes
404 Not Found: Recurso não encontrado
429 Too Many Requests: Limite de taxa excedido
500 Internal Server Error: Erro do servidor

Especificação OpenAPI

A especificação OpenAPI 3.0 completa está disponível em:

Documentação interativa: /api-docs.html
OpenAPI JSON: /api/docs/openapi.json

Você pode usar a especificação OpenAPI com qualquer ferramenta compatível:

Swagger UI
Postman
Insomnia
Geradores de código para bibliotecas cliente

Exemplos de código

cURL

curl -H "X-API-Key: mapf_sua_chave_api_aqui" \
  https://mapfolio.app/api/search?q=tecnologia

JavaScript (Fetch)

const response = await fetch('https://mapfolio.app/api/search?q=tecnologia', {
  headers: {
    'X-API-Key': 'mapf_sua_chave_api_aqui'
  }
})
const data = await response.json()

Python (Requests)

import requests

headers = {'X-API-Key': 'mapf_sua_chave_api_aqui'}
response = requests.get(
  'https://mapfolio.app/api/search',
  params={'q': 'tecnologia'},
  headers=headers
)
data = response.json()

Suporte

Para suporte da API e perguntas:

Documentação: Visite a documentação interativa da API
Email: support@mapfolio.app
Problemas: Reporte problemas através do painel da sua conta

Termos de uso

Ao usar a API do Mapfolio, você concorda com nossos Termos de serviço e nossa Política de privacidade. Por favor, revise os limites de taxa e as diretrizes de uso para garantir conformidade.