Guia de referência da API

Primeiros passos

Para começar com a API, sugerimos usar uma ferramenta de teste de APIs. Bruno e Postman são ótimos para testar requisições e ajustar seu fluxo de trabalho antes de começar a programar.

Primeiros passos com o Bruno

Para começar, você precisa baixar e instalar o Bruno. O Bruno é uma ótima ferramenta de código aberto para testar requisições de API e ajustar seu fluxo de trabalho antes de começar a programar.

Importar a coleção no Bruno — Importe nossa coleção do Bruno baixando este arquivo para adicionar todos os nossos endpoints e parâmetros.

Como adicionar a chave de API no Bruno — A autenticação é feita por chave de API, adicionando o cabeçalho de requisição "apiKey".

Primeiros passos com o Postman

Para começar, você precisa baixar e instalar o Postman. O Postman é uma ótima ferramenta para testar requisições de API e ajustar seu fluxo de trabalho antes de começar a programar.

Importar a coleção no Postman — Importe nossa coleção do Postman copiando este link para adicionar todos os nossos endpoints e parâmetros.

Como adicionar a chave de API no Postman — A autenticação é feita por chave de API, adicionando o cabeçalho de requisição "apiKey".

Referência

Obter grupos

Retorna informações sobre os objetos de grupo. Retorna todos os grupos.

Consulta de exemplo

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

Exemplo de resposta

`1`	`[`
`2`	`{`
`3`	`"id": "d2358de1-3631-428a-a314-f1bdb8ab53a2",`
`4`	`"name": "Auckland",`
`5`	`"deleted": false,`
`6`	`"last_updated": "2024-06-06T21:19:17.622Z",`
`7`	`"created": "2024-06-06T21:19:17.622Z"`
`8`	`},`
`9`	`{`
`10`	`"id": "369b6e85-b90f-4262-9fab-08da623fe3bd",`
`11`	`"name": "Christchurch",`
`12`	`"deleted": false,`
`13`	`"last_updated": "2024-08-12T20:00:36.701Z",`
`14`	`"created": "2024-08-12T20:00:36.701Z"`
`15`	`}`
`16`	`]`

Obter serviços

Retorna informações sobre os objetos de serviço. Por padrão, retorna todos os serviços.

Parameters

Property	Description	Type	Requirement	Default
id	Informar um ID retorna o serviço específico. Sem esse valor, todos os serviços são retornados.	UUID	Optional
completed	Retorna somente os serviços cujo campo completed corresponde ao valor.	Boolean	Optional	false
deleted	Retorna somente os serviços cujo campo deleted corresponde ao valor.	Boolean	Optional	false

Example Query

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

Exemplo de resposta

[
    {
        "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
    },
]

Adicionar serviço

Adiciona um objeto de serviço.

Body

Property	Description	Type	Requirement	Default
name	O nome do serviço.	String	Required
description	A descrição do serviço.	String	Optional
permanent	Este serviço pode ser marcado como concluído?	Boolean	Optional	false
due_date	A data em que o serviço deve ser concluído.	String	Obrigatório se permanent == false
cost_code	O código de custo do serviço.	String	Optional
completed	Este serviço foi concluído?	Boolean	Optional	false
deleted	Este serviço foi excluído?	Boolean	Optional	false
budget_hours	As horas de trabalho orçadas para o serviço. null se não houver orçamento.	Number	Optional	null
priority	Este é um serviço prioritário? Serviços prioritários aparecem primeiro no quiosque.	Boolean	Optional	false

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
}

Exemplo de resposta

{
    "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"
}

Excluir serviços

Exclui os objetos de serviço listados.

Corpo

Propriedade	Descrição	Tipo	Obrigatoriedade	Padrão
UUID	Uma lista com os UUIDs de todos os serviços a excluir.	UUID	Obrigatório

Example Query

DELETE https://timeclock.kiwi/api/jobs

`1`	`["01d2aa95-1866-4718-8d86-08aa5182f20d", "13074d81-2483-46ea-8bce-b8d761c2580e"]`

Exemplo de resposta

`1`	`{`
`2`	`"status": 200`
`3`	`}`

Atualizar serviço

Atualiza um objeto de serviço.

Corpo

Propriedade	Descrição	Tipo	Obrigatoriedade	Padrão
id	O UUID do serviço que você quer modificar.	UUID	Obrigatório
name	O nome do serviço.	String	Obrigatório
description	A descrição do serviço.	String	Opcional
permanent	É um serviço que pode ser marcado como concluído?	Boolean	Opcional	false
due_date	A data em que o serviço deve ser concluído.	String	Obrigatório se permanent == false
cost_code	O código de custo do serviço.	String	Opcional
completed	Este serviço foi concluído?	Boolean	Opcional	false
deleted	Este serviço foi excluído?	Boolean	Opcional	false
budget_hours	As horas de trabalho orçadas para o serviço. null se não houver orçamento.	Number	Opcional	null
priority	Este é um serviço prioritário? Serviços prioritários aparecem primeiro no quiosque.	Boolean	Opcional	false
groups	Os UUIDs de todos os grupos dos quais este serviço faz parte.	UUID	Opcional
people	Os UUIDs de todas as pessoas que poderão ver este serviço.	UUID	Opcional
materials	Uma lista de todos os materiais usados neste serviço. Os materiais precisam ter sido usados por uma pessoa.	UUID	Opcional
notes	Adiciona uma nova nota ao serviço.	UUID	Opcional

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."}]
}

Exemplo de resposta

`1`	`{`
`2`	`"status": 200`
`3`	`}`

Obter quiosques

Retorna informações sobre os objetos de quiosque. Retorna todos os quiosques.

Consulta de exemplo

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

Exemplo de resposta

`1`	`[`
`2`	`{`
`3`	`"id": "353e1f09-9851-42c8-9b2c-e536ce2cd3bb",`
`4`	`"name": "Back Stairs",`
`5`	`"deleted": false,`
`6`	`"status": "Offline",`
`7`	`"last_updated": "2024-06-10T00:09:43.169Z",`
`8`	`"created": "2024-06-10T00:09:43.169Z"`
`9`	`},`
`10`	`{`
`11`	`"id": "7276d2e1-0fe2-4b64-8d89-1e9b65f4a969",`
`12`	`"name": "Factory Front",`
`13`	`"deleted": false,`
`14`	`"status": "Offline",`
`15`	`"last_updated": "2024-06-10T02:22:51.027Z",`
`16`	`"created": "2024-06-10T02:22:51.027Z"`
`17`	`}`
`18`	`]`

Obter materiais

Retorna informações sobre os objetos de material. Retorna todos os materiais.

Consulta de exemplo

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

Exemplo de resposta

`1`	`[`
`2`	`{`
`3`	`"id": "03b133a9-4546-4e73-89c8-119fb5042fdb",`
`4`	`"name": "M2 Screw",`
`5`	`"cost_code": "0001",`
`6`	`"unit": "none",`
`7`	`"description": "2mm thick screw",`
`8`	`"last_updated": "2024-08-19T21:42:33.021Z",`
`9`	`"created": "2024-08-19T21:42:33.021Z"`
`10`	`},`
`11`	`{`
`12`	`"id": "c127106f-0570-485c-9466-dcf543d9ffbd",`
`13`	`"name": "MDF18",`
`14`	`"cost_code": "ABC123",`
`15`	`"unit": "m²",`
`16`	`"description": "18mm MDF",`
`17`	`"last_updated": "2024-08-05T03:08:12.870Z",`
`18`	`"created": "2024-08-05T03:08:12.870Z"`
`19`	`}`
`20`	`]`

Obter pessoas

Retorna informações sobre os objetos de pessoa. Retorna todas as pessoas.

Consulta de exemplo

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

Exemplo de resposta

[
    {
        "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"
    }
]

Obter turnos

Retorna informações sobre os objetos de turno.

Parâmetros

Propriedade	Descrição	Tipo	Obrigatoriedade
start-date	Primeiro dia dos turnos a retornar (inclusive).	Data ISO 8601 (YYYY-MM-DD)	Obrigatório
end-date	Último dia dos turnos a retornar (inclusive).	Data ISO 8601 (YYYY-MM-DD)	Obrigatório
group-id	Retorna somente turnos de pessoas que pertencem a este grupo.	UUID	Opcional
person-id	Retorna somente os turnos desta pessoa.	UUID	Opcional

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

Exemplo de resposta

[
  {
    "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
      }
    ]
  }
]

`1`	`[`
`2`	`{`
`3`	`"person_id": "a8b3e429-d307-4cg1-bde4-1c2510b8b8ef",`
`4`	`"first_name": "Ada",`
`5`	`"last_name": "Nicodemou",`
`6`	`"days": [`
`7`	`{`
`8`	`"date": "2026-02-20",`
`9`	`"total_hours": 6.82,`
`10`	`"hours_worked": 6.57,`
`11`	`"break_hours": 0.25`
`12`	`},`
`13`	`{`
`14`	`"date": "2026-02-21",`
`15`	`"total_hours": 6.98,`
`16`	`"hours_worked": 6.73,`
`17`	`"break_hours": 0.25`
`18`	`},`
`19`	`{`
`20`	`"date": "2026-02-22",`
`21`	`"total_hours": 7.02,`
`22`	`"hours_worked": 6.77,`
`23`	`"break_hours": 0.25`
`24`	`}`
`25`	`]`
`26`	`},`
`27`	`{`
`28`	`"person_id": "b1d8859f-84cc-49c0-ba94-175c8a1e16c4",`
`29`	`"first_name": "Fred",`
`30`	`"last_name": "Flinstone",`
`31`	`"days": [`
`32`	`{`
`33`	`"date": "2026-02-20",`
`34`	`"total_hours": 8.12,`
`35`	`"hours_worked": 7.95,`
`36`	`"break_hours": 0.17`
`37`	`},`
`38`	`{`
`39`	`"date": "2026-02-21",`
`40`	`"total_hours": 8.13,`
`41`	`"hours_worked": 7.88,`
`42`	`"break_hours": 0.25`
`43`	`},`
`44`	`{`
`45`	`"date": "2026-02-22",`
`46`	`"total_hours": 1.97,`
`47`	`"hours_worked": 1.72,`
`48`	`"break_hours": 0.25`
`49`	`}`
`50`	`]`
`51`	`}`
`52`	`]`

`1`	`[`
`2`	`{`
`3`	`"id": "055fdff9-c264-4c5d-a98e-e98bab581d1a",`
`4`	`"name": "63 Handover Rd",`
`5`	`"description": "",`
`6`	`"cost_code": null,`
`7`	`"due_date": null,`
`8`	`"completed": false,`
`9`	`"permanent": false,`
`10`	`"deleted": false,`
`11`	`"budget_hours": 120,`
`12`	`"priority": false,`
`13`	`"last_updated": "2024-11-01T02:22:56.973Z",`
`14`	`"created": "2024-11-01T02:22:56.973Z",`
`15`	`"groups": [`
`16`	`{`
`17`	`"id": "f8a97df7-85b9-4331-a284-9463c68810b8",`
`18`	`"name": "Mosgiel"`
`19`	`}`
`20`	`],`
`21`	`"people": null`
`22`	`},`
`23`	`]`

`1`	`{`
`2`	`"name": "99 Bamford St",`
`3`	`"description": "Renovating kitchen in 6 apartments",`
`4`	`"permanent": false,`
`5`	`"due_date": "2024-11-30 09:00",`
`6`	`"cost_code": "123456",`
`7`	`"budget_hours": 120,`
`8`	`"priority": false,`
`9`	`"completed": false,`
`10`	`"deleted": false`
`11`	`}`

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

`1`	`[`
`2`	`{`
`3`	`"id": "b6cc9e4b-cccb-4206-92a0-a387ff121c69",`
`4`	`"first_name": "Aspen",`
`5`	`"last_name": "Brewster",`
`6`	`"email": "[email protected]",`
`7`	`"pin_enabled": false,`
`8`	`"pin": null,`
`9`	`"permission": 3,`
`10`	`"last_updated": "2024-09-09T02:44:06.604Z",`
`11`	`"created": "2024-09-09T02:44:06.604Z"`
`12`	`},`
`13`	`{`
`14`	`"id": "2d68300b-f34e-45f9-a1a5-fdf0daa59729",`
`15`	`"first_name": "Bryne",`
`16`	`"last_name": "Lynton",`
`17`	`"email": null,`
`18`	`"pin_enabled": false,`
`19`	`"pin": null,`
`20`	`"permission": 3,`
`21`	`"last_updated": "2024-09-09T02:44:06.604Z",`
`22`	`"created": "2024-09-09T02:44:06.604Z"`
`23`	`}`
`24`	`]`

Guia de referência da API

Primeiros passos

Primeiros passos com o Bruno

Primeiros passos com o Postman

Referência

Obter grupos

Consulta de exemplo

Exemplo de resposta

Obter serviços

Parameters

Example Query

Exemplo de resposta

Adicionar serviço

Body

Example Query

Exemplo de resposta

Excluir serviços

Corpo

Example Query

Exemplo de resposta

Atualizar serviço

Corpo

Example Query

Exemplo de resposta

Obter quiosques

Consulta de exemplo

Exemplo de resposta

Obter materiais

Consulta de exemplo

Exemplo de resposta

Obter pessoas

Consulta de exemplo

Exemplo de resposta

Obter turnos

Parâmetros

Example Query

Exemplo de resposta

Estamos sempre felizes em ajudar. Entre em contato e faremos o possível para que nosso sistema de controle de ponto funcione para você.

Estamos sempre felizes em ajudar.
Entre em contato e faremos o possível para que nosso sistema de controle de ponto funcione para você.