Ir para o conteúdo

Calendário de feriados

Os prazos da propriedade industrial chilena são contados em dias úteis, então o corpus mantém o calendário de feriados legais para os seus próprios cálculos (janelas de oposição, prazos de apelação). Este guia cobre o endpoint que o expõe, para que você calcule esses mesmos prazos por conta própria — e audite os nossos.

O esquema completo e sempre atualizado por campo vive na referência OpenAPI interativa em /docs (Scalar). Este guia explica o contrato e aponta para essa referência — não reescreve o esquema. Quando um campo não está documentado aqui, /docs é autoritativo.

Ao longo do guia a URL base é escrita como $TARNO_BASE_URL e a chave como $TARNO_API_KEY, e cada chamada leva o cabeçalho X-API-Key.

GET /holidays · scope insights:read · equivalente MCP: list_holidays

curl -sS "$TARNO_BASE_URL/holidays?year=2026" -H "X-API-Key: $TARNO_API_KEY"
{
  "results": [
    { "date": "2026-01-01", "name": "Año Nuevo", "type": "regular", "origin": "seed:reglas-permanentes" },
    { "date": "2026-04-03", "name": "Viernes Santo", "type": "regular", "origin": "seed:reglas-permanentes" }
  ],
  "limit": …, "next": null, "hasMore": false, "total": …,
  "meta": { "dataAsOf": "2026-10-05T05:41:47.891Z", "coverageThrough": "2030-12-31", "coverage": { "from": "2013-01-01", "to": "2030-12-31" } }
}
Parâmetro O que faz
year Atalho para um ano inteiro.
from / to Intervalo explícito e inclusivo (ISO YYYY-MM-DD). Quando informados, prevalecem sobre year.
type regular ou excepcional (veja abaixo).

⛔ Desde 2026-09-23 os nomes antigos desde / hasta / anio / tipo deixaram de existir: pedir com eles é um 400 validation_error cujo detail nomeia o parâmetro novo (por exemplo `desde` was renamed: use `from`). O mesmo vale para qualquer parâmetro que a rota não conheça (envelope incluído): nada é descartado em silêncio.

Regulares frente a excepcionais

Cada linha declara se um algoritmo consegue reproduzi-la:

  • regular — derivada das regras permanentes: datas fixas, o computus da Páscoa, os deslocamentos para segunda/sexta das leis 19.668 e 20.299 e os feriados adicionais das Fiestas Patrias e do Ano-Novo das leis 20.215 e 20.983 (se 18 e 19 caem terça-quarta, a segunda dia 17 é feriado; quarta-quinta, a sexta dia 20; sábado-domingo, a sexta dia 17; e se 1º de janeiro cai num domingo, a segunda dia 2).
  • excepcional — criada por uma lei ad-hoc para um único dia de um único ano, ou por um decreto de eleição. Nenhuma regra a produz: só pode ser lida de uma lista.

origin completa o quadro dizendo de onde saiu aquela linha (Ley 20.215, Ley 21.462, decreto:dia-de-eleccion, seed:reglas-permanentes). Um origin que começa por loader: marca uma linha escrita pelo refresco automático, e não por uma migração revista.

A distinção não é acadêmica. O feriado de sexta-feira 2024-09-20 faltava no calendário, e a sua ausência rompia o teto legal de 15 dias úteis do prazo de apelação em 65 casos medidos. Um feriado ausente não aparece até deslocar um prazo.

# quais feriados nenhum cálculo automático consegue reproduzir?
curl -sS "$TARNO_BASE_URL/holidays?type=excepcional" -H "X-API-Key: $TARNO_API_KEY"

A cobertura é finita — e é um dado, não uma dedução

O calendário cobre um intervalo de anos declarado explicitamente. Fora dele não há dado, e isso não significa que não haja feriados: significa que não sabemos. A diferença não é académica — são coisas opostas:

  • não há feriados nesse trecho → a sua contagem de dias úteis está correta;
  • esse trecho não está carregado → a contagem degrada para só-fins-de-semana e devolve um prazo mais longo do que o real, sem que nada falhe. Esse é o erro perigoso: diria a um advogado que tem mais tempo do que tem.
curl -sS "$TARNO_BASE_URL/holidays" -H "X-API-Key: $TARNO_API_KEY"
{ "results": [ … ], "meta": { "coverage": { "from": "2013-01-01", "to": "2030-12-31" }, … } }

GET /holidays · scope insights:read · equivalente MCP: list_holidays

É barato e cacheável (Cache-Control: public, max-age=3600), por isso, se congelar o calendário no seu repositório, pode escrever este intervalo junto aos dados e o seu artefacto passa a dizer de que anos responde.

Não é o min/max das linhas, e é aí que está toda a graça. O min/max descreve o que existe, não o que o calendário afirma: se um ano entrasse pela metade — só o Natal, por exemplo — o min/max diria «cubro até esse 25 de dezembro» e congelaria um ano a 5 % julgando-o completo. O intervalo só avança quando um ano está inteiro, e por isso termina a 31 de dezembro do último ano declarado e não no dia do último feriado.

Pedir fora do intervalo é um erro, nunca uma lista vazia

curl -sS "$TARNO_BASE_URL/holidays?from=2031-01-01&to=2031-12-31" -H "X-API-Key: $TARNO_API_KEY"
{
  "type": "https://api.tarno.cl/problems/out_of_coverage",
  "title": "Business rule not satisfied",
  "status": 422,
  "detail": "El calendario cubre 2013-01-01 → 2030-12-31; el rango pedido lo excede.",
  "code": "out_of_coverage",
  "requestId": "…",
  "coverage": { "from": "2013-01-01", "through": "2030-12-31" }
}

HTTP 422. Nunca um 200 com lista vazia ou parcial. O intervalo viaja dentro do erro, por isso não precisa de uma segunda chamada para saber contra o que bateu. Em MCP o mesmo caso devolve um resultado de erro com o mesmo code e a mesma coverage.

Dois detalhes de contorno:

  • Um extremo aberto não é erro. ?from=2030-12-01 é limitado pelo que existir; só se verificam os limites que indica explicitamente.
  • Dentro do intervalo, vazio significa vazio. ?from=2026-02-01&to=2026-02-28 devolve [] com um 200 porque fevereiro de 2026 não tem feriados, e isso é um dado fiável.

A cobertura declarada viaja sempre em meta.coverage —{ "from", "to" }—, sem nenhuma flag: uma só chamada traz os feriados e o intervalo a que respondem.

meta.coverageThrough é o último dia com calendário declarado (o to de meta.coverage): os prazos que terminam até essa data são contados com feriados declarados; um que termine depois não pode ser contado com este calendário. É a sequência contígua de anos declarados: um ano não declarado no meio a interrompe.

Com que frequência é atualizado

Um trabalho semanal atualiza a janela de hoje até dois anos à frente: dá entrada aos feriados novos (uma lei ad-hoc costuma ser publicada com poucas semanas de antecedência) e retira os que deixam de o ser — o caso típico é uma eleição que muda da data planeada para a data em que se realizou. Fora dessa janela o calendário só muda por uma migração revista. meta.dataAsOf é o instante da última carga bem-sucedida desse trabalho (não a sincronização de marcas nem a hora da sua requisição); null se nenhuma terminou.

Uma nuance a ter em conta se calcular prazos muito à frente: os feriados regulares derivam das regras permanentes e por isso cobrem a janela inteira, mas os excepcionais só se detetam até onde chegam as fontes públicas que os publicam — hoje pouco mais de um ano. Para qualquer prazo em curso é de sobra: o mais longo do sistema são 30 dias úteis.

Contar dias úteis com este calendário

Se o que você precisa é a data do N.º dia útil depois de uma âncora, não precisa calculá-la: GET /business-days (MCP: compute_business_days) conta com este mesmo calendário —o mesmo cômputo da janela de oposição— e devolve a data, os fins de semana e feriados que pulou, a cobertura que usou e a norma do cômputo; e a marca como estimativa quando o trecho sai da cobertura declarada.