Projetos (projects)

O recurso projects expõe os projetos da sua conta: número, nome, cliente vinculado, status, progresso e as datas planejadas e realizadas. É o mesmo cadastro que aparece no módulo Projetos do aplicativo.

Acesso


Módulo	`projetos`
Escopos	`projects:read` (ou `:read`, ou `:write`)
Operações	somente leitura

Sem o módulo no contrato, a resposta é 403 module_not_enabled. Sem o escopo na chave, é 403 insufficient_scope.

Endpoints

Método	Endpoint	Descrição
`GET`	`/v1/projects`	Lista projetos, com paginação por cursor
`GET`	`/v1/projects/{id}`	Retorna um projeto pelo `id`

A listagem usa o envelope padrão com data, pagination e meta, e aceita limit (1 a 100, padrão 20), cursor, sort e fields. Veja Paginação, filtros e ordenação.

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador do projeto
`project_number`	`string \| null`	Número sequencial do projeto
`name`	`string`	Nome do projeto
`description`	`string \| null`	Descrição livre
`color`	`string \| null`	Cor de exibição usada no aplicativo, em hexadecimal
`customer_id`	`uuid \| null`	Cliente vinculado, do recurso `customers`
`status`	`string`	Situação do projeto, por exemplo `planning`, `in_progress`, `completed`
`progress_percentage`	`number \| null`	Progresso em porcentagem, de 0 a 100
`start_date`	`date (YYYY-MM-DD) \| null`	Data de início planejada
`estimated_end_date`	`date (YYYY-MM-DD) \| null`	Data de término estimada
`actual_end_date`	`date (YYYY-MM-DD) \| null`	Data de término real
`tags`	`string[] \| null`	Etiquetas livres
`notes`	`string \| null`	Anotações internas
`is_active`	`boolean \| null`	`false` quando o projeto foi desativado
`created_at`	`timestamp (ISO 8601) \| null`	Criação do registro
`updated_at`	`timestamp (ISO 8601) \| null`	Última atualização

Filtros e ordenação

Campo	Operadores	Exemplo
`status`	`eq`, `in`	`filter[status][in]=planning,in_progress`
`customer_id`	`eq`	`filter[customer_id][eq]=3c9d8e7f-6a5b-4c3d-9e1f-0a9b8c7d6e5f`
`name`	`ilike`	`filter[name][ilike]=%reforma%`
`is_active`	`eq`	`filter[is_active][eq]=true`

Filtros combinam com AND. A ordenação padrão é -created_at; sort também aceita created_at, updated_at e name, com - na frente para ordem decrescente.

Exemplos

Listar

curl "$LIGGA_BASE/v1/projects?limit=2&sort=-created_at&filter[status][in]=planning,in_progress&filter[is_active][eq]=true" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": [
    {
      "id": "7b1e2f30-9c4d-4a1b-8e5f-2d6c7a8b9c0d",
      "project_number": "PRJ-0042",
      "name": "Reforma cozinha — Ap. 302",
      "description": "Reforma completa da cozinha com troca de bancada.",
      "color": "#14D484",
      "customer_id": "3c9d8e7f-6a5b-4c3d-9e1f-0a9b8c7d6e5f",
      "status": "in_progress",
      "progress_percentage": 45,
      "start_date": "2026-06-01",
      "estimated_end_date": "2026-08-15",
      "actual_end_date": null,
      "tags": ["reforma", "residencial"],
      "notes": "Cliente prefere visitas às terças.",
      "is_active": true,
      "created_at": "2026-05-28T14:03:11.000Z",
      "updated_at": "2026-07-02T09:41:27.000Z"
    },
    {
      "id": "a4f5b6c7-d8e9-4f0a-b1c2-d3e4f5a6b7c8",
      "project_number": "PRJ-0041",
      "name": "Projeto elétrico — Galpão Norte",
      "description": null,
      "color": "#4899C1",
      "customer_id": null,
      "status": "planning",
      "progress_percentage": 10,
      "start_date": "2026-07-20",
      "estimated_end_date": "2026-09-30",
      "actual_end_date": null,
      "tags": null,
      "notes": null,
      "is_active": true,
      "created_at": "2026-05-20T10:15:00.000Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImE0ZjViNmM3LWQ4ZTktNGYwYS1iMWMyLWQzZTRmNWE2YjdjOCIsInYiOiIyMDI2LTA1LTIwVDEwOjE1OjAwLjAwMFoifQ",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01JZXK4W8Q5M7N9P0R1S2T3U4V" }
}

Para a próxima página, repita a chamada com cursor=<pagination.next_cursor> enquanto has_more for true.

Buscar por id

curl "$LIGGA_BASE/v1/projects/7b1e2f30-9c4d-4a1b-8e5f-2d6c7a8b9c0d?fields=id,name,status,progress_percentage" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "7b1e2f30-9c4d-4a1b-8e5f-2d6c7a8b9c0d",
    "name": "Reforma cozinha — Ap. 302",
    "status": "in_progress",
    "progress_percentage": 45
  },
  "meta": { "request_id": "req_01JZXK4W8Q5M7N9P0R1S2T3U4V" }
}

Erros comuns

HTTP	`type`	Quando acontece
401	`invalid_token`	Cabeçalho `Authorization` ausente ou chave inexistente
403	`insufficient_scope`	Chave sem `projects:read`
403	`module_not_enabled`	Módulo `projetos` fora do contrato
404	`not_found`	`id` inexistente ou de outra conta
422	`validation`	Campo de filtro, operador, `sort` ou `cursor` não aceito
429	`rate-limit-exceeded`	Limite de requisições do plano excedido

Veja também

Paginação, filtros e ordenação — limit, cursor, sort e fields
Módulos e escopos — o que o módulo projetos libera
Clientes (customers) — o cliente em customer_id
Erros — o corpo de erro completo