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? Rp2 per request yang berhasil. Akun baru mendapat bonus 3.000 kredit sekali saat daftar (tanpa kartu kredit), cukup untuk sekitar 1.500 request data, 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.