Agendamentos (appointments)

O recurso appointments expõe os agendamentos da sua conta. Cada registro traz a data, o horário de início e de término, o status, as observações da equipe e do cliente, e os vínculos com cliente, pet e transação financeira.

Acesso


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

Endpoints

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

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador do agendamento
`customer_id`	`uuid`	Cliente vinculado ao agendamento
`appointment_date`	`date` (`YYYY-MM-DD`)	Data do agendamento
`start_time`	`time` (`HH:MM:SS`)	Horário de início
`end_time`	`time` (`HH:MM:SS`)	Horário de término
`status`	`string`	Status atual, por exemplo `scheduled`, `confirmed`, `completed` ou `cancelled`
`appointment_type`	`string \| null`	Tipo do agendamento, definido pela conta
`notes`	`string \| null`	Observações internas da equipe
`customer_notes`	`string \| null`	Observações enviadas pelo cliente
`cancellation_reason`	`string \| null`	Motivo do cancelamento, quando houver
`has_passed`	`boolean \| null`	Indica se o horário do agendamento já passou
`transaction_id`	`uuid \| null`	Transação financeira vinculada, quando houver
`pet_id`	`uuid \| null`	Pet vinculado, em contas com o módulo `pets`
`is_active`	`boolean \| null`	`false` quando o registro foi desativado
`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,appointment_date,start_time,status.

Filtros e ordenação

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

Campo	Exemplo
`appointment_date`	`filter[appointment_date][gte]=2026-07-01`
`status`	`filter[status][in]=scheduled,confirmed`
`customer_id`	`filter[customer_id][eq]=4d2f8a91-6b3e-47c0-9d55-e1a2b3c4d5e6`
`is_active`	`filter[is_active][eq]=true`

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 appointment_date. 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

Agendamentos com status scheduled, do mais recente para o mais antigo:

curl -G "$LIGGA_BASE/v1/appointments" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "limit=2" \
  --data-urlencode "sort=-appointment_date" \
  --data-urlencode "filter[status][eq]=scheduled"

{
  "data": [
    {
      "id": "b7e0a1f4-3c9d-4e2b-8f61-2a7d9c5e0b13",
      "customer_id": "4d2f8a91-6b3e-47c0-9d55-e1a2b3c4d5e6",
      "appointment_date": "2026-07-15",
      "start_time": "14:00:00",
      "end_time": "15:00:00",
      "status": "scheduled",
      "appointment_type": "banho_e_tosa",
      "notes": "Cliente prefere atendimento com a Paula.",
      "customer_notes": "Chego 10 min antes.",
      "cancellation_reason": null,
      "has_passed": false,
      "transaction_id": null,
      "pet_id": "7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "is_active": true,
      "created_at": "2026-07-01T18:22:10.512Z",
      "updated_at": "2026-07-02T09:05:44.301Z"
    },
    {
      "id": "a1c2e3d4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
      "customer_id": "4d2f8a91-6b3e-47c0-9d55-e1a2b3c4d5e6",
      "appointment_date": "2026-07-10",
      "start_time": "09:30:00",
      "end_time": "10:00:00",
      "status": "scheduled",
      "appointment_type": "consulta",
      "notes": null,
      "customer_notes": null,
      "cancellation_reason": null,
      "has_passed": false,
      "transaction_id": "0e9d8c7b-6a5f-4e3d-2c1b-0a9f8e7d6c5b",
      "pet_id": null,
      "is_active": true,
      "created_at": "2026-06-28T11:40:02.118Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImExYzJlM2Q0LS4uLiIsInYiOiIyMDI2LTA2LTI4VDExOjQwOjAyLjExOFoifQ",
    "has_more": true,
    "limit": 2
  },
  "meta": {
    "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V"
  }
}

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

Um recorte de período combina dois operadores no mesmo campo:

curl -G "$LIGGA_BASE/v1/appointments" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "filter[appointment_date][gte]=2026-07-01" \
  --data-urlencode "filter[appointment_date][lte]=2026-07-31" \
  --data-urlencode "filter[status][eq]=confirmed"

Buscar por id

curl "$LIGGA_BASE/v1/appointments/b7e0a1f4-3c9d-4e2b-8f61-2a7d9c5e0b13" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "b7e0a1f4-3c9d-4e2b-8f61-2a7d9c5e0b13",
    "customer_id": "4d2f8a91-6b3e-47c0-9d55-e1a2b3c4d5e6",
    "appointment_date": "2026-07-15",
    "start_time": "14:00:00",
    "end_time": "15:00:00",
    "status": "scheduled",
    "appointment_type": "banho_e_tosa",
    "notes": "Cliente prefere atendimento com a Paula.",
    "customer_notes": "Chego 10 min antes.",
    "cancellation_reason": null,
    "has_passed": false,
    "transaction_id": null,
    "pet_id": "7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "is_active": true,
    "created_at": "2026-07-01T18:22:10.512Z",
    "updated_at": "2026-07-02T09:05:44.301Z"
  },
  "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 `agendamentos` fora do contrato
403	`insufficient_scope`	Chave sem `appointments: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

Serviços (services) — o catálogo que alimenta a agenda
Paginação, filtros e ordenação — cursor, sort e fields
Módulos e escopos — por que um 403 acontece
Erros — o formato da resposta de erro