> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /public-holidays

> Recupere a lista de feriados nacionais de qualquer país e ano.

## Endpoint

```
POST https://api.bunny.build/api/v1/public-holidays
```

## Autenticação

| Header         | Obrigatório | Valor                        |
| -------------- | ----------- | ---------------------------- |
| `X-API-Key`    | Sim         | Sua chave de API (`bun_...`) |
| `Content-Type` | Sim         | `application/json`           |

## Visão geral

Recupere uma lista completa de feriados nacionais para qualquer país suportado, com filtro opcional por ano. Retorna os nomes dos feriados no idioma local junto com datas ISO, permitindo agendamentos conscientes de datas, cálculos de SLA e integrações com calendários.

## Casos de uso

* Ignorar feriados em cálculos de dias úteis
* Exibir feriados regionais em interfaces de agendamento ou calendário
* Automatizar ajustes de prazo de SLA em torno de feriados nacionais
* Construir sistemas de folha de pagamento ou controle de ponto conscientes de países

## Detalhes

Cobre mais de 100 países. Os dados de feriados incluem observâncias nacionais e regionais. O campo `year` tem como padrão o ano atual quando omitido. Os códigos de país seguem o padrão ISO 3166-1 alpha-2 (ex.: `BR`, `US`, `DE`).

## Corpo da requisição

| Campo     | Tipo   | Obrigatório | Descrição                                           |
| --------- | ------ | ----------- | --------------------------------------------------- |
| `country` | string | Sim         | Código de país ISO 3166-1 alpha-2 (ex.: `BR`, `US`) |
| `year`    | number | Não         | Ano para buscar os feriados (padrão: ano atual)     |

### Exemplo

```json theme={null}
{
  "country": "BR",
  "year": 2025
}
```

## Resposta

### 200 OK

| Campo      | Tipo      | Descrição                   |
| ---------- | --------- | --------------------------- |
| `country`  | string    | Código de país ISO          |
| `year`     | number    | Ano dos feriados            |
| `holidays` | object\[] | Array de objetos de feriado |

Cada objeto de feriado:

| Campo  | Tipo   | Descrição                              |
| ------ | ------ | -------------------------------------- |
| `date` | string | Data ISO 8601 (YYYY-MM-DD)             |
| `name` | string | Nome do feriado no idioma local        |
| `type` | string | `national`, `regional` ou `observance` |

**Exemplo**

```json theme={null}
{
  "country": "BR",
  "year": 2025,
  "holidays": [
    { "date": "2025-01-01", "name": "Confraternização Universal", "type": "national" },
    { "date": "2025-04-21", "name": "Tiradentes", "type": "national" },
    { "date": "2025-09-07", "name": "Independência do Brasil", "type": "national" }
  ]
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Unknown country code"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/public-holidays \
  -H "X-API-Key: bun_sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{"country": "BR", "year": 2025}'
```