API за разработчици

Данните за отпуските във всяка система, която има нужда от тях

REST API, което връща JSON. Подавайте отпуските към заплатите, синхронизирайте отсъствията с ERP или ги включете в BI справки, без ръчни експорти.

Поискайте API ключ Изтеглете OpenAPI спецификацията

API е включено в плановете Standard и Enterprise. Цени →

Версия: 2.1.0
Базов адрес: https://timeoff.guru/to/{instance}/xsp/resources/api
Автентикация: TimeOffApiKey: …
Формат: REST · JSON · GET

Какво изграждат екипите с него

Заплати
Вземете одобрените отпуски за месеца преди изчисляването на заплатите, с дни, часове и вид отпуск.
leaveRequestByMonth →
Ежедневна синхронизация
Веднъж на ден вземете заявките, които са одобрени, отменени или променени, и обновете ERP или контрола на достъпа.
leaveRequestsInProgress →
Справки и BI
Комбинирайте видовете отпуск, организациите и заявките с останалите HR данни в Power BI или друг инструмент.
leaveTypes →

Бърз старт

Вземете API ключ
Ключът се издава от администратора на TIMEOFF.GURU. Пазете го на сървъра си и никога не го слагайте в браузър или мобилно приложение.
Изпращайте го в хедър
Всяка заявка носи ключа в хедъра TimeOffApiKey. Всички методи са GET и връщат JSON.
Направете първата заявка
Заменете {instance} с името на вашата инстанция и пробвайте заявките за месец.

bash

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestByMonth?year=2026&month=10" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Справочник

Конфигурация

Организациите и видовете отпуск, настроени във вашата инстанция.

Списък с организации

GET/configuration/organizations

Връща организациите във вашата инстанция: име, пълно наименование, ЕИК/БУЛСТАТ, адрес, град и държава.

Параметри

Няма параметри.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/configuration/organizations" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "organizations": [
    {
      "country": "string",
      "unid": "string",
      "address": "string",
      "deleted": "string",
      "city": "string",
      "name": "string",
      "fullName": "string",
      "bulstat": "string"
    }
  ],
  "success": true
}

Видове отпуск

GET/configuration/leaveTypes

Връща настроените видове отпуск: име на български и английски, кратко име, дали отпускът е платен, дали се приспада от баланса, дали е активен и дали изисква прикачен файл.

Параметри

Име	Тип	Описание
`organizationId`незадължителен	string	ID на организацията. Нужно е само ако инстанцията ви има повече от една конфигурация.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/configuration/leaveTypes" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "leaveTypes": [
    {
      "id": 0,
      "uuid": "string",
      "name": {
        "default": "string",
        "bg": "string",
        "en": "string"
      },
      "shortName": "string",
      "notes": {
        "default": "string",
        "bg": "string",
        "en": "string"
      },
      "paid": true,
      "deduct": true,
      "active": true,
      "attachFile": true,
      "kind": "string"
    }
  ],
  "success": true
}

Справочник

Отпуски

Заявки за отпуск, планирани отпуски и промените в тях.

Заявка за отпуск по UNID

GET/leaves/leaveRequestByUnid

Връща една заявка за отпуск: дати, вид отпуск, дни или часове, статус, одобряващ и пълната история на статусите (кой какво е направил и кога).

Параметри

Име	Тип	Описание
`unid`задължителен	string	Уникален идентификатор (UNID) на заявката.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ
404Не е намерено

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestByUnid?unid=REQUEST_UNID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "requestInfo": {
    "date": "string",
    "periodMode": "string",
    "unid": "string",
    "usedYears": {
      "year": {
        "days": 0,
        "hours": 0
      }
    },
    "endDate": "string",
    "kind": "string",
    "substitutes": {},
    "statusLog": [
      {
        "date": "string",
        "reason": "string",
        "approveComment": "string",
        "effectiveEmployee": {
          "id": null,
          "name": null
        },
        "employee": {
          "id": null,
          "name": null
        },
        "status": "string"
      }
    ],
    "approvedBy": {
      "employee_id": "string"
    },
    "description": "string",
    "dates": [
      "string"
    ],
    "type": "string",
    "hoursRange": "string",
    "requestor": "string",
    "email": "string",
    "employeeNumber": "string",
    "rejectReason": "string",
    "leaveType": "string",
    "days": 0,
    "typeId": 0,
    "startDate": "string",
    "hoursAmount": 0,
    "status": "string"
  },
  "success": true
}

Заявки на служител

GET/leaves/leaveRequestsByEmployee

Връща всички заявки за отпуск, създадени от служителя.

Параметри

Име	Тип	Описание
`employeeId`задължителен	string	ID на служителя.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestsByEmployee?employeeId=EMPLOYEE_ID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "requests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "usedYears": {
        "year": {
          "days": null,
          "hours": null
        }
      },
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "statusLog": [
        {
          "date": null,
          "reason": null,
          "approveComment": null,
          "effectiveEmployee": null,
          "employee": null,
          "status": null
        }
      ],
      "approvedBy": {
        "employee_id": "string"
      },
      "description": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "hoursRange": "string",
      "requestor": "string",
      "email": "string",
      "employeeNumber": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "success": true
}

Заявки за месец

GET/leaves/leaveRequestByMonth

Връща заявките за отпуск в дадения месец. Не включва заявки в статус Rejected, Canceled или Current. Подходящо за месечното изчисляване на заплати.

Параметри

Име	Тип	Описание
`year`задължителен	number	Година на периода на отпуска.
`month`задължителен	number	Месец на периода на отпуска.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestByMonth?year=2026&month=10" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "requests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "usedYears": {
        "year": {
          "days": null,
          "hours": null
        }
      },
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "statusLog": [
        {
          "date": null,
          "reason": null,
          "approveComment": null,
          "effectiveEmployee": null,
          "employee": null,
          "status": null
        }
      ],
      "approvedBy": {
        "employee_id": "string"
      },
      "description": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "hoursRange": "string",
      "requestor": "string",
      "email": "string",
      "employeeNumber": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "success": true
}

Всички заявки за месец

GET/leaves/allLeaveRequestByMonth

Като предишния метод, но връща заявките във всички статуси.

Параметри

Име	Тип	Описание
`year`задължителен	number	Година на периода на отпуска.
`month`задължителен	number	Месец на периода на отпуска.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/allLeaveRequestByMonth?year=2026&month=10" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "requests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "usedYears": {
        "year": {
          "days": null,
          "hours": null
        }
      },
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "statusLog": [
        {
          "date": null,
          "reason": null,
          "approveComment": null,
          "effectiveEmployee": null,
          "employee": null,
          "status": null
        }
      ],
      "approvedBy": {
        "employee_id": "string"
      },
      "description": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "hoursRange": "string",
      "requestor": "string",
      "email": "string",
      "employeeNumber": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "success": true
}

Планирани отпуски на служител

GET/leaves/plannedLeaves

Връща отпуските, които служителят е планирал: начална и крайна дата, брой дни и списък с датите.

Параметри

Име	Тип	Описание
`employeeId`задължителен	string	ID на служителя.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/plannedLeaves?employeeId=EMPLOYEE_ID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "planned": [
    {
      "endDate": "string",
      "days": 0,
      "dates": [
        "string"
      ],
      "startDate": "string"
    }
  ],
  "success": true
}

Промени в заявките

GET/leaves/leaveRequestsInProgress

Връща заявките за отпуск, групирани според случващото се с тях: одобрени, текущи, отменени, променени и архивирани. По подразбиране обхваща текущия ден. Подходящо за ежедневна синхронизация със заплати, ERP или контрол на достъпа.

Параметри

Име	Тип	Описание
`daysBack`незадължителен	number	Колко дни назад да се търси. Важи само за отменени, променени и архивирани заявки.
`exclude`незадължителен	string	Групи, които да се изключат: accepted, current, cancelled, modified, archived. За няколко групи ги долепете една до друга.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestsInProgress" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "acceptedRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "currentRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "cancelledRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "modifiedRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "archivedRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "success": true
}

Справочник

Служители

Данни за служителите и компенсации.

Данни за служител

GET/employees/employeeById

Връща името, организацията, отдела и работните часове на служителя.

Параметри

Име	Тип	Описание
`employeeId`задължителен	string	ID на служителя.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ
403API за служители не е включено във вашата инстанция
404Не е намерено

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/employees/employeeById?employeeId=EMPLOYEE_ID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "employee": {
    "organization": "string",
    "name": "string",
    "id": "string",
    "department": "string",
    "workingHours": 0
  },
  "success": true
}

Компенсации на служител

GET/employees/compensationsByEmployee

Връща компенсациите, записани за служителя: дата, описание, дни и статус.

Параметри

Име	Тип	Описание
`employeeId`задължителен	string	ID на служителя.

Отговори

200Успешна заявка
401Липсващ или невалиден API ключ
403API за служители не е включено във вашата инстанция

Примерна заявка

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/employees/compensationsByEmployee?employeeId=EMPLOYEE_ID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Структура на отговораСтойностите показват типа на данните.

{
  "compensations": [
    {
      "date": "string",
      "unid": "string",
      "description": "string",
      "days": 0,
      "status": "string"
    }
  ],
  "success": true
}

Кодове на отговор

Всеки отговор съдържа поле success. Първо проверявайте HTTP статуса:

200Успешна заявка
401Липсващ или невалиден API ключ
403API за служители не е включено във вашата инстанция
404Не е намерено

Нужна ви е помощ с интеграция?

Пишете ни коя система искате да свържете и ще ви помогнем да изберете правилните методи и данни.

Пишете на поддръжката

TIMEOFF.GURU API 2.1.0 · Лиценз: Apache 2.0

Данните за отпуските във всяка система, която има нужда от тях

Какво изграждат екипите с него

Заплати

Ежедневна синхронизация

Справки и BI

Бърз старт

Вземете API ключ

Изпращайте го в хедър

Направете първата заявка

Конфигурация

Параметри

Отговори

Параметри

Отговори

Отпуски

Параметри

Отговори

Параметри

Отговори

Параметри

Отговори

Параметри

Отговори

Параметри

Отговори

Параметри

Отговори

Служители

Параметри

Отговори

Параметри

Отговори

Кодове на отговор

Нужна ви е помощ с интеграция?