Огляд

Документація API

Публічний REST-API Calendar Creator: один POST-запит — і у відповідь самостійний HTML календаря. Растеризацію у PDF/PNG/JPG виконує клієнт (та сама бібліотека, що й на сайті).

Базовий URL https://calendar-creator.online/api/v1

Як працює API

Сервер ніколи не віддає готовий файл — лише самодостатню HTML-сторінку зі стилями, шрифтами та зображеннями всередині. Це гарантує однаковий результат і у браузері, і в Android-застосунку, і у вашому коді.

Один контракт — HTML-у-відповідь. Жодних розбіжностей між сайтом та апкою.
Растеризація HTML → PDF/PNG/JPG — на вашому боці (html-to-image + jsPDF або власне рішення).
Rate limit: 10 запитів за хвилину з одного IP та 500 запитів на день усього.
CORS відкритий — можна викликати з браузера, серверного коду чи мобільного клієнта.

Авторизація

Без ключів

API публічний — ключі не потрібні. Захист працює через rate-limit на рівні IP та глобальний денний ліміт.

Ендпойнти

Доступні запити

GET /api/v1/health

Перевірка стану. Повертає {"ok": true, "time": "…"}.

GET /api/v1/presets

Список доступних пресетів і опис їхніх кастомних полів.

POST /api/v1/generate

Генерує самодостатній HTML календаря за переданими параметрами.

Спільні параметри

Що приймають усі пресети

Поле	Тип	Обовʼязковість	Опис
`preset`	string	обовʼязкове	minimal \| planner \| visual
`year`	integer	обовʼязкове	1900..2100
`month`	integer	обовʼязкове	1..12
`weekStart`	enum	обовʼязкове	mon (Понеділок) або sun (Неділя)
`locale`	enum	обовʼязкове	uk або en — мова назв днів та місяця
`bgColor`	string	опційне	HEX-колір фону календаря, напр. #ffffff (дефолт)
`custom`	object	опційне	Пресет-специфічні поля (див. нижче)

Кастомні поля по пресетам

custom-поля для кожного пресета

Усі custom-поля опційні — без них пресет використає свої дефолти.

Minimal minimal

Без декору, оптимально для друку.

Поле	Тип	Обовʼязковість	Опис
`titleLeft`	string	опційне	Головний заголовок
`titleRight`	string	опційне	Альтернативний заголовок
`accentColor`	color	опційне	Акцентний колір
`altOpacity`	number	опційне	Додаткова прозорість (0–1)

Planner planner

Місяць поряд із полем для записів і ghost-роком позаду.

Поле	Тип	Обовʼязковість	Опис
`monthTitle`	string	опційне	Головний заголовок
`yearGhost`	string	опційне	Альтернативний заголовок
`notesTitle`	string	опційне	Заголовок нотаток
`notesContent`	text	опційне	Текст нотаток
`notesColor`	color	опційне	Колір нотаток
`accentColor`	color	опційне	Акцентний колір
`altOpacity`	number	опційне	Додаткова прозорість (0–1)

Visual visual

Календар-постер: фото поряд із календарем, акцентний колір під фото.

Поле	Тип	Обовʼязковість	Опис
`monthTitle`	string	опційне	Головний заголовок
`imageUrl`	url	опційне	URL зображення
`accentColor`	color	опційне	Акцентний колір

POST /api/v1/generate

Згенерувати календар

Приймає JSON із параметрами, повертає Content-Type: text/html; charset=UTF-8 із готовою сторінкою всередині. На статус 200 — HTML, на 422 — JSON із описом помилок валідації.

Тіло запиту

{
    "preset": "planner",
    "year": 2026,
    "month": 6,
    "weekStart": "mon",
    "locale": "uk",
    "bgColor": "#ffffff",
    "custom": {
        "monthTitle": "Червень",
        "notesTitle": "Нотатки:",
        "notesContent": "Список покупок:",
        "notesColor": "#1e293b",
        "accentColor": "#0c7e71",
        "altOpacity": 0.12
    }
}

Приклад на curl

curl -X POST https://calendar-creator.online/api/v1/generate \
  -H "Content-Type: application/json" \
  -H "Accept: text/html" \
  -d '{
    "preset": "planner",
    "year": 2026,
    "month": 6,
    "weekStart": "mon",
    "locale": "uk",
    "bgColor": "#ffffff",
    "custom": {
        "monthTitle": "Червень",
        "notesTitle": "Нотатки:",
        "notesContent": "Список покупок:",
        "notesColor": "#1e293b",
        "accentColor": "#0c7e71",
        "altOpacity": 0.12
    }
}' \
  -o calendar.html

Відповідь

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

<!DOCTYPE html>
<html lang="uk">
  <head>…inlined CSS, fonts (base64), title…</head>
  <body><div class="calendar calendar--planner">…</div></body>
</html>

Ліміти

Скільки можна запитів

10 запитів за хвилину з одного IP та 500 запитів на день у сумі. Перевищення повертає HTTP 429 із заголовком Retry-After.

Помилки

Коди відповідей

`200 OK`	HTML календаря у тілі відповіді.
`400 Bad Request`	Некоректне тіло запиту (не JSON або не той Content-Type).
`422 Unprocessable Entity`	Не пройшла валідація — у JSON-відповіді є поле errors з деталями.
`429 Too Many Requests`	Перевищено ліміт. Дочекайся вікна, що вказане у Retry-After.