Formatos de identificador

A Ligga API identifica todo registro por UUID versão 4, no formato da RFC 4122. São 36 caracteres, minúsculos, com hífens:

c06d8705-f091-46e1-81bb-4a2cec656694

O formato é o mesmo nos quinze recursos da API. Os catorze recursos de coleção expõem id: Clientes (customers), Vendas (sales), Fornecedores (suppliers), Despesas (expenses), Agendamentos (appointments), Serviços (services), Produtos (products), Estoque (inventory), Contas bancárias (bank-accounts), Projetos (projects), Oportunidades (deals), Formulários (forms), Veículos (vehicles) e Pets (pets). Sua conta (me) não tem id próprio: expõe team_id e key_id.

Onde os UUIDs aparecem

Lugar	Exemplo
`id` de qualquer registro	`"id": "c06d8705-f091-46e1-81bb-4a2cec656694"`
`id` de item aninhado, como os itens de uma venda	`"items": [{ "id": "c06d8705-f091-46e1-81bb-4a2cec656694" }]`
Referência a outro recurso no corpo	`"customer_id": "c06d8705-f091-46e1-81bb-4a2cec656694"`
Segmento `{id}` do caminho	`GET /v1/customers/c06d8705-f091-46e1-81bb-4a2cec656694`
`team_id` e `key_id`, em `GET /v1/me`	`"team_id": "c06d8705-f091-46e1-81bb-4a2cec656694"`

Os identificadores são estáveis: o id de um registro não muda ao longo da vida dele, nem quando o registro é desativado. Guarde-o como chave estrangeira no seu lado, em vez de reconciliar por nome ou por documento.

Validação no cliente

Vale conferir o formato antes de gastar uma requisição:

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

if (!UUID_RE.test(customerId)) {
  throw new Error(`customer_id inválido: ${customerId}`);
}

Um identificador malformado é recusado com 422 e type validation, sem chegar ao banco. Um identificador bem formado que não corresponde a nenhum registro da sua conta devolve 404 com type not_found.

Identificadores que não são UUID

Identificador	Formato	Origem
`request_id`, no corpo e no cabeçalho `X-Request-Id`	`req_` seguido de 32 caracteres hexadecimais	A API gera. É o que o suporte pede
`Idempotency-Key`	Qualquer texto de 1 a 255 caracteres. Recomendados: UUID v4 ou ULID	Você gera
`cursor`, na paginação	Texto opaco em base64url	A API gera. Copie da resposta, não interprete
`plan_code`, `modules`, escopos	Texto curto em minúsculas	A API define. Valores fechados

Se a sua integração já tem um identificador de correlação, envie-o em X-Request-Id na requisição: até 128 caracteres entre letras, números, _ e - são aceitos e reaproveitados na resposta. Fora desse formato, a API gera o próprio.

Por que UUID

A API herda o modelo de dados do aplicativo principal da Ligga, que padronizou em UUID v4 desde o começo. A escolha se sustenta por três motivos:

é suportado em qualquer linguagem e em qualquer banco, sem biblioteca extra;
é gerado nativamente pelo Postgres, o que evita uma ida ao servidor só para reservar um identificador;
não revela ordem nem volume, ao contrário de um inteiro sequencial, que entrega quantos registros a conta tem.

A desvantagem é que UUID v4 não tem ordenação natural. A paginação por cursor resolve isso: ela ordena por um campo de data e desempata pelo id.

Veja também

Erros — o corpo do 422 e do 404
Paginação, filtros e ordenação — o cursor e como ele usa o id
Idempotência — como escolher o valor de Idempotency-Key
Sua conta (me) — onde ler team_id e key_id