Documentação da API

Bem-vindo à documentação oficial da Feriados API. Nossa API REST fornece dados precisos sobre feriados nacionais, estaduais e municipais do Brasil. Todos os endpoints retornam dados em formato JSON e utilizam códigos de status HTTP padrão.

Referência Interativa da API

Explore nossos endpoints em tempo real com nossa documentação interativa. Teste requisições diretamente do navegador e valide sua integração instantaneamente.

Abrir Referência API

Base URL:

https://feriadosapi.com

OpenAPI Spec (YAML)

Escolha a linguagem dos exemplos

Limites de Uso e Planos

A Feriados API oferece diferentes níveis de serviço dependendo do seu plano. Entender os limites é fundamental para garantir a estabilidade da sua integração.

Plano Free

Acesso a feriados Nacionais e Estaduais
Acesso às 27 capitais estaduais
Rate Limit: 60 requisições por minuto

Planos Pagos

Acesso a todos os 5.570 municípios
Verificação de data e endpoints avançados
Sem Rate Limit (Alta Velocidade)

Nota sobre o Plano Free: O limite de 60 RPM (requisições por minuto) é aplicado de forma global por token. Caso precise de maior volume ou acesso a municípios do interior, considere um de nossos planos profissionais.

Autenticação

Todas as requisições devem incluir sua chave de API no cabeçalho Authorization. Você pode obter sua chave no Dashboard.

Ainda não tem uma chave de API?

Crie sua conta gratuita agora mesmo e comece a integrar.

Criar Conta Grátis

Header example

bash

Authorization: Bearer seu_token_aqui

Paginação e Filtros

A API suporta paginação via parâmetros de query em endpoints de listagem. Além disso, todos os endpoints retornam metadados úteis sobre a resposta no objeto meta.

Parâmetros de Query

Parâmetro	Descrição	Padrão
page	Número da página atual	1
limit	Quantidade de itens por página (max 100)	50
ano	Filtra feriados por ano (ex: 2026)	Todos
facultativos	Se `true`, inclui feriados facultativos	false

Feriados Nacionais

GETGratuito

Retorna todos os feriados nacionais de um determinado ano.

Endpoint

/api/v1/feriados/nacionais?ano=2026

Exemplo (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/feriados/nacionais?ano=2026" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Exemplo de Resposta

json

{
  "tipo": "NACIONAL",
  "ano": "2026",
  "feriados": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "data": "01/01/2026",
      "nome": "Confraternização Universal",
      "tipo": "NACIONAL"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "data": "25/12/2026",
      "nome": "Natal",
      "tipo": "NACIONAL"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

Feriados Estaduais

GETGratuito

Retorna feriados estaduais (incluindo nacionais) de uma UF específica.

Endpoint

/api/v1/feriados/estado/{uf}?ano=2026

Exemplo (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/feriados/estado/SP?ano=2026" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Exemplo de Resposta (SP)

json

{
  "uf": "SP",
  "ano": "2026",
  "feriados": [
    {
      "id": "...",
      "data": "09/07/2026",
      "nome": "Revolução Constitucionalista",
      "tipo": "ESTADUAL"
    }
    // ... feriados nacionais incluídos
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

Feriados Municipais

GETCapitais GratuitoOutros Consome Cota

Retorna todos os feriados (municipais, estaduais e nacionais) de uma cidade específica pelo código IBGE.

Gratuito para as 27 capitais estaduais. Demais municípios consome 1 unidade da cota mensal.

Endpoint

/api/v1/feriados/cidade/{ibge}?ano=2026

Exemplo (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/feriados/cidade/3550308?ano=2026" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Exemplo de Resposta (São Paulo - 3550308)

json

{
  "cidade": {
    "ibge": 3550308,
    "nome": "São Paulo",
    "uf": "SP"
  },
  "ano": "2026",
  "feriados": [
    {
      "id": "...",
      "data": "25/01/2026",
      "nome": "Aniversário de São Paulo",
      "tipo": "MUNICIPAL"
    },
    {
      "id": "...",
      "data": "20/11/2026",
      "nome": "Consciência Negra",
      "tipo": "MUNICIPAL"
    }
  ],
  "meta": {
    "total": 18,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

Verificar Data

GETConsome Cota

Verifica se uma data específica é feriado. Retorna 404 se não for.

Atenção: Este endpoint está disponível apenas nos planos pagos e consome 1 unidade da sua cota mensal por consulta.

Endpoint

/api/v1/feriados/data/{ano-mes-dia}

Exemplo (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/feriados/data/2026-12-25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Feriados Bancários

A API inclui o calendário bancário oficial baseado na Resolução 4.880/2020 do CMN e no calendário da FEBRABAN. Todos os endpoints retornam o campo bancario (booleano) indicando se o feriado é bancário. Inclui todos os feriados nacionais mais datas facultativas em que agências não funcionam: Carnaval (seg/ter), Quarta-feira de Cinzas (expediente após meio-dia), Corpus Christi e Véspera de Ano Novo (31/dez).

Filtrar apenas feriados bancários

Adicione ?bancarios=true a qualquer endpoint existente para retornar somente feriados bancários.

bash

GET /api/v1/feriados/nacionais?ano=2026&bancarios=true

Endpoint dedicado: Listar feriados bancários

Gratuito

json

GET /api/v1/feriados/bancarios?ano=2026

// Resposta
{
  "tipo": "BANCARIO",
  "ano": "2026",
  "feriados": [
    {
      "id": 1,
      "data": "01/01/2026",
      "nome": "Confraternização Universal",
      "tipo": "NACIONAL",
      "bancario": true
    }
  ],
  "meta": { "total": 13, "page": 1, "per_page": 50, "total_pages": 1 }
}

Parâmetros opcionais: uf, ibge, facultativos.

Verificar dia útil bancário

Gratuito

json

GET /api/v1/feriados/dia-util-bancario/2026-02-16

// Resposta
{
  "data": "2026-02-16",
  "dia_util_bancario": false,
  "motivo": "Carnaval (Segunda-feira)",
  "proximo_dia_util": "2026-02-18"
}

Retorna se a data é dia útil bancário. Se não for, informa o motivo e o próximo dia útil. Formato da data: YYYY-MM-DD.

Listar Estados

GETGratuito

Retorna a lista de todas as Unidades Federativas (UFs) e seus nomes.

Endpoint

/api/v1/estados

Exemplo (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/estados" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Exemplo de Resposta

json

{
  "estados": [
    {
      "uf": "RO",
      "nome": "Rondônia"
    },
    // ...
  ],
  "total": 27
}

Listar Municípios

GETGratuito

Retorna a lista completa de todos os 5.570 municípios brasileiros.

Endpoint

/api/v1/municipios

Exemplo (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/municipios" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Exemplo de Resposta

json

{
  "municipios": [
    {
      "ibge": "3550308",
      "nome": "São Paulo",
      "uf": "SP"
    }
  ],
  "meta": {
    "total": 5570,
    "page": 1,
    "per_page": 50,
    "total_pages": 112
  }
}

Buscar Município

GETGratuito

Retorna os dados de um município específico pelo código IBGE.

Endpoint

/api/v1/municipio/{ibge}

Exemplo (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/municipio/3550308" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Exemplo de Resposta (São Paulo - 3550308)

json

{
  "ibge": 3550308,
  "nome": "São Paulo",
  "uf": "SP"
}

Glossário e Modelos

Tipos de Feriados

NACIONALFeriado válido em todo o território brasileiro.
ESTADUALFeriado válido apenas em um estado específico (UF).
MUNICIPALFeriado válido apenas no município específico (ex: Aniversário da cidade).
FACULTATIVOPonto facultativo. A adesão é opcional (ex: Carnaval, Corpus Christi em alguns locais).

Objeto Feriado

json

{
  "id": "UUID",          // Identificador único
  "data": "DD/MM/YYYY",  // Data oficial
  "nome": "String",      // Nome do feriado
  "tipo": "Enum",        // NACIONAL | ESTADUAL | MUNICIPAL | FACULTATIVO
  "descricao": "String", // Contexto histórico
  "uf": "SP",            // (Opcional) UF do feriado
  "codigo_ibge": 12345,  // (Opcional) IBGE do mun.
  "bancario": true       // Feriado bancário (FEBRABAN)
}

Agentes de IA via MCP

Site Exclusivo do Servidor MCP

Para ver opções avançadas, como configuração para VS Code, Copilot, Cursor e guias completos para Frameworks, acesse nosso portal dedicado a integração com Model Context Protocol.

Acessar mcp.feriadosapi.com

Além da nossa clássica API REST, a Feriados API é o Primeiro Servidor Model Context Protocol (MCP) de Feriados do Brasil. Com ele, você fornece contexto local preciso sobre regras de datas e feriados para Agentes de IA desenvolvidos nas plataformas OpenAI, Gemini, Claude, Manus e outras. Permita que suas aplicações autônomas resolvam problemas complexos do mundo real (como planejar pacotes de viagens, calcular a logística ou analisar contratos e faturas).

1. Conexão Remota (Recomendada)

Configure via URL conectando a API no seu cliente.

https://mcp.feriadosapi.com/api/mcp?apiKey=SUA_KEY

2. Conexão Local (npx)

Execute diretamente via CLI (Node.js/npm).

npx -y @feriados-api/mcp-server
# Lembre-se de configurar a variável # de ambiente FERIADOS_API_KEY

Conecte sua Aplicação

Exemplo: Arquivo de configuração (Clientes e Frameworks MCP)

json

{
  "mcpServers": {
    "feriadosapi": {
      "url": "https://mcp.feriadosapi.com/api/mcp?apiKey=SUA_API_KEY"
    }
  }
}

Casos de Uso Reais para a sua IA:

Agente de Logística: "Calcule o prazo de entrega final para Salvador, ignorando a contagem de tempo durante finais de semana, feriados nacionais e feriados estaduais na Bahia."
Agente de Viagens: "Monte um roteiro em Ouro Preto na próxima semana. Evite marcar atrações na terça caso seja um feriado municipal."
Agente de RH/DP: "Gere o fechamento do ponto deste mês identificando todas as horas extras feitas durante emendas e pontos facultativos da base São Paulo."
Assistente Financeiro: "Verifique este lote de faturas e antecipe o pagamento bancário daquelas cujos vencimentos coincidirão com feriados."

Tools Injetadas no Agente

buscar_feriadosBusca completa com filtros flexíveis (data, tipo, UF, IBGE, ano, bancarios).

feriados_nacionaisLista de todos os feriados nacionais.

feriados_por_estadoBusca feriados estaduais usando a sigla UF.

feriados_por_cidadeBusca feriados municipais usando código IBGE.

feriados_bancariosLista feriados bancários FEBRABAN. Filtros: ano, UF, IBGE.

verificar_dia_util_bancarioVerifica se uma data é dia útil bancário (motivo + próximo dia útil).

verificar_dataVerifica se uma data (YYYY-MM-DD) é feriado.

listar_estadosLista estados e UFs (dá contexto).

buscar_municipiosBusca código IBGE de cidades.