Pets (pets)

O recurso pets expõe os animais cadastrados na sua conta: espécie, raça, sexo, data de nascimento, peso, castração e dados de identificação como microchip e número de registro.

Acesso


Módulo	`pets`
Escopos	`pets: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/pets`	Lista pets, com paginação por cursor
`GET`	`/v1/pets/{id}`	Retorna um pet 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. Pets removidos no aplicativo não aparecem em nenhuma das duas chamadas.

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador do pet
`name`	`string`	Nome do pet
`pet_species_id`	`uuid`	Espécie do pet
`pet_breed_id`	`uuid \| null`	Raça, quando vem do catálogo de raças
`breed_text`	`string \| null`	Raça em texto livre, quando não catalogada
`gender`	`string`	Sexo do pet, por exemplo `male`, `female`
`birth_date`	`date (YYYY-MM-DD) \| null`	Data de nascimento
`color`	`string \| null`	Cor da pelagem
`weight_kg`	`number \| null`	Peso em quilogramas
`is_neutered`	`boolean \| null`	Se o pet é castrado
`microchip_number`	`string \| null`	Número do microchip
`registration_number`	`string \| null`	Número de registro, como pedigree
`photo_url`	`string \| null`	URL da foto do pet
`notes`	`string \| null`	Observações livres
`created_at`	`timestamp (ISO 8601)`	Criação do registro
`updated_at`	`timestamp (ISO 8601)`	Última atualização

Os valores de pet_species_id e pet_breed_id apontam para os catálogos de espécies e raças, que ainda não estão expostos na API. Guarde-os como chaves opacas e compare uma listagem com a outra para agrupar por espécie.

Filtros e ordenação

Campo	Operadores	Exemplo
`name`	`eq`, `ilike`	`filter[name][ilike]=thor%25`
`pet_species_id`	`eq`, `in`	`filter[pet_species_id][eq]=6c1a9d47-3b2e-4f8a-9c5d-2e0b7f4a1d63`
`gender`	`eq`	`filter[gender][eq]=male`

Filtros combinam com AND. Em ilike, o curinga % precisa ser codificado como %25 na URL. 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/pets?limit=2&sort=-created_at&filter[gender][eq]=male" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": [
    {
      "id": "a4e19c72-5d3b-4f8e-b6a1-9c2d7e0f4b58",
      "name": "Thor",
      "pet_species_id": "6c1a9d47-3b2e-4f8a-9c5d-2e0b7f4a1d63",
      "pet_breed_id": "d2f8b431-7a6c-4e9d-8b0f-5c3a1e9d7b26",
      "breed_text": null,
      "gender": "male",
      "birth_date": "2022-08-15",
      "color": "Dourado",
      "weight_kg": 28.4,
      "is_neutered": true,
      "microchip_number": "981098106543210",
      "registration_number": null,
      "photo_url": "https://cdn.ligga.app/pets/thor.jpg",
      "notes": "Alérgico a frango. Prefere tosa na máquina 2.",
      "created_at": "2026-04-02T11:18:44.207Z",
      "updated_at": "2026-06-21T16:02:19.633Z"
    },
    {
      "id": "f7b3d5e9-1c4a-4b8d-a2e6-8f0c9b7d3a41",
      "name": "Thorzinho",
      "pet_species_id": "6c1a9d47-3b2e-4f8a-9c5d-2e0b7f4a1d63",
      "pet_breed_id": null,
      "breed_text": "SRD (vira-lata)",
      "gender": "male",
      "birth_date": null,
      "color": "Caramelo",
      "weight_kg": 12,
      "is_neutered": false,
      "microchip_number": null,
      "registration_number": null,
      "photo_url": null,
      "notes": null,
      "created_at": "2026-03-19T09:37:05.481Z",
      "updated_at": "2026-03-19T09:37:05.481Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImY3YjNkNWU5LTFjNGEtNGI4ZC1hMmU2LThmMGM5YjdkM2E0MSIsInYiOiIyMDI2LTAzLTE5VDA5OjM3OjA1LjQ4MVoifQ",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01JWQ8V2K5M7N9P0R1S2T3U4VY" }
}

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/pets/a4e19c72-5d3b-4f8e-b6a1-9c2d7e0f4b58?fields=id,name,gender,weight_kg,microchip_number" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "a4e19c72-5d3b-4f8e-b6a1-9c2d7e0f4b58",
    "name": "Thor",
    "gender": "male",
    "weight_kg": 28.4,
    "microchip_number": "981098106543210"
  },
  "meta": { "request_id": "req_01JWQ8V2K5M7N9P0R1S2T3U4VY" }
}

Erros comuns

HTTP	`type`	Quando acontece
401	`invalid_token`	Cabeçalho `Authorization` ausente ou chave inexistente
403	`insufficient_scope`	Chave sem `pets:read`
403	`module_not_enabled`	Módulo `pets` fora do contrato
404	`not_found`	`id` inexistente, removido 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 pets libera
Formatos de identificador — o formato dos campos uuid
Erros — o corpo de erro completo