Integrador PONTO — terminal e exportações

Onde fica: Integrador PONTO › Cadastros › Filiais › Terminais · API em /api/v1/

O PONTO é um produto de RH e controle de jornada. Ele não oferece, hoje, uma API de integração geral para outros sistemas (como os webservices do ISP ou do OMNI). As rotas HTTP que existem para uso fora do painel do RH são as do terminal de ponto (quiosque), a exportação do AFD e a página pública da escala de sobreaviso. Esta página descreve só o que existe.

Observação

A integração entre o PONTO e o Integrador ISP (envio de holerite, confirmação de assinatura, sincronização de cadastro) está registrada como projeto à parte, ainda não implementada. O PONTO funciona de forma autônoma.

Antes de começar

• Todas as rotas ficam sob o prefixo /api/v1.
• O RH entra com e-mail e senha e recebe um token de sessão. O terminal entra com um token próprio de pareamento, criado pelo RH. Não existe "chave de API" por escopo, como nos outros produtos.

Autenticação

Sessão do RH

curl -s -X POST https://ponto.exemplo.com.br/api/v1/auth/login \
  -d "username=rh@exemplo.com.br" -d "password=senha-de-exemplo"

A resposta traz access_token, a usar como Authorization: Bearer <token>. Há limite de tentativas por IP e por e-mail.

Token do terminal (quiosque)

1. No painel do RH, vá em Cadastros › Filiais, abra Terminais na filial e crie um terminal com um nome. O token (TERM-…) aparece uma única vez — para ver outro, é preciso gerar um novo token, que invalida o anterior.
2. No tablet, o token é enviado em POST /api/v1/auth/login-terminal ({"token": "TERM-..."}), que devolve a sessão do terminal. POST /api/v1/auth/refresh-terminal renova a sessão sem colar o token de novo.

Um terminal criado dentro de uma filial reconhece só os colaboradores daquela filial. Revogar o terminal derruba o acesso do tablet na ação seguinte.

Recursos

Terminal (sessão do terminal)

O terminal identifica o colaborador por rosto ou matrícula e age em nome dele.

Método e rota	Para quê
GET /terminal/me	Identifica o terminal pareado: terminal_id, nome e empresa_nome.
POST /terminal/identificar	Identifica por rosto: face_embedding (um vetor de 128 números) ou face_embeddings (até 5, para votação). Devolve funcionario_id, nome, matricula e score.
POST /terminal/por-matricula	Identifica por matrícula (matricula).
POST /terminal/marcacao	Registra o ponto. Campos: funcionario_id, tipo (entrada/saida; se omitido, o sistema calcula o esperado), foto_base64, face_embedding, latitude, longitude, accuracy, mocked, via_matricula. Devolve nsr, tipo e hora.
POST /terminal/reajuste	Abre pedido de reajuste de ponto — entra pendente para o RH aprovar.
POST /terminal/justificativa	Abre justificativa de falta ou abono (tipo: atestado, falta, abono, outro), pendente para o RH.
GET /terminal/documentos, POST /terminal/documentos/{id}/assinar, POST /terminal/documentos/{id}/ciencia	Documentos do colaborador: listar, assinar e dar ciência.

Exportação (sessão do RH)

Método e rota	Para quê
GET /afd	Gera o AFD (Arquivo Fonte de Dados, Anexo V da Portaria MTP 671/2021), em texto ISO-8859-1. Parâmetros: inicio e fim (AAAA-MM-DD, opcionais) e formato (posicional, o padrão, ou estruturado, para conferência).

Página pública da escala de sobreaviso (sem login)

Método e rota	Para quê
GET /publico/escala/{token}	A escala de sobreaviso de um grupo ou da empresa, identificada pelo token do link. Parâmetros ano e mes. Expõe só o que o modo do link permite; token inválido: 404.
GET/POST/DELETE /grupos/{id}/link-publico	(RH) Ver, gerar ou revogar o link público de um grupo. regenerar=true troca o token e o link antigo para de funcionar na hora.

Exemplos

Registrar uma batida pelo terminal

curl -s -X POST https://ponto.exemplo.com.br/api/v1/terminal/marcacao \
  -H "Authorization: Bearer <sessao-do-terminal>" \
  -H "Content-Type: application/json" \
  -d '{"funcionario_id": "00000000-0000-0000-0000-000000000010", "tipo": "entrada",
       "via_matricula": true}'

{"ok": true, "nsr": 1021, "tipo": "entrada", "hora": "2026-10-20T11:02:00+00:00"}

Baixar o AFD de um período

curl -s "https://ponto.exemplo.com.br/api/v1/afd?inicio=2026-10-01&fim=2026-10-31" \
  -H "Authorization: Bearer <sessao-do-rh>" -o AFD_outubro.txt

Regras que as rotas aplicam

Atenção

• Toda ação do terminal confere que o colaborador é da mesma empresa do terminal (e da filial, quando o terminal tem filial). Ações de colaborador desligado são recusadas.
• Reajuste e justificativa pelo terminal nunca alteram o ponto sozinhos: entram pendentes, com a selfie guardada como prova, para o RH aprovar.
• Marcação por matrícula (rosto não reconhecido) é salva com a foto e fica marcada como suspeita para o RH conferir.

Erros comuns

Código	Quando
401	Token de terminal ou sessão inválidos ou revogados.
404	Colaborador não encontrado nesta empresa.
400	Datas do AFD inválidas ou formato desconhecido.
429	Muitas tentativas de login.

Leia também

• Integrações — visão geral
• Integrador ISP