Documentação — API de Feriados

API REST com feriados nacionais, estaduais e municipais do Brasil. Respostas em JSON, datas em ISO 8601 (AAAA-MM-DD), autenticação por chave no cabeçalho.

URL base

https://api.muhbianco.com.br/api/latest

/api/latest aponta sempre para a versão estável mais recente. Se você preferir travar a versão, use /api/v1 — o contrato desta página é o mesmo nos dois.

Autenticação

Toda chamada precisa do cabeçalho X-API-Key. A chave começa com mbk_ e é gerada na sua conta, em Serviços → API de Feriados → Configurações do serviço. 

curl -H "X-API-Key: mbk_sua_chave_aqui" \
  "https://api.muhbianco.com.br/api/latest/feriados?ano=2026&uf=SP"

Como escolher a localidade

Os três endpoints aceitam os mesmos filtros. Só ano é obrigatório em /feriados. A regra é:

Município ou UF inexistentes devolvem 404. Não envie a chave vazia (ibge=): omita o parâmetro.

GET /feriados

Lista os feriados de um ano para a localidade escolhida.

Parâmetros

Exemplo

curl -H "X-API-Key: mbk_sua_chave_aqui" \
  "https://api.muhbianco.com.br/api/latest/feriados?ano=2026&cidade=São Paulo&uf=SP"
{
  "ano": 2026,
  "localidade": {
    "uf": "SP",
    "municipio_ibge": "3550308",
    "municipio_nome": "São Paulo"
  },
  "inclui_facultativos": false,
  "total": 14,
  "feriados": [
    {
      "data": "2026-09-07",
      "nome": "Independência do Brasil",
      "tipo": "national",
      "abrangencia": "national",
      "escopo": "BR",
      "uf": null,
      "recorrencia": "fixed",
      "base_legal": "Lei nº 662/1949",
      "fonte_url": null,
      "confianca": 100,
      "verificado": true
    }
  ]
}

Campos de cada feriado

GET /feriados/dias-uteis

Conta os dias úteis entre duas datas, já descontando sábado, domingo e os feriados da localidade. Útil para prazo contratual, SLA e folha.

Parâmetros

Exemplo

curl -H "X-API-Key: mbk_sua_chave_aqui" \
  "https://api.muhbianco.com.br/api/latest/feriados/dias-uteis?de=2026-09-01&ate=2026-09-11&uf=SP"
{
  "inicio": "2026-09-01",
  "fim": "2026-09-11",
  "localidade": { "uf": "SP", "municipio_ibge": null, "municipio_nome": null },
  "considera_facultativos": false,
  "dias_corridos": 11,
  "dias_uteis": 8,
  "feriados": [
    {
      "data": "2026-09-07",
      "nome": "Independência do Brasil",
      "tipo": "national",
      "abrangencia": "national",
      "escopo": "BR",
      "uf": null,
      "recorrencia": "fixed",
      "base_legal": "Lei nº 662/1949",
      "fonte_url": null,
      "confianca": 100,
      "verificado": true
    }
  ]
}

Ponto facultativo não reduz o total a menos que você passe facultativos=true. Feriado que cai no fim de semana não é descontado duas vezes.

GET /feriados/cobertura

Responde o que existe de dado para aquela localidade, por nível. É o endpoint honesto: em vez de devolver lista vazia e deixar você achar que o município não tem feriado, ele diz em que estágio aquele município está.

Parâmetros

Exemplo

curl -H "X-API-Key: mbk_sua_chave_aqui" \
  "https://api.muhbianco.com.br/api/latest/feriados/cobertura?ibge=3550308"
{
  "localidade": {
    "uf": "SP",
    "municipio_ibge": "3550308",
    "municipio_nome": "São Paulo"
  },
  "niveis": [
    { "nivel": "national",  "status": "published", "atualizado_em": "2026-08-17T12:00:00Z", "fontes_ativas": 0 },
    { "nivel": "state",     "status": "published", "atualizado_em": "2026-08-17T12:00:00Z", "fontes_ativas": 0 },
    { "nivel": "municipal", "status": "none",      "atualizado_em": null,                   "fontes_ativas": 0 }
  ]
}

Valores de status

Nacionais e as datas magnas das 27 unidades federativas são determinísticos e vêm como published. O nível municipal é trabalho contínuo — consulte a cobertura antes de assumir que o silêncio significa "não há feriado".

Erros

Todo erro devolve o mesmo formato:

{
  "error": "rate_limited",
  "message": "Cota diária de requisições atingida. O contador zera à meia-noite (UTC).",
  "details": { "retry_after_seconds": 18240, "limit": 10000, "used": 10000 },
  "request_id": "0f2a…"
}

Guarde o request_id ao abrir chamado: é com ele que localizamos a requisição no log.

Cota e limites

Boas práticas

Como obter uma chave

A jornada é exclusiva deste produto: conta, saldo, habilitar a API e gerar a chave. Não passa pelo WhatsApp e não abre o painel genérico no meio.

  1. Crie a conta (Google ou e-mail).
  2. Adicione saldo pelo Mercado Pago (PIX ou cartão).
  3. Aceite os termos e habilite a API de Feriados.
  4. Gere a chave neste mesmo fluxo. Copie na hora — ela não aparece de novo.
Começar a API de Feriados Voltar para a visão geral