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.

Base URL:

https://feriadosapi.com

Escolha a linguagem dos exemplos

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

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

GET

Retorna todos os feriados nacionais de um determinado ano.

Endpoint

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

Exemplo (curl)

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

Exemplo de Resposta

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

GET

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

Endpoint

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

Exemplo (curl)

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

Exemplo de Resposta (SP)

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

GET

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

Endpoint

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

Exemplo (curl)

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)

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

GET

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

Endpoint

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

Exemplo (curl)

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

Listar Estados

GET

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

Endpoint

/api/v1/estados

Exemplo (curl)

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

Exemplo de Resposta

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

Listar Municípios

GET

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

Endpoint

/api/v1/municipios

Exemplo (curl)

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

Exemplo de Resposta

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

Buscar Município

GET

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

Endpoint

/api/v1/municipio/{ibge}

Exemplo (curl)

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

Exemplo de Resposta (São Paulo - 3550308)

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

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

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)

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

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.

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

listar_estadosLista estados e UFs (dá contexto).

buscar_municipiosBusca código IBGE de cidades.