API Kalender Indonesia: Integrasi Hari Libur Nasional untuk HR, Payroll, dan Aplikasi

Setiap awal tahun, tim HR dan developer aplikasi internal menjalankan ritual yang sama: menyalin daftar tanggal merah dari berita, mengetiknya ke spreadsheet atau tabel database, lalu berdoa tidak ada yang salah ketik. Masalahnya, SKB 3 Menteri bisa terbit belakangan, cuti bersama bisa berubah, dan satu tanggal yang terlewat cukup untuk merusak perhitungan payroll atau jadwal SLA.

API Kalender Indonesia dari API Indonesia menyelesaikan ini: daftar hari libur nasional, hari besar keagamaan, dan cuti bersama yang bersumber dari SKB 3 Menteri, diakses lewat REST API. Tidak ada lagi update manual tiap tahun.

Endpoint yang Dipakai

Base URL: https://use.apiindonesia.id/api/v1/libur

Method	Endpoint	Parameter	Keterangan
GET	/	tahun, bulan (dua digit)	Daftar hari libur, bisa difilter per tahun dan bulan
GET	/upcoming	tanpa parameter	Maksimal 10 hari libur berikutnya dari hari ini
GET	/:id	ID hari libur	Detail satu hari libur, contoh: hol_2026_014

Field penting di respons: date, name, type (misal nasional), dan is_joint_leave yang menandai cuti bersama.

Contoh Request dan Response

Ambil semua hari libur tahun 2026:

curl "https://use.apiindonesia.id/api/v1/libur?tahun=2026" \
  -H "x-api-key: aip_li...x"

Response:

{
  "data": [
    {
      "id": "hol_2026_001",
      "date": "2026-01-01",
      "name": "Tahun Baru 2026 Masehi",
      "type": "nasional",
      "is_joint_leave": 0,
      "source": "SKB 3 Menteri"
    }
  ]
}

Untuk banner "libur berikutnya" di dashboard karyawan:

curl "https://use.apiindonesia.id/api/v1/libur/upcoming" \
  -H "x-api-key: aip_li...x"

Integrasi ke Sistem HR/Payroll

Kasus paling umum: menghitung hari kerja efektif dalam satu bulan untuk prorata gaji, jatah cuti, atau SLA tiket.

import requests
from datetime import date, timedelta

def working_days(api_key: str, year: int, month: int) -> int:
    r = requests.get(
        "https://use.apiindonesia.id/api/v1/libur",
        params={"tahun": year, "bulan": f"{month:02d}"},
        headers={"x-api-key": api_key},
    )
    r.raise_for_status()
    holidays = {row["date"] for row in r.json()["data"]}

    first = date(year, month, 1)
    if month == 12:
        nxt = date(year + 1, 1, 1)
    else:
        nxt = date(year, month + 1, 1)

    count = 0
    d = first
    while d < nxt:
        if d.weekday() < 5 and d.isoformat() not in holidays:
            count += 1
        d += timedelta(days=1)
    return count

print(working_days("aip_live_xxx", 2026, 6))

Versi JavaScript untuk aplikasi Node:

async function isWorkingDay(dateStr) {
  const url = `https://use.apiindonesia.id/api/v1/libur?tahun=${dateStr.slice(0, 4)}&bulan=${dateStr.slice(5, 7)}`;
  const res = await fetch(url, {
    headers: { "x-api-key": process.env.API_INDONESIA_KEY },
  });
  const { data } = await res.json();
  const day = new Date(dateStr + "T00:00:00+07:00").getDay();
  const isWeekend = day === 0 || day === 6;
  const isHoliday = data.some((h) => h.date === dateStr);
  return !isWeekend && !isHoliday;
}

Pola yang Sering Dibutuhkan

• Payroll: hitung hari kerja efektif untuk prorata gaji karyawan yang masuk/keluar di tengah bulan.
• HR-tech: validasi pengajuan cuti, tolak tanggal yang jatuh di hari libur atau cuti bersama.
• Logistik dan SLA: hitung tanggal jatuh tempo dengan memperhitungkan tanggal merah, bukan asumsi 30 hari flat.
• Aplikasi kalender: sinkronkan hari libur ke kalender pengguna dengan job harian yang memanggil /upcoming. Kalau aplikasi Anda menyasar pengguna Muslim, pasangkan juga dengan API Jadwal Sholat untuk 514 kabupaten/kota agar reminder ibadah ikut menghormati hari besar keagamaan.

Catatan Teknis

• Auth pakai header x-api-key, sama seperti produk API Indonesia lainnya.
• Simpan source dari respons di log Anda untuk audit; sumbernya SKB 3 Menteri.
• Cache respons per tahun, hari libur jarang berubah setelah SKB terbit. Tetap refresh berkala untuk menangkap revisi cuti bersama.
• Field is_joint_leave bernilai 1 untuk cuti bersama; sebagian perusahaan memperlakukannya beda dari libur nasional murni.

FAQ

Apakah mencakup cuti bersama? Ya, ditandai lewat field is_joint_leave.

Tahun yang didukung? Mengikuti terbitnya SKB 3 Menteri; filter tahun yang tersedia di dataset, contoh: 2026.

Berapa biayanya? Tier Free 1.000 hits/bulan, cukup untuk job harian dan environment staging.

Mulai Sekarang

Pelajari detail parameter di halaman produk API Hari Libur, dapatkan API key gratis di dashboard.apiindonesia.id/register, dan baca referensi lengkap di docs.apiindonesia.id.