Skip to Content
TillorManual
Exemple

API Program de funcționare

Preluați programul de funcționare rezolvat și sărbătorile legale următoare pentru un site web

Ultima actualizare la

Folosiți API-ul de program de funcționare rezolvat dacă afișați pe un site public programul sezonier (de exemplu Vară / Iarnă) sau sărbătorile legale următoare. Tillor aplică deja excepțiile, perioadele sezoniere și programul săptămânal obișnuit și adaugă sărbătorile legale din intervalul cerut. Nu trebuie să implementați din nou acest lucru.

Permisiune: organization:settings:read sau organization:settings:write

Cheia API rămâne pe server

Apelați Tillor doar de pe un server (Next.js Route Handler, Server Component sau backend). Puneți cheia în variabile de mediu. Nu o trimiteți niciodată către browser.

Autentificare: consultați API-ul HTTP. Încercați endpointul în Referința API sau prin OpenAPI (tag organization-settings).

Endpoint

GET https://tillor.eu/api/orgs/org_abc123/organization-settings/opening-hours

Antete:

x-api-key: tkn_xxx

Înlocuiți org_abc123 cu ID-ul organizației dumneavoastră.

Parametri de interogare

Folosiți fie date, fie from/to. Nu le combinați.

ParametruSemnificație
(niciunul)Astăzi, în fusul orar al organizației
dateO singură zi calendaristică (YYYY-MM-DD)
fromZiua de început (inclusiv). Fără to: doar acea zi
toZiua de sfârșit (inclusiv). Necesită from. Maximum 366 de zile
languageIsoCodeLimba pentru numele sărbătorilor (NL, FR, …). Implicit: limba organizației

Răspuns

Fiecare element este o zi calendaristică, deja rezolvată:

CâmpSemnificație
timeZoneFusul orar IANA al organizației
from / toIntervalul cerut
holidaysSărbători legale care se suprapun cu from–to
items[].dateZiua calendaristică YYYY-MM-DD
items[].weekdaymonday … sunday
items[].sourceexception, period sau regular
items[].periodLabelDoar la source: "period": eticheta din Tillor, de exemplu "Zomer" sau "Winter"
items[].holidayDoar dacă acea zi este sărbătoare legală: { id, name, startDate, endDate }
items[].blocksIntervale orare în minute de la miezul nopții
items[].closedtrue dacă blocks este gol

Prioritate: excepție (sărbătoare sau interval personalizat) → ultima perioadă sezonieră potrivită → programul săptămânal obișnuit.

Etichetele sezoniere provin din Setări > Program de funcționare. Perioadele pot trece peste schimbarea anului (de exemplu de la 1 noiembrie până la 31 martie). Zilele din afara oricărei perioade revin la programul săptămânal obișnuit (source: "regular", fără periodLabel).

Din minute în oră de ceas

startMinutes / endMinutes sunt minute de la 00:00.

MinuteOra
54009:00
60010:00
72012:00
78013:00
102017:00
114019:00
function formatMinutes(minutes: number): string {
  const hour = Math.floor(minutes / 60);
  const minute = minutes % 60;
  return `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
}

Exemple

Zi dintr-o perioadă sezonieră

curl -X GET "https://tillor.eu/api/orgs/org_abc123/organization-settings/opening-hours?date=2026-07-15" \
  -H "x-api-key: tkn_xxx"
{
  "timeZone": "Europe/Brussels",
  "from": "2026-07-15",
  "to": "2026-07-15",
  "holidays": [],
  "items": [
    {
      "date": "2026-07-15",
      "weekday": "wednesday",
      "source": "period",
      "periodLabel": "Zomer",
      "blocks": [{ "startMinutes": 540, "endMinutes": 720 }],
      "closed": false
    }
  ]
}

09:00–12:00, program de vară.

Zi în afara perioadelor sezoniere

curl -X GET "https://tillor.eu/api/orgs/org_abc123/organization-settings/opening-hours?date=2026-01-15" \
  -H "x-api-key: tkn_xxx"
{
  "timeZone": "Europe/Brussels",
  "from": "2026-01-15",
  "to": "2026-01-15",
  "holidays": [],
  "items": [
    {
      "date": "2026-01-15",
      "weekday": "thursday",
      "source": "regular",
      "blocks": [
        { "startMinutes": 540, "endMinutes": 720 },
        { "startMinutes": 780, "endMinutes": 1020 }
      ],
      "closed": false
    }
  ]
}

09:00–12:00 și 13:00–17:00.

Interval peste limita unei perioade

curl -X GET "https://tillor.eu/api/orgs/org_abc123/organization-settings/opening-hours?from=2026-03-30&to=2026-04-02" \
  -H "x-api-key: tkn_xxx"
DatasourceperiodLabel
2026-03-30regular-
2026-03-31regular-
2026-04-01periodZomer
2026-04-02periodZomer

Sărbători legale următoare

Sărbătorile legale se află în același răspuns: holidays pentru o listă (nume + date), items[].holiday dacă acea zi calendaristică este o sărbătoare. Orele rămân programul rezolvat; o sărbătoare fără excepție completată în Tillor urmează programul sezonier sau săptămânal (source nu este atunci "exception").

curl -X GET "https://tillor.eu/api/orgs/org_abc123/organization-settings/opening-hours?from=2026-08-27&to=2026-12-31&languageIsoCode=NL" \
  -H "x-api-key: tkn_xxx"
{
  "timeZone": "Europe/Brussels",
  "from": "2026-08-27",
  "to": "2026-12-31",
  "holidays": [
    {
      "id": "0fad0035-6b77-404a-953d-c66dac014483",
      "name": "Allerheiligen",
      "startDate": "2026-11-01",
      "endDate": "2026-11-01"
    },
    {
      "id": "d90e5f53-bc92-4860-bdae-f7e75935848d",
      "name": "Kerstmis",
      "startDate": "2026-12-25",
      "endDate": "2026-12-25"
    }
  ],
  "items": [
    {
      "date": "2026-11-01",
      "weekday": "sunday",
      "source": "regular",
      "holiday": {
        "id": "0fad0035-6b77-404a-953d-c66dac014483",
        "name": "Allerheiligen",
        "startDate": "2026-11-01",
        "endDate": "2026-11-01"
      },
      "blocks": [],
      "closed": true
    }
  ]
}

Exemplul items de mai sus este prescurtat; răspunsul real conține fiecare zi din interval. Vacanțele școlare nu sunt incluse în acest endpoint; ele rămân la GET /holidays?kind=school.

Next.js (server)

Pentru un widget săptămânal sau „deschis acum” pe un site public:

const TILLOR_API_URL = "https://tillor.eu";
const ORGANIZATION_ID = process.env.TILLOR_ORG_ID ?? "";

type OpeningHoursBlock = {
  startMinutes: number;
  endMinutes: number;
};

type OpeningHoursHoliday = {
  id: string;
  name: string;
  startDate: string;
  endDate: string;
};

type OpeningHoursItem = {
  date: string;
  weekday: string;
  source: "exception" | "period" | "regular";
  periodLabel?: string;
  holiday?: OpeningHoursHoliday;
  blocks: OpeningHoursBlock[];
  closed: boolean;
};

type OpeningHoursResponse = {
  timeZone: string;
  from: string;
  to: string;
  holidays: OpeningHoursHoliday[];
  items: OpeningHoursItem[];
};

export async function getOpeningHours(
  from: string,
  to: string,
): Promise<OpeningHoursResponse> {
  const url = new URL(
    `${TILLOR_API_URL}/api/orgs/${ORGANIZATION_ID}/organization-settings/opening-hours`,
  );
  url.searchParams.set("from", from);
  url.searchParams.set("to", to);
  url.searchParams.set("languageIsoCode", "NL");

  const response = await fetch(url, {
    headers: {
      "x-api-key": process.env.TILLOR_API_KEY ?? "",
    },
    next: { tags: ["opening-hours"], revalidate: 3600 },
  });

  if (!response.ok) {
    throw new Error(`Tillor opening hours ${response.status}`);
  }

  return response.json() as Promise<OpeningHoursResponse>;
}

holidays este lista pentru un bloc „sărbători următoare”. items[].holiday este util într-un calendar săptămânal. items[].periodLabel este textul sezonier (de exemplu "Zomer" sau "Winter"). Un cache de 1 oră este de obicei suficient.

Invalidarea cache-ului (webhook)

La fiecare modificare a setărilor organizației, Tillor trimite organizationSettings:updated (webhook și SSE). Abonați-vă la el și preluați din nou programul de funcționare. Payloadul este intenționat mic (fără IP-uri de imprimantă sau programul complet):

{
  "event": "organizationSettings:updated",
  "data": {
    "openingHoursChanged": true
  },
  "timestamp": 1787829600000
}

openingHoursChanged este true dacă se schimbă programul de funcționare, fusul orar sau țara implicită - adică ceea ce influențează GET .../opening-hours. La false puteți păstra cache-ul programului de funcționare.

Exemplu de Route Handler Next.js:

import { revalidateTag } from "next/cache";

export async function POST(request: Request) {
  const body = (await request.json()) as {
    event?: string;
    data?: { openingHoursChanged?: boolean };
  };
  if (body.event === "organizationSettings:updated" && body.data?.openingHoursChanged) {
    await revalidateTag("opening-hours");
  }
  return new Response(null, { status: 204 });
}

Crearea unui webhook: consultați Webhookuri. Cheia evenimentului: organizationSettings:updated (permisiune organization:settings:read sau organization:settings:write).

Programul complet (opțional)

Necesar doar dacă doriți să afișați singur calendarul sezonier (etichete + fromMonth/untilDay), fără rezolvare pe zile:

GET https://tillor.eu/api/orgs/org_abc123/organization-settings

Citiți openingHoursSchedule.periods (etichete precum "Zomer") și openingHoursSchedule.weekdays (program obișnuit). Pentru site-ul propriu-zis, GET .../opening-hours rămâne sursa cea mai simplă.

MCP

În Cursor sau Claude: endpointul organizationSettings_listOpeningHours (categoria organizationSettings), argumente organizationId, opțional date sau from/to, opțional languageIsoCode.

Legate de acest subiect

A fost utilă această pagină?

Exemple HTTP

Exemple cURL și de cereri pentru API-ul Tillor

Exemple webhook

Payloaduri de evenimente și exemple de POST webhook

Pe această pagină

EndpointParametri de interogareRăspunsDin minute în oră de ceasExempleZi dintr-o perioadă sezonierăZi în afara perioadelor sezoniereInterval peste limita unei perioadeSărbători legale următoareNext.js (server)Invalidarea cache-ului (webhook)Programul complet (opțional)MCPLegate de acest subiect