Convenções da API

Convenções que valem para toda a superfície de integração.

Localização e fuso horário

Idioma das mensagens: português (pt-br).
Fuso horário: America/Sao_Paulo. Datas e horários são interpretados e retornados no horário local, sem conversão para UTC.
Datas no formato ISO YYYY-MM-DD; horários HH:MM[:SS].

As duas gerações da API coexistem no mesmo host:

V2 (/v2/...) — padrão REST moderno; prefira sempre a V2 quando o recurso existir nas duas versões.
V1 — mantida por compatibilidade. Operações com substituto na V2 aparecem como deprecated na referência, com a indicação do endpoint novo.

Código	Significado	Corpo típico
`400`	Erro de validação	`{"campo": ["mensagem de erro"]}`
`401`	Não autenticado (token ausente, inválido ou expirado)	detalhe do erro
`403`	Sem permissão para o recurso	detalhe do erro
`404`	Recurso não encontrado	detalhe do erro

Trate o 400 campo a campo: a chave é o nome do campo enviado e o valor é a lista de mensagens em pt-br.

Endpoints de listagem usam o padrão limit/offset com envelope:

{"count": 120, "next": "...", "previous": null, "results": []}

Upload de arquivos: máximo de 10 MB por requisição.
Rate limiting: limite de requisições por minuto configurado por ambiente. Ao receber 429, aplique backoff e repita.

Use um usuário de integração dedicado, com o menor conjunto de permissões necessário.
Não persista o token além da expiração (50 min); trate o 401 renovando o login.
Em cargas em lote, respeite a ordem de dependência dos cadastros (departamento → cargo → horário → funcionário).