Convenções

Envelope de resposta

Toda resposta de sucesso vem dentro de data, podendo trazer um objeto meta com os filtros aplicados (período, identificadores).

{
  "data": [
    { "id": 1, "description": "Recursos Humanos" }
  ],
  "meta": {
    "begin_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}

Envelope de erro

Erros sempre seguem o formato { error: { code, message } }. Confira o catálogo de códigos para entender cada caso.

{
  "error": {
    "code": "date_range_exceeded",
    "message": "O período máximo é de 31 dias."
  }
}

Erros de validação (422)

Quando faltam campos obrigatórios, a resposta também inclui payload_data_required listando o que está faltando:

{
  "error": {
    "code": "validation_failed",
    "message": "Campos obrigatórios ausentes."
  },
  "payload_data_required": ["begin_date", "end_date"]
}

Status HTTP

Datas e horários

• Datas: YYYY-MM-DD (ex.: 2026-05-26).
• Datas com hora: YYYY-MM-DD HH:MM:SS (ex.: 2026-05-26 08:00:00).
• Fuso: horário local da empresa (Brasília por padrão).
• Durações: HH:MM:SS, com sinal quando aplicável (-00:15:00).

Períodos de consulta

Endpoints que aceitam begin_date e end_date têm um limite máximo de 31 dias por requisição. Períodos maiores retornam date_range_exceeded (422).

Formato decimal das horas

Endpoints de horas (totalHours, getFromPeriod) aceitam o parâmetro opcional decimal_format=1. Quando enviado, valores como 08:30:00 são retornados como 8.5, e 00:00:00 vira 0.

Grupos econômicos (matriz e filiais)

Quando o token é de uma matriz, todos os endpoints GET aceitam dois parâmetros opcionais para acessar as filiais do grupo. Sem eles, o escopo é apenas a própria empresa (comportamento padrão).

• include_branches=1 — agrega a matriz e todas as filiais na resposta.
• company_national_registry=<CNPJ> — restringe a uma empresa específica do grupo. Use os CNPJs de GET /economic-group. CNPJ fora do grupo retorna company_not_found (404).

Para identificar a origem de cada registro, toda resposta de leitura traz um bloco company com o nome e o CNPJ da empresa:

{
  "company": {
    "name": "Filial São Paulo LTDA",
    "national_registry": "12345678000288"
  }
}

Buscar um colaborador de uma filial (CPF / e-mail)

Os filtros de colaborador (national_registry_list[], email_list[], national_registry) são combinados com o escopo de empresa. Para encontrar alguém que está numa filial, mande o filtro do colaborador junto com include_branches=1 (procura no grupo todo) ou company_national_registry (procura só naquela filial). Sem um dos dois, o escopo é só a matriz e o colaborador da filial não é encontrado.

# CPF de um colaborador que está na filial — agregando o grupo
GET /customer/v2/point/getFromPeriod?begin_date=2026-05-01&end_date=2026-05-31&include_branches=1&national_registry_list[]=12345678900

# ou mirando diretamente a filial pelo CNPJ
GET /customer/v2/point/getFromPeriod?begin_date=2026-05-01&end_date=2026-05-31&company_national_registry=12345678000288&national_registry_list[]=12345678900

• Busca por e-mail (email_list[]): disponível em collaborator/totalHours e point/getFromPeriod. Os relatórios tardiness, adjustment, overtime e inconsistency filtram apenas por national_registry (CPF).
• CPF repetido no grupo: se a mesma pessoa for colaboradora em mais de uma empresa, include_branches=1 retorna uma ocorrência por empresa — use o bloco company para distinguir, ou company_national_registry para trazer só uma.

Listas vazias

Quando nenhum dado é encontrado, a resposta é 200 com { "data": [] }. Endpoints de período mantêm o meta com os filtros usados.