Documentação de Integração

A ÍndiceAPI é a plataforma brasileira criada para unificar, em um único serviço, o acesso aos principais índices econômicos e financeiros do Brasil e do mundo. Nossa proposta é simples e ambiciosa: eliminar a dor de integrar dezenas de fontes diferentes — Banco Central (SGS), IBGE (SIDRA), IPEA, Tesouro Nacional, índices estaduais como a UFESP (SP), UFIR-RJ, UFEMG (MG), UFERMS e UAM-MS (MS) e centenas de outras séries — entregando tudo por meio de uma API REST moderna, documentada em português e pronta para ambientes de produção.

Sabemos o quanto é frustrante manter scripts frágeis, lidar com formatos distintos, indisponibilidades e mudanças silenciosas nas fontes oficiais. Por isso centralizamos a coleta, o tratamento e a disponibilização dos dados com atualização contínua: nossa base é alimentada dezenas de vezes ao dia, com foco em confiabilidade, rastreabilidade e qualidade para contratos, sistemas financeiros, ERPs, fintechs, cooperativas, escritórios, órgãos públicos e qualquer aplicação que dependa de índices oficiais.

A ÍndiceAPI nasceu para ser o ponto único de consulta. Enquanto o mercado ainda espalha informações em portais distintos, oferecemos um catálogo vivo que cresce a cada semana — novos índices, novas instituições e novas possibilidades de integração sem que você precise refazer sua arquitetura. É a combinação de facilidade (cadastro rápido, painel claro, exemplos prontos), segurança (HTTPS, autenticação robusta, limites por plano, logs de auditoria) e excelência técnica (baixa latência, paginação, documentação Swagger e suporte em português).

Acreditamos que dados econômicos de qualidade devem ser acessíveis. Por isso disponibilizamos plano gratuito para testes reais, evolução natural para planos pagos sem perder configurações e uma experiência pensada para desenvolvedores e gestores. A ÍndiceAPI é referência nacional em API unificada de índices — integração simples hoje, escala amanhã.

Para utilizar a API e o painel de controle, é necessário possuir uma conta na ÍndiceAPI. O cadastro é o primeiro passo: a partir dele são liberados o acesso ao sistema, a geração de chaves e a integração com os endpoints de disponibilidade.

Como se cadastrar

1. 1Acesse a página de cadastro em indiceapi.com.br/cadastro (ou clique em "Criar conta grátis" na home).
2. 2Escolha o plano desejado — o plano Gratuito / Teste é ideal para avaliar a API sem compromisso.
3. 3Preencha nome, CPF ou CNPJ, e-mail, telefone, endereço e defina uma senha forte.
4. 4Resolva o desafio de segurança anti-spam exibido na tela e envie o formulário.
5. 5Planos gratuitos costumam ser liberados rapidamente; planos pagos podem ficar com status PENDENTE até confirmação da equipe.
6. 6Após liberação, você receberá orientações por e-mail, incluindo a chave de licença (lic_) quando aplicável.

Como fazer login

1. 1Acesse indiceapi.com.br/login.
2. 2Informe seu CPF ou CNPJ (somente números) e a senha cadastrada.
3. 3Após autenticar, você será direcionado ao painel Cliente (ou Master, se for administrador).
4. 4No painel você consulta índices, acompanha uso da API, gerencia perfil e solicita API Keys ao suporte/master.
5. 5A sessão do painel dura 23 horas; depois disso será necessário entrar novamente.

A ÍndiceAPI aplica limitações por plano para garantir estabilidade, segurança e qualidade do serviço para todos os clientes. Esses limites protegem a infraestrutura contra abusos, distribuem recursos de forma justa e mantêm a base de índices rápida e confiável mesmo com alto volume de consultas.

Plano Gratuito / Teste

O plano gratuito foi desenhado para você testar a integração de ponta a ponta em ambiente real, porém com cotas reduzidas. Em geral inclui: até 100 requisições por dia, até 2.000 requisições por mês, 1 API Key (chave ind_) e ciclo de acesso de aproximadamente 30 dias a partir do cadastro. Os contadores diários zeram à meia-noite e os mensais no dia 1º, sempre no fuso horário de Cuiabá (America/Cuiaba).

Quando o período de avaliação expira ou o status do usuário passa para EXPIRADO, o acesso ao painel e à API é bloqueado até a contratação de um plano pago. Nesse momento não é possível gerar novos tokens nem consultar índices — entre em contato com nossa equipe ou escolha um plano Starter, Business ou Enterprise na página de planos.

Outras limitações importantes

• Códigos de índice: alguns planos restringem quais séries podem ser consultadas. Verifique no painel quais códigos seu plano permite.
• Rate limit: requisições excessivas em curto intervalo podem retornar HTTP 429. Implemente retry com espera progressiva.
• Paginação: consultas de índices retornam até 40 registros por página — use o parâmetro page para percorrer o histórico.
• Timeout: recomendamos timeout de cliente de 30 segundos; períodos muito amplos podem demorar mais.
• API desativada: em manutenção, o administrador pode desligar temporariamente a API de Disponibilidade (HTTP 503).

A API de Disponibilidade é o coração da integração ÍndiceAPI. Ela expõe, de forma somente leitura, os índices já coletados, validados e armazenados em nossa base — prontos para alimentar sistemas financeiros, módulos de reajuste contratual, motores de precificação, ERPs, dashboards, relatórios regulatórios e qualquer aplicação que precise de dados econômicos oficiais com baixa latência.

Por que usar nossa API?

• Comunicação padronizada: JSON via HTTPS, códigos HTTP claros e contratos estáveis documentados no Swagger.
• Segurança em camadas: token temporário (20h), JWT de sessão (23h) ou API Key permanente (ind_) — você escolhe o modelo que melhor se adapta ao seu ambiente.
• Qualidade dos dados: fontes oficiais (BCB, IBGE, IPEA, Tesouro, SEFAZ-SP para UFESP, SEFAZ-RJ para UFIR-RJ, SEFAZ-MG para UFEMG e SEFAZ-MS para UFERMS/UAM-MS) com atualização automática dezenas de vezes ao dia.
• Rastreabilidade: consultas autenticadas são registradas para auditoria e suporte (sem expor valores sensíveis publicamente).

Base URL

https://indiceapi.com.br/api/v1

Todos os endpoints de integração de índices ficam sob /api/v1/disponibilidade. A autenticação inicial é feita em POST .../auth; as consultas usam Authorization: Bearer <token> ou header X-API-Key: ind_....

Ferramentas para testar

Você pode integrar com qualquer linguagem (Node.js, Python, Java, C#, PHP, etc.) ou testar manualmente pelo Swagger, Postman, Insomnia ou curl. O Swagger é a forma mais rápida de explorar parâmetros, schemas e respostas sem escrever código.

O Swagger (OpenAPI) da ÍndiceAPI é a interface interativa oficial para explorar e testar todos os endpoints de Disponibilidade. Ele documenta parâmetros, tipos de dados, códigos de resposta e permite executar requisições reais diretamente no navegador — ideal para validar autenticação antes de codificar sua integração.

Endereço do Swagger

https://indiceapi.com.br/docs

Acesse o link acima, localize a tag Disponibilidade e siga o fluxo abaixo. O token temporário gerado em /auth tem validade de 20 horas (72000 segundos). Recomendamos renovar o token a cada 19 horas em integrações de produção, deixando margem de segurança antes do vencimento.

Autenticação no Swagger — regras de sucesso

• O usuário deve estar com status ATIVO no sistema.
• O documento (CPF/CNPJ sem máscara) deve corresponder ao cadastro.
• A chaveUsuario (prefixo ind_) deve ser uma API Key válida e ativa do mesmo usuário.
• A chaveLicenca (prefixo lic_) deve ter sido enviada pela nossa equipe ao e-mail cadastrado e pertencer ao mesmo documento.
• Plano não pode estar expirado; caso contrário a autenticação retorna 403.
• No botão Authorize do Swagger, use somente um método: cole o accessToken no campo bearer OU a chave ind_ no campo api-key — nunca os dois ao mesmo tempo com valores trocados.

Passo a passo — da autenticação à consulta

1. 1Execute POST https://indiceapi.com.br/api/v1/disponibilidade/auth com documento, chaveUsuario e chaveLicenca (veja exemplo JSON abaixo).
2. 2Copie o campo accessToken da resposta (começa com eyJ...).
3. 3Clique em Authorize no topo do Swagger e cole o token no campo bearer (sem escrever a palavra "Bearer").
4. 4Chame GET https://indiceapi.com.br/api/v1/disponibilidade/catalogo para localizar o codigo do índice desejado (ex.: 433 para IPCA).
5. 5Chame GET https://indiceapi.com.br/api/v1/disponibilidade/indices?codigo=433&page=1 para obter os valores.
6. 6Opcional: use GET .../indices/{instituicao}/{id} para detalhar um registro específico.

{
  "documento": "00000000000",
  "chaveUsuario": "ind_a1b2c3d4e5f6789012345678901234567890abcd",
  "chaveLicenca": "lic_f1e2d3c4b5a6978012345678901234567890abcd"
}

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 72000,
  "usuario": {
    "id": "uuid-do-usuario",
    "nome": "Sua Empresa LTDA",
    "documento": "00000000000",
    "plano": "GRATUITO_TESTE",
    "planoTitulo": "Gratuito / Teste",
    "status": "ATIVO"
  }
}

curl -s -X POST "https://indiceapi.com.br/api/v1/disponibilidade/auth" \
  -H "Content-Type: application/json" \
  -d @corpo-auth.json

curl -s "https://indiceapi.com.br/api/v1/disponibilidade/catalogo?nome=ipca&page=1" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

curl -s "https://indiceapi.com.br/api/v1/disponibilidade/indices?codigo=433&dataInicio=2024-01-01&page=1" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

curl -s "https://indiceapi.com.br/api/v1/disponibilidade/ufir-rj?competencia=2026&page=1&limit=40" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

curl -s "https://indiceapi.com.br/api/v1/disponibilidade/ufemg?exercicio=2026&page=1&limit=40" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

curl -s "https://indiceapi.com.br/api/v1/disponibilidade/vrte-es?competencia=2026&page=1&limit=40" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

curl -s "https://indiceapi.com.br/api/v1/disponibilidade/vmac-es?referencia=julho%2F2026&page=1&limit=40" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

curl -s "https://indiceapi.com.br/api/v1/disponibilidade/uferms?ano=2026&page=1&limit=40" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

curl -s "https://indiceapi.com.br/api/v1/disponibilidade/uam-ms?referencia=08%2F2026&page=1&limit=40" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

A tabela abaixo resume os endpoints públicos da API de Disponibilidade que você deve utilizar na integração. Todos os caminhos são relativos à base https://indiceapi.com.br/api/v1.

Parâmetros frequentes — GET /indices

• codigo (obrigatório) — código da série no catálogo
• dataInicio / dataFim — filtro AAAA-MM-DD
• instituicao — BANCO_CENTRAL, IBGE, IPEA, TESOURO_NACIONAL
• page — página (padrão 1, 40 itens por página)

A segurança da ÍndiceAPI foi projetada em camadas: credenciais de longa duração (API Key e licença) são usadas apenas para obter tokens de curta duração; o tráfego é criptografado em HTTPS; limites por plano evitam abuso; e todas as operações relevantes geram logs para auditoria.

Token temporário (20 horas)

Após autenticar em POST /auth, você recebe um JWT com escopo disponibilidade válido por 20 horas. Utilize-o no header Authorization: Bearer <accessToken>. Recomendamos renovar antes de 19 horas e nunca expor o token em URLs públicas ou repositórios.

Timeout do cliente

Configure timeout de pelo menos 30 segundos nas suas requisições HTTP. Consultas com intervalos de data muito amplos podem levar mais tempo — prefira paginar e filtrar por período.

Chave do usuário (API Key — ind_)

1. 1Faça login no painel Cliente em indiceapi.com.br/login.
2. 2No Dashboard, localize o bloco "Keys do usuário (API Keys)".
3. 3Informe um nome descritivo (ex.: "ERP Produção") e clique em "Gerar API Key".
4. 4Copie e guarde a chave (prefixo ind_) imediatamente — ela só é exibida uma vez.
5. 5Respeite o limite de chaves do seu plano; se atingir o limite, desative ou exclua uma chave antiga.
6. 6Se perder a chave, gere uma nova — não é possível recuperar o valor anterior.

Administradores (master) também podem gerar chaves para o cliente em Painel Master → Usuários → selecionar o usuário.

Chave de licença (lic_)

A chave de licença é vinculada à sua conta e enviada posteriormente pela nossa equipe ao e-mail cadastrado, após liberação do acesso. Ela não aparece no painel por segurança. Sem a licença válida, o endpoint /auth não gera token. Guarde-a com o mesmo cuidado da API Key.

Status ATIVO obrigatório

Somente usuários com status ATIVO conseguem autenticar e consultar a API. Status PENDENTE, INATIVO, BLOQUEADO ou EXPIRADO resultam em erro 401/403 com mensagem explicativa.

{
  "documento": "00000000000",
  "chaveUsuario": "ind_a1b2c3d4e5f6789012345678901234567890abcd",
  "chaveLicenca": "lic_f1e2d3c4b5a6978012345678901234567890abcd"
}

A API utiliza códigos HTTP padrão. A tabela abaixo lista as mensagens mais comuns retornadas pela API de Disponibilidade e pelo sistema de autenticação. O corpo da resposta é JSON com o campo message (string ou array de strings).

Esta documentação é mantida pela equipe ÍndiceAPI e pode ser atualizada a qualquer momento para refletir novos endpoints, parâmetros, políticas de limite ou melhorias de segurança. Recomendamos consultar esta página periodicamente e acompanhar o Swagger oficial para a versão mais recente dos contratos.

O catálogo de índices também é dinâmico: novas séries são incluídas conforme disponibilidade das fontes oficiais e índices podem ser descontinuados quando as instituições os substituem. A listagem pública do site e o endpoint GET /catalogo sempre refletem o estado atual do catálogo ativo.