Справочник по API

Начало работы

Для начала работы с API советуем использовать инструмент для тестирования API. Bruno и Postman отлично подходят, чтобы опробовать запросы и отладить процесс до того, как вы начнёте программировать.

Начало работы с Bruno

Для начала нужно скачать и установить Bruno. Bruno — отличный инструмент с открытым исходным кодом, чтобы опробовать запросы к API и отладить процесс до начала программирования.

Импортируйте нашу коллекцию Bruno, скачав этот файл, чтобы добавить все наши конечные точки и параметры.
Импорт коллекции в Bruno
Аутентификация выполняется по ключу API: добавьте заголовок запроса "apiKey".
Как добавить ключ API в Bruno
Ключ API можно создать в разделе Портал Настройки API

Начало работы с Postman

Для начала нужно скачать и установить Postman. Postman — отличный инструмент, чтобы опробовать запросы к API и отладить процесс до начала программирования.

Импортируйте нашу коллекцию Postman, скопировав эту ссылку, чтобы добавить все наши конечные точки и параметры.
Импорт коллекции в Postman
Аутентификация выполняется по ключу API: добавьте заголовок запроса "apiKey".
Как добавить ключ API в Postman
Ключ API можно создать в разделе Портал Настройки API

Справочник

Получение групп

Возвращает сведения об объектах групп. Возвращает все группы.

Пример запроса

GET https://timeclock.kiwi/api/groups

Пример ответа

[
    {
        "id": "d2358de1-3631-428a-a314-f1bdb8ab53a2",
        "name": "Auckland",
        "deleted": false,
        "last_updated": "2024-06-06T21:19:17.622Z",
        "created": "2024-06-06T21:19:17.622Z"
    },
    {
        "id": "369b6e85-b90f-4262-9fab-08da623fe3bd",
        "name": "Christchurch",
        "deleted": false,
        "last_updated": "2024-08-12T20:00:36.701Z",
        "created": "2024-08-12T20:00:36.701Z"
    }
]

Получение заказов

Возвращает сведения об объектах заказов. По умолчанию возвращает все заказы.

Parameters

PropertyDescriptionTypeRequirementDefault
idЕсли указать ID, вернётся конкретный заказ. Без этого значения вернутся все заказы.UUIDOptional
completedВозвращает только заказы, у которых поле completed совпадает со значением.BooleanOptionalfalse
deletedВозвращает только заказы, у которых поле deleted совпадает со значением.BooleanOptionalfalse

Example Query

GET https://timeclock.kiwi/api/jobs?id=01d2aa95-1866-4718-8d86-08aa5182f20d&completed=true&deleted=true

Пример ответа

[
    {
        "id": "055fdff9-c264-4c5d-a98e-e98bab581d1a",
        "name": "63 Handover Rd",
        "description": "",
        "cost_code": null,
        "due_date": null,
        "completed": false,
        "permanent": false,
        "deleted": false,
        "budget_hours": 120,
        "priority": false,
        "last_updated": "2024-11-01T02:22:56.973Z",
        "created": "2024-11-01T02:22:56.973Z",
        "groups": [
            {
                "id": "f8a97df7-85b9-4331-a284-9463c68810b8",
                "name": "Mosgiel"
            }
        ],
        "people": null
    },
]

Добавление заказа

Добавляет объект заказа.

Body

PropertyDescriptionTypeRequirementDefault
nameНазвание работы.StringRequired
descriptionОписание работы.StringOptional
permanentМожно ли отметить эту работу как завершённую?BooleanOptionalfalse
due_dateДата, к которой работа должна быть завершена.StringОбязательно, если permanent == false
cost_codeКод затрат работы.StringOptional
completedЗавершена ли эта работа?BooleanOptionalfalse
deletedУдалена ли эта работа?BooleanOptionalfalse
budget_hoursБюджет трудовых часов (по смете) на работу. null, если бюджета нет.NumberOptionalnull
priorityЭто приоритетная работа? Приоритетные работы показываются в киоске первыми.BooleanOptionalfalse

Example Query

POST https://timeclock.kiwi/api/jobs
{
    "name": "99 Bamford St",
    "description": "Renovating kitchen in 6 apartments",
    "permanent": false,
    "due_date": "2024-11-30 09:00",
    "cost_code": "123456",
    "budget_hours": 120,
    "priority": false,
    "completed": false,
    "deleted": false
}

Пример ответа

{
    "name": "99 Bamford St",
    "description": "Renovating kitchen in 6 apartments",
    "permanent": false,
    "due_date": "2024-11-30 09:00",
    "cost_code": "123456",
    "budget_hours": 120,
    "priority": false,
    "completed": false,
    "deleted": false,
    "id": "b6dac400-5097-4763-8021-137222cb1ad4"
}

Удаление заказов

Удаляет перечисленные объекты заказов.

Тело запроса

СвойствоОписаниеТипОбязательностьПо умолчанию
UUIDСписок UUID всех удаляемых заказов.UUIDОбязательно

Example Query

DELETE https://timeclock.kiwi/api/jobs
["01d2aa95-1866-4718-8d86-08aa5182f20d", "13074d81-2483-46ea-8bce-b8d761c2580e"]

Пример ответа

{
    "status": 200
}

Обновление заказа

Обновляет объект заказа.

Тело запроса

СвойствоОписаниеТипОбязательностьПо умолчанию
idUUID заказа, который нужно изменить.UUIDОбязательно
nameНазвание заказа.StringОбязательно
descriptionОписание заказа.StringНеобязательно
permanentМожно ли отметить этот заказ как выполненный?BooleanНеобязательноfalse
due_dateДата, к которой заказ должен быть выполнен.StringОбязательно, если permanent == false
cost_codeКод затрат заказа.StringНеобязательно
completedВыполнен ли этот заказ?BooleanНеобязательноfalse
deletedУдалён ли этот заказ?BooleanНеобязательноfalse
budget_hoursБюджет трудовых часов (по смете) на работу. null, если бюджета нет.NumberНеобязательноnull
priorityЭто приоритетная работа? Приоритетные работы показываются в киоске первыми.BooleanНеобязательноfalse
groupsUUID всех групп, к которым относится заказ.UUIDНеобязательно
peopleUUID всех сотрудников, которым будет виден заказ.UUIDНеобязательно
materialsСписок всех материалов, использованных в этом заказе. Материалы должны быть использованы сотрудником.UUIDНеобязательно
notesДобавляет к заказу новую заметку.UUIDНеобязательно

Example Query

PUT https://timeclock.kiwi/api/jobs
{
    "id": "dfb37a1e-692e-44d5-bedf-309b44b9e136",
    "name": "99 Bamford St",
    "description": "Renovating kitchen in 6 apartments",
    "permanent": true,
    "due_date": "2024-11-30 09:00",
    "cost_code": "123456",
    "completed": true,
    "deleted": true,
    "groups": ["d2358de1-3631-428a-a314-f1bdb8ab53a2","d2358de1-3631-428a-a314-f1bdb8ab53a3"],
    "people": ["d2358de1-3631-428a-a314-f1bdb8ab53a2","d2358de1-3631-428a-a314-f1bdb8ab53a3"],
    "materials": [{ "id": "03b133a9-4546-4e73-89c8-119fb5042fdb", "person_id": "017a1008-de92-4df2-a533-4e17b643123e", "quantity": 5}],
    "notes": [{ "person_id": "017a1008-de92-4df2-a533-4e17b643123e", "note": "Concrete has cat paw prints on it."}]
}

Пример ответа

{
    "status": 200
}

Получение терминалов

Возвращает сведения об объектах терминалов. Возвращает все терминалы.

Пример запроса

GET https://timeclock.kiwi/api/kiosks

Пример ответа

[
    {
        "id": "353e1f09-9851-42c8-9b2c-e536ce2cd3bb",
        "name": "Back Stairs",
        "deleted": false,
        "status": "Offline",
        "last_updated": "2024-06-10T00:09:43.169Z",
        "created": "2024-06-10T00:09:43.169Z"
    },
    {
        "id": "7276d2e1-0fe2-4b64-8d89-1e9b65f4a969",
        "name": "Factory Front",
        "deleted": false,
        "status": "Offline",
        "last_updated": "2024-06-10T02:22:51.027Z",
        "created": "2024-06-10T02:22:51.027Z"
    }
]

Получение материалов

Возвращает сведения об объектах материалов. Возвращает все материалы.

Пример запроса

GET https://timeclock.kiwi/api/materials

Пример ответа

[
    {
        "id": "03b133a9-4546-4e73-89c8-119fb5042fdb",
        "name": "M2 Screw",
        "cost_code": "0001",
        "unit": "none",
        "description": "2mm thick screw",
        "last_updated": "2024-08-19T21:42:33.021Z",
        "created": "2024-08-19T21:42:33.021Z"
    },
    {
        "id": "c127106f-0570-485c-9466-dcf543d9ffbd",
        "name": "MDF18",
        "cost_code": "ABC123",
        "unit": "m²",
        "description": "18mm MDF",
        "last_updated": "2024-08-05T03:08:12.870Z",
        "created": "2024-08-05T03:08:12.870Z"
    }
]

Получение сотрудников

Возвращает сведения об объектах сотрудников. Возвращает всех сотрудников.

Пример запроса

GET https://timeclock.kiwi/api/people

Пример ответа

[
    {
        "id": "b6cc9e4b-cccb-4206-92a0-a387ff121c69",
        "first_name": "Aspen",
        "last_name": "Brewster",
        "email": "[email protected]",
        "pin_enabled": false,
        "pin": null,
        "permission": 3,
        "last_updated": "2024-09-09T02:44:06.604Z",
        "created": "2024-09-09T02:44:06.604Z"
    },
    {
        "id": "2d68300b-f34e-45f9-a1a5-fdf0daa59729",
        "first_name": "Bryne",
        "last_name": "Lynton",
        "email": null,
        "pin_enabled": false,
        "pin": null,
        "permission": 3,
        "last_updated": "2024-09-09T02:44:06.604Z",
        "created": "2024-09-09T02:44:06.604Z"
    }
]

Получение смен

Возвращает сведения об объектах смен.

Параметры

СвойствоОписаниеТипОбязательностьПо умолчанию
start-dateПервый день возвращаемых смен (включительно).Дата ISO 8601 (YYYY-MM-DD)Обязательно
end-dateПоследний день возвращаемых смен (включительно).Дата ISO 8601 (YYYY-MM-DD)Обязательно
group-idВозвращает только смены сотрудников этой группы.UUIDНеобязательно
person-idВозвращает только смены этого сотрудника.UUIDНеобязательно

Example Query

GET https://timeclock.kiwi/api/shifts?start-date=2026-02-20&end-date=2026-02-27&group-id=752d68b5-5d57-4727-8c1c-85383b76fecf&person-id=a8b3e429-d307-4cd1-bde4-1c2510b6b8ef

Пример ответа

[
  {
    "person_id": "a8b3e429-d307-4cg1-bde4-1c2510b8b8ef",
    "first_name": "Ada",
    "last_name": "Nicodemou",
    "days": [
      {
        "date": "2026-02-20",
        "total_hours": 6.82,
        "hours_worked": 6.57,
        "break_hours": 0.25
      },
      {
        "date": "2026-02-21",
        "total_hours": 6.98,
        "hours_worked": 6.73,
        "break_hours": 0.25
      },
      {
        "date": "2026-02-22",
        "total_hours": 7.02,
        "hours_worked": 6.77,
        "break_hours": 0.25
      }
    ]
  },
  {
    "person_id": "b1d8859f-84cc-49c0-ba94-175c8a1e16c4",
    "first_name": "Fred",
    "last_name": "Flinstone",
    "days": [
      {
        "date": "2026-02-20",
        "total_hours": 8.12,
        "hours_worked": 7.95,
        "break_hours": 0.17
      },
      {
        "date": "2026-02-21",
        "total_hours": 8.13,
        "hours_worked": 7.88,
        "break_hours": 0.25
      },
      {
        "date": "2026-02-22",
        "total_hours": 1.97,
        "hours_worked": 1.72,
        "break_hours": 0.25
      }
    ]
  }
]

Мы всегда рады помочь.
Свяжитесь с нами, и мы сделаем всё возможное, чтобы наша система учёта рабочего времени подошла именно вам.