Ana Sayfa / Blog / Mevzuat & Hukuk

Mevzuat & Hukuk

İş Günü Hesaplama API Entegrasyonu: Fatura Vadesi, Teslimat SLA ve Cron Planlama

Yazar: apibir Geliştirici Ekibi • 14 Eylül 2026 • 8 dk okuma süresi

Özet: Fatura vadesi, kargo teslimat SLA’sı ve cron planlaması Türkiye’de “takvim günü” ile değil iş günü ile yürür. Resmi tatiller, dini bayramlar ve hafta sonu (banka/mahkeme bağlamında Cumartesi dahil) son günü kaydırır. Bu yazıda apibir Resmi Tatiller & İş Günü API ile tatil listesini çekmeyi, N iş günü eklemeyi, iki tarih arası farkı hesaplamayı ve fatura / SLA / cron senaryolarını Node.js ile Python örnekleriyle adım adım entegre ediyoruz.

İçindekiler

Neden iş günü API’si kullanmalısınız?
Uç noktalar ve alanlar
Yıllık tatil listesi ve tek gün kontrolü
N iş günü ekleme ve sonraki iş günü
İki tarih arası iş günü farkı
Pratik senaryolar: fatura vadesi, teslimat SLA, cron
Ekonomik Takvim, Faiz ve Döviz ile birlikte kullanım
Sık yapılan hatalar
Sık sorulan sorular

Türkiye’de operasyonel tarihler çoğu zaman “+3 gün” veya “+7 gün” diye kodlanır; oysa HMK tarzı süre hesaplarında son gün resmi tatil veya hafta sonuna denk gelirse süre sonraki iş gününe uzar. Lojistikte “T+2 iş günü teslim”, muhasebede “vade Cuma’ya kaymasın”, DevOps’ta “tatilde faiz poll’u çalışmasın” aynı sorunun üç yüzüdür. apibir’in /holidays ve /business-days/* uçları Avrupa/İstanbul saat diliminde (UTC+3) resmi + dini tatilleri ve iş günü aritmetiğini tek zarfta sunar. Aşağıdaki rehber entegrasyonu uç nokta tablosu, örnek JSON ve kopyala-yapıştır kodlarla tamamlar.

Neden İş Günü API’si Kullanmalısınız?

Takvim aritmetiği “gün + N” değildir. Ürününüzün ihtiyacına göre şu katmanlar ayrı ayrı gelir:

Resmi / dini tatil listesi — yıl ve ülke (TR) bazlı; bayramın gözlemlenen günü (observedDate) dahil.
Gün tipi bayrakları — isWeekend, isHoliday, isBusinessDay, yarım gün (halfday).
İş günü aritmetiği — N gün ileri, iki tarih arası fark, “sonraki iş günü”.
Zaman dilimi tutarlılığı — Avrupa/İstanbul; gece yarısı kaymalarına karşı tarih alanları YYYY-MM-DD.

Manuel veya sabit listeyle tipik kırılmalar:

Eski liste: Geçen yılın bayram takvimi hâlâ kodda; yeni yılın arife yarım günü unutulmuş.
Cumartesi yanılgısı: Birçok TR banka/mahkeme bağlamında Cumartesi iş günü sayılmaz; “hafta içi = Pzt–Cum” varsayımı fatura vadesini yanlış kaydırır.
Dağınık cron’lar: Her servis kendi tatil listesini tutar; faiz poll’u tatilde çalışır, SLA sayacı yanlış artar.

API tabanlı kurgu üçünü birden çözer: güncel tatil kaynağı, sunucu tarafı aritmetik ve tek entegrasyon noktası. Kod yazmadan günlük özet isteyen ekipler için apibir WhatsApp / e-posta raporları da aynı veri ailesini kullanır.

Uç Noktalar ve Alanlar

Temel adres: https://api.apibir.com/v1

Uç	Ne döner
`GET /holidays`	Yıl / ülke bazlı resmi + dini tatiller (ve yarım günler)
`GET /holidays/check?date=YYYY-MM-DD`	Tek günün tatil / hafta sonu / iş günü durumu
`GET /business-days/add?start=&days=`	Başlangıçtan N iş günü sonraki tarih
`GET /business-days/diff?from=&to=`	İki tarih arası iş günü sayısı
`GET /business-days/next?date=`	Verilen tarihten sonraki (veya aynı gün iş günüyse o gün) iş günü

Kimlik doğrulama tüm apibir uçlarında aynıdır:

Authorization: apikey APIBIR-8f2c...9d41
Accept: application/json

Yanıt zarfı diğer servislerle ortaktır: success, data, creditsUsed, creditsRemaining. Her başarılı istek tipik olarak 1 kredi harcar; 4xx hataları kredi düşürmez. Yıllık tatil listesini gün başında bir kez çekip önbelleğe almak kredi kullanımını düşürür. Ücretsiz plan yaklaşık 100 kredi/ay ile geliştirme ve deneme için yeterlidir.

Sık görülen alanlar:

Alan	Örnek	Açıklama
`date`	`2026-10-29`	Takvim tarihi (İstanbul TZ günü)
`name`	`Cumhuriyet Bayramı`	Tatil adı
`type`	`national` \| `religious` \| `halfday`	Tatil tipi
`isWeekend`	`true/false`	Cmt/Paz (TR banka/mahkeme bağlamında)
`isHoliday`	`true/false`	Resmi veya dini tatil mi?
`isBusinessDay`	`true/false`	İş günü mü?
`observedDate`	`2026-10-29`	Gözlemlenen / uygulanan gün (kaydırma varsa)

Not: Cumartesi, Türkiye’de banka, mahkeme ve birçok kurumsal SLA bağlamında tipik olarak iş günü sayılmaz. Ürün kuralınız perakende “7/24 açık” ise hafta sonu politikasını kendi katmanınızda netleştirin; API varsayılanı kurumsal TR iş günü modeline yakındır.

1. Adım: Yıllık Tatil Listesi ve Tek Gün Kontrolü

cURL — 2026 tatilleri

curl --request GET \
  --url "https://api.apibir.com/v1/holidays?year=2026&country=TR" \
  --header "authorization: apikey APIBIR-8f2c...9d41" \
  --header "accept: application/json"

cURL — tek gün kontrolü

curl --request GET \
  --url "https://api.apibir.com/v1/holidays/check?date=2026-10-29" \
  --header "authorization: apikey APIBIR-8f2c...9d41" \
  --header "accept: application/json"

Node.js (fetch)

async function tatilleriGetir(year = 2026) {
  const url = new URL("https://api.apibir.com/v1/holidays");
  url.searchParams.set("year", String(year));
  url.searchParams.set("country", "TR");
  const res = await fetch(url, {
    headers: { authorization: `apikey ${process.env.APIBIR_KEY}` }
  });
  if (!res.ok) throw new Error(`apibir ${res.status}`);
  const { data } = await res.json();
  return data;
}

async function gunKontrol(date) {
  const url = new URL("https://api.apibir.com/v1/holidays/check");
  url.searchParams.set("date", date);
  const res = await fetch(url, {
    headers: { authorization: `apikey ${process.env.APIBIR_KEY}` }
  });
  if (!res.ok) throw new Error(`apibir ${res.status}`);
  const { data } = await res.json();
  return data;
}

const liste = await tatilleriGetir(2026);
const bugun = await gunKontrol("2026-09-14");
console.log(liste.length, bugun.isBusinessDay, bugun.isHoliday);

Python

import os, requests

HEADERS = {"authorization": f"apikey {os.environ['APIBIR_KEY']}"}
BASE = "https://api.apibir.com/v1"

def holidays(year=2026, country="TR"):
    r = requests.get(
        f"{BASE}/holidays",
        params={"year": year, "country": country},
        headers=HEADERS,
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["data"]

def holiday_check(date):
    r = requests.get(
        f"{BASE}/holidays/check",
        params={"date": date},
        headers=HEADERS,
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["data"]

for h in holidays(2026)[:5]:
    print(h["date"], h["name"], h["type"])

print(holiday_check("2026-10-29"))

Örnek yanıt iskeleti (dokümantasyondaki şemaya uygun, illüstratif):

{
  "success": true,
  "creditsUsed": 1,
  "creditsRemaining": 97,
  "timestamp": "2026-09-14T09:12:00+03:00",
  "data": {
    "date": "2026-10-29",
    "name": "Cumhuriyet Bayramı",
    "type": "national",
    "isWeekend": false,
    "isHoliday": true,
    "isBusinessDay": false,
    "observedDate": "2026-10-29",
    "timezone": "Europe/Istanbul"
  }
}

type: "halfday" arife gibi yarım günleri işaretler. SLA’nız “öğleden sonra kapalı” ise yarım günü iş günü saymama veya özel eşik uygulama kuralını ürün tarafında yazın; API bayrağı karar vermenizi kolaylaştırır.

2. Adım: N İş Günü Ekleme ve Sonraki İş Günü

Fatura vadesi ve teslimat pencereleri için en sık kullanılan uç /business-days/add’tir. start tarihinden itibaren days kadar iş günü ilerler; hafta sonu ve tatiller atlanır.

cURL

curl --request GET \
  --url "https://api.apibir.com/v1/business-days/add?start=2026-09-14&days=5" \
  --header "authorization: apikey APIBIR-8f2c...9d41"

curl --request GET \
  --url "https://api.apibir.com/v1/business-days/next?date=2026-10-29" \
  --header "authorization: apikey APIBIR-8f2c...9d41"

Node.js

async function isGunuEkle(start, days) {
  const url = new URL("https://api.apibir.com/v1/business-days/add");
  url.searchParams.set("start", start);
  url.searchParams.set("days", String(days));
  const res = await fetch(url, {
    headers: { authorization: `apikey ${process.env.APIBIR_KEY}` }
  });
  if (!res.ok) throw new Error(`apibir ${res.status}`);
  const { data } = await res.json();
  return data; // { start, days, resultDate, timezone, ... }
}

async function sonrakiIsGunu(date) {
  const url = new URL("https://api.apibir.com/v1/business-days/next");
  url.searchParams.set("date", date);
  const res = await fetch(url, {
    headers: { authorization: `apikey ${process.env.APIBIR_KEY}` }
  });
  if (!res.ok) throw new Error(`apibir ${res.status}`);
  const { data } = await res.json();
  return data;
}

// Fatura: 10 takvim günü değil, 10 iş günü vade
const vade = await isGunuEkle("2026-09-14", 10);
console.log("Vade tarihi:", vade.resultDate);

// Son gün tatil/hafta sonuna denk geldiyse kaydır
const kaydirilmis = await sonrakiIsGunu("2026-10-29");
console.log("Sonraki iş günü:", kaydirilmis.resultDate || kaydirilmis.date);

Python

def business_days_add(start, days):
    r = requests.get(
        f"{BASE}/business-days/add",
        params={"start": start, "days": days},
        headers=HEADERS,
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["data"]

def business_days_next(date):
    r = requests.get(
        f"{BASE}/business-days/next",
        params={"date": date},
        headers=HEADERS,
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["data"]

print(business_days_add("2026-09-14", 5))
print(business_days_next("2026-10-29"))

Örnek add yanıtı (illüstratif):

{
  "success": true,
  "creditsUsed": 1,
  "creditsRemaining": 96,
  "data": {
    "start": "2026-09-14",
    "days": 5,
    "resultDate": "2026-09-21",
    "skipped": ["2026-09-19", "2026-09-20"],
    "timezone": "Europe/Istanbul",
    "isBusinessDay": true
  }
}

3. Adım: İki Tarih Arası İş Günü Farkı

SLA ölçümü (“sipariş–teslim kaç iş günü sürdü?”) ve gecikme cezası hesapları için /business-days/diff kullanılır.

curl --request GET \
  --url "https://api.apibir.com/v1/business-days/diff?from=2026-09-01&to=2026-09-14" \
  --header "authorization: apikey APIBIR-8f2c...9d41"

async function isGunuFarki(from, to) {
  const url = new URL("https://api.apibir.com/v1/business-days/diff");
  url.searchParams.set("from", from);
  url.searchParams.set("to", to);
  const res = await fetch(url, {
    headers: { authorization: `apikey ${process.env.APIBIR_KEY}` }
  });
  if (!res.ok) throw new Error(`apibir ${res.status}`);
  const { data } = await res.json();
  return data; // { from, to, businessDays, calendarDays, ... }
}

const sla = await isGunuFarki("2026-09-01", "2026-09-14");
console.log(sla.businessDays, "iş günü /", sla.calendarDays, "takvim günü");

def business_days_diff(from_date, to_date):
    r = requests.get(
        f"{BASE}/business-days/diff",
        params={"from": from_date, "to": to_date},
        headers=HEADERS,
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["data"]

diff = business_days_diff("2026-09-01", "2026-09-14")
print(diff["businessDays"], diff.get("calendarDays"))

Ürün kuralında from / to uçlarının dahil mi hariç mi olduğunu netleştirin (çoğu SLA “gönderim günü hariç, teslim günü dahil” gibi özel sayım ister). API’nin döndürdüğü businessDays değerini kendi sözleşmenize göre +0/+1 ayarlayın; dokümantasyundaki dahil etme kuralına bakın.

4. Adım: Pratik Senaryolar — Fatura Vadesi, Teslimat SLA, Cron

Fatura vadesi (son gün kaydırma)

HMK tarzı düşüncede sürelerin son günü resmi tatil veya hafta sonuna denk gelirse süre, takip eden ilk iş gününe uzar. Pseudokod:

def fatura_vade_tarihi(duzenleme_tarihi, takvim_gunu=30):
    """Önce takvim günü ekle, sonra son günü iş gününe kaydır."""
    from datetime import date, timedelta
    ham = date.fromisoformat(duzenleme_tarihi) + timedelta(days=takvim_gunu)
    # Son gün iş günü değilse /business-days/next
    sonuc = business_days_next(ham.isoformat())
    return sonuc.get("resultDate") or sonuc.get("date")

# Alternatif: doğrudan N iş günü vade
def fatura_vade_is_gunu(duzenleme_tarihi, is_gunu=10):
    return business_days_add(duzenleme_tarihi, is_gunu)["resultDate"]

Muhasebe panosunda hem “ham vade” hem “iş günü kaydırılmış vade”yi gösterin; denetimde hangi kuralın uygulandığı net kalsın.

Kargo / teslimat SLA

async function teslimatSla(siparisTarihi, sozlesmeIsGunu = 2) {
  const hedef = await isGunuEkle(siparisTarihi, sozlesmeIsGunu);
  return {
    siparis: siparisTarihi,
    sozlesmeIsGunu,
    sonTeslim: hedef.resultDate,
    timezone: "Europe/Istanbul",
  };
}

// Gecikme ölçümü
async function geciktiMi(siparis, teslimEdildi) {
  const d = await isGunuFarki(siparis, teslimEdildi);
  return { businessDays: d.businessDays, gecikti: d.businessDays > 2 };
}

Akaryakıt fiyatı veya şehir bazlı lojistik kurallarıyla birleştirirken apibir Akaryakıt API (81 il) maliyet katmanını, iş günü API’si ise süre katmanını sağlar — ikisini aynı sipariş kaydında tutmak panoyu sadeleştirir.

Cron: tatilde atla, faiz/döviz yalnız iş gününde

import datetime as dt

def bugun_is_gunu_mu():
    bugun = dt.datetime.now(dt.timezone(dt.timedelta(hours=3))).date().isoformat()
    # Europe/Istanbul ≈ UTC+3 (yaz/kış için zoneinfo tercih edin)
    return bool(holiday_check(bugun).get("isBusinessDay"))

def sabah_pipeline():
    if not bugun_is_gunu_mu():
        print("Tatil/hafta sonu — poll atlandı")
        return
    # Faiz / döviz / ekonomik takvim poll'ları burada
    # örn. GET /rates/policy, FX, /calendar/events
    print("İş günü — poll çalışıyor")

sabah_pipeline()

Node tarafında aynı mantık:

async function onlyOnBusinessDays(job) {
  const today = new Intl.DateTimeFormat("en-CA", {
    timeZone: "Europe/Istanbul",
    year: "numeric",
    month: "2-digit",
    day: "2-digit",
  }).format(new Date()); // YYYY-MM-DD
  const check = await gunKontrol(today);
  if (!check.isBusinessDay) return { skipped: true, reason: "non_business_day" };
  return job();
}

5. Adım: Ekonomik Takvim, Faiz ve Döviz ile Birlikte Kullanım

İş günü API’si “ne zaman çalış?” sorusunu cevaplar; “o gün makroda ne var?” ve “kur/faiz ne oldu?” soruları ayrı servislerdedir:

Ekonomik Takvim API — TCMB / istatistik açıklama saatlerini iş günü süzgecinden sonra poll edin; tatilde boş beklemeyin.
TCMB Faiz Oranları API — politika faizi güncellemelerini yalnızca iş günü cron’unda çekin.
Döviz Kurları / Geçmiş Kur API — fatura vadesi TRY çevirisinde vade gününün kurunu alın; vade kaymışsa kaydırılmış tarihin kurunu kullanın.
Akaryakıt API — teslimat maliyeti + iş günü SLA aynı sipariş kartında.

def fatura_try_tutar(vade_tarihi, usd_tutar, fx_fn):
    """Vade (iş günü kaydırılmış) tarihinin kuru ile TRY'ye çevir."""
    kur = fx_fn(vade_tarihi)  # örn. geçmiş döviz API
    return usd_tutar * kur["selling"]

Ürün kuralınızı “iş günü + (isteğe bağlı) ekonomik takvim + kur” üçlüsü olarak yazın; tek kaynağa güvenmek yerine çapraz kontrol operasyon ve denetimde işe yarar. İnce kart seviyesindeki “Resmi Tatiller ve İş Günü Aritmetiği API’si Nasıl Çalışır?” özetinin entegrasyon derinliği bu rehberdedir.

Sık Yapılan Entegrasyon Hataları

Hata	Sonucu	Doğrusu
Takvim günü + N ile vade hesaplamak	Bayramda yanlış vade / ceza.	`/business-days/add` veya son günü `/next` ile kaydırın.
Cumartesi’yi iş günü saymak	Banka/mahkeme SLA sapması.	TR kurumsal bağlamda Cmt + Paz + tatil = değil; `isBusinessDay` kullanın.
UTC gece yarısı ile tarih kesmek	İstanbul’da bir gün kayma.	`Europe/Istanbul`; tarih alanlarını `YYYY-MM-DD` tutun.
Her istekte yıllık tatil listesi çekmek	Gereksiz kredi tüketimi.	Yılı (veya ayı) önbelleğe alın; `/check` ve aritmetik uçlarını kullanın.
Yarım günü yok saymak	Arife SLA ihlali.	`type=halfday` için ürün kuralı yazın.
diff uçlarını sözleşmesiz kullanmak	Off-by-one gecikme cezası.	Dahil/hariç kuralını sözleşmeye bağlayın.

Sık Sorulan Sorular

Veriler hangi saat diliminde?

Tarihler Avrupa/İstanbul (Europe/Istanbul) gününe göredir. Sunucunuz UTC’deyse “bugün” hesabını İstanbul’a çevirmeden /holidays/check çağırmayın.

Cumartesi iş günü mü?

apibir’in varsayılan TR iş günü modelinde Cumartesi tipik olarak iş günü değildir (banka/mahkeme/kurumsal SLA bağlamı). Perakende 6 gün çalışan bir operasyonunuz varsa kendi katmanınızda Cumartesi’yi açabilirsiniz; API bayraklarını olduğu gibi saklayıp ürün kuralıyla override edin.

Dini bayramlar otomatik güncellenir mi?

Evet — yıllık /holidays listesi resmi ve dini tatilleri (ve varsa observedDate kaymalarını) kapsar. Sabit kodlanmış bayram tablosu kullanmayın.

Ücretsiz planda yeterli mi?

Ücretsiz plan yaklaşık 100 kredi/ay ile geliştirme, staging ve düşük frekanslı cron’lar için uygundur. Yoğun SLA motorlarında tatil listesini önbelleğe alıp aritmetik uçlarını kullanın.

Kod yazmadan takip edebilir miyim?

Evet. apibir’in WhatsApp veya e-posta günlük raporları tatil / iş günü özetini kodsuz iletebilir. Kapsam için hizmetler sayfasına bakın.

Hata kodları kredi düşürür mü?

4xx istemci hataları tipik olarak kredi düşürmez; başarılı 2xx yanıtlar creditsUsed ile düşer. Anahtarınızı APIBIR-8f2c...9d41 biçiminde maskeleyin; üretimde process.env.APIBIR_KEY / os.environ['APIBIR_KEY'] kullanın.

Başlamak için: Ücretsiz API anahtarı ile /holidays/check ve /business-days/add uçlarını deneyin. Fatura vadesi, teslimat SLA ve cron planlama aynı entegrasyon deseniyle çözülür. Uç noktaların tamamı Resmi Tatiller & İş Günü API kapsamında; kimlik doğrulama ve hata kodları dokümantasyonda yer alır. Ücretsiz plan ~100 kredi/ay ile deneme için yeterlidir — apibir.com üzerinden anahtar alın ve ilk iş günü hesabınızı bugün çalıştırın.

← Tüm Blog Yazılarına Dön Ücretsiz API Anahtarı Al