Serviços (services)

O recurso services consulta o cadastro legado de serviços da conta. Cada registro traz nome, descrição, categoria, duração padrão, preço e cor.

Na navegação, produtos e serviços ficam em Catálogo. O contrato de services exige o módulo catalogo, mantendo o schema do cadastro legado. Consulte também os produtos do catálogo.

Acesso


Módulo	`catalogo`
Escopos	`services:read` (também concedido por `:read` e por `:write`)
Operações	somente leitura

Endpoints

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

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador do serviço
`name`	`string`	Nome do serviço
`description`	`string \| null`	Descrição livre do serviço
`category_id`	`uuid \| null`	Categoria do serviço, usada para agrupar na agenda
`duration_minutes`	`integer`	Duração padrão em minutos
`price`	`number \| null`	Preço do serviço, em reais
`requires_staff`	`boolean \| null`	Se o serviço exige um profissional atribuído
`color`	`string \| null`	Cor de exibição na agenda, por exemplo `#14D484`
`is_active`	`boolean \| null`	Se o serviço está disponível para agendamento
`created_at`	`string (ISO 8601) \| null`	Data de criação
`updated_at`	`string (ISO 8601) \| null`	Data da última atualização

Use fields para receber só um subconjunto das colunas: ?fields=id,name,duration_minutes,price.

Filtros e ordenação

A sintaxe do filtro é filter[campo][operador]=valor. Os campos filtráveis de services são:

Campo	Exemplo
`name`	`filter[name][ilike]=corte%`
`is_active`	`filter[is_active][eq]=true`
`category_id`	`filter[category_id][eq]=8f3b2d10-6c5e-4a9b-b1d2-0e7f4a6c8d92`

Os operadores aceitos são eq, neq, gt, gte, lt, lte, in, nin, ilike e is_null. Um campo fora da lista acima responde 422 validation.

A ordenação usa sort=campo para crescente e sort=-campo para decrescente. Os campos ordenáveis são created_at, updated_at e name. O padrão é -created_at.

A listagem também aceita limit (de 1 a 100, padrão 20) e cursor. Veja Paginação, filtros e ordenação.

Exemplos

Listar

Serviços ativos, dois por página:

curl -G "$LIGGA_BASE/v1/services" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "limit=2" \
  --data-urlencode "filter[is_active][eq]=true"

{
  "data": [
    {
      "id": "3f2c8a1e-9b4d-4c6a-8e2f-1a7d5b9c0e34",
      "name": "Corte de cabelo",
      "description": "Corte masculino com máquina e tesoura",
      "category_id": "8f3b2d10-6c5e-4a9b-b1d2-0e7f4a6c8d92",
      "duration_minutes": 45,
      "price": 60,
      "requires_staff": true,
      "color": "#14D484",
      "is_active": true,
      "created_at": "2026-05-12T14:03:21.512Z",
      "updated_at": "2026-06-30T09:41:07.884Z"
    },
    {
      "id": "b91d4e7a-2c3f-48b5-9a6d-4e8c1f0b7a25",
      "name": "Barba completa",
      "description": null,
      "category_id": "8f3b2d10-6c5e-4a9b-b1d2-0e7f4a6c8d92",
      "duration_minutes": 30,
      "price": 40,
      "requires_staff": true,
      "color": "#4899C1",
      "is_active": true,
      "created_at": "2026-05-12T14:05:48.109Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImI5MWQ0ZTdhLi4uIiwidiI6IjIwMjYtMDUtMTJUMTQ6MDU6NDguMTA5WiJ9",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

Enquanto pagination.has_more for true, repita a chamada passando cursor=<pagination.next_cursor>.

Buscar por nome usa ilike, em que % é o coringa:

curl -G "$LIGGA_BASE/v1/services" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "filter[name][ilike]=corte%" \
  --data-urlencode "sort=name"

Buscar por id

curl "$LIGGA_BASE/v1/services/3f2c8a1e-9b4d-4c6a-8e2f-1a7d5b9c0e34" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "3f2c8a1e-9b4d-4c6a-8e2f-1a7d5b9c0e34",
    "name": "Corte de cabelo",
    "description": "Corte masculino com máquina e tesoura",
    "category_id": "8f3b2d10-6c5e-4a9b-b1d2-0e7f4a6c8d92",
    "duration_minutes": 45,
    "price": 60,
    "requires_staff": true,
    "color": "#14D484",
    "is_active": true,
    "created_at": "2026-05-12T14:03:21.512Z",
    "updated_at": "2026-06-30T09:41:07.884Z"
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

Erros comuns

HTTP	`type`	Quando acontece
401	`invalid_token`	Cabeçalho `Authorization` ausente ou chave inexistente
403	`api_disabled`	A conta ainda não tem a API habilitada
403	`module_not_enabled`	Módulo `catalogo` fora do contrato
403	`insufficient_scope`	Chave sem `services:read`
404	`not_found`	`id` inexistente ou pertencente a 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

Agendamentos (appointments) — a agenda que consome estes serviços
Produtos (products) — o catálogo de itens vendidos
Paginação, filtros e ordenação — cursor, sort e fields
Módulos e escopos — por que um 403 acontece