Chaves de API
Guia: Chaves de API em Configurações.
Gerencia chaves de autenticação para a API pública do TAGGUIRH. Cada chave pertence à empresa e pode ter escopos de leitura específicos.
A documentação técnica da API (https://api.tagguirh.com.br/docs) abre pelo botão Ver documentação desta tela, com o usuário logado na plataforma. Quem acessar o endereço direto, sem passar pela plataforma, vê o aviso para entrar por ela. Para um integrador sem usuário na plataforma, o RH pode criar um usuário para ele ou enviar o arquivo da especificação (openapi.json) aberto por esse botão.
Visão geral
| Aspecto | Detalhe |
|---|---|
| Limite de tráfego | 60 pedidos/minuto por chave (fixo na plataforma, não editável) |
| Segredo | Exibido uma única vez na criação — não é possível recuperar depois |
| Documentação externa | Botão Ver documentação → abre https://api.tagguirh.com.br/docs já autenticado (acesso válido por 8 horas) |
| Validade da chave | Chave nova expira em 365 dias; chaves criadas antes continuam sem data de expiração |
| URL direta | /configuracoes/?tab=chaves-api (rota legada /configuracoes/chaves-api/ redireciona para esta aba) |
Lista de chaves
Colunas da tabela:
| Coluna | Descrição |
|---|---|
| Nome | Identificação interna da chave |
| Escopos | Lista dos escopos concedidos |
| Estado | Ativa ou Revogada |
| RPM | Limite exibido (60) |
| Último uso | Data/hora do último request (ou —) |
| Criada em | Data/hora de criação |
| Ações | Revogar (ativa) ou Reativar (revogada) |
Paginação: 20 chaves por página quando houver mais registros.
Criar chave
Botão Nova chave abre o modal Nova chave de API:
| Campo | Obrigatório | Descrição |
|---|---|---|
| Nome | Sim | Ex.: "Integração ERP" |
| Descrição | Não | Notas internas sobre o uso |
| Escopos | Sim (≥ 1) | Ver tabela abaixo |
| Expira em | Não | Em Opções avançadas — data/hora futura |
Escopos disponíveis
| Escopo | Acesso |
|---|---|
colaboradores:read | Leitura de colaboradores |
cargos:read | Leitura de cargos |
departamentos:read | Leitura de departamentos |
pdis:read | Leitura dos PDIs. GET /v1/pdis lista os planos (status, evolução, prazo e quantidade de ações). GET /v1/pdis/resumo devolve os totais. Não cria nem altera planos |
ponto_integracao:read | Equipes e batidas do Ponto (/v1/integracao/ponto/*) |
| Holerites (envio) | A contabilidade ou o sistema de folha envia os holerites em PDF de cada colaborador (por CPF e competência) direto para a plataforma, sem lote manual, e consulta o que já enviou |
| Tarefas da admissão (leitura) | O sistema da empresa lista as tarefas internas das admissões digitais (TI, DP, benefícios…) com os campos de cada uma, para abrir os chamados lá |
| Tarefas da admissão (conclusão) | O sistema da empresa conclui a tarefa da admissão com as respostas dos campos ao fechar o chamado. A tarefa fica concluída na admissão e o RH é avisado |
| Sincronização com dispositivos (leitura) | Catracas e outros dispositivos de acesso recebem a situação de cada colaborador (liberado ou bloqueado, com o motivo) e a foto, para manter o acesso em dia |
A lista de escopos pode crescer em versões futuras — consulte a documentação oficial da API pelo botão Ver documentação.
Opções avançadas
| Campo | Regra |
|---|---|
| Expira em | Opcional; deve ser data futura; inválida se no passado |
Após Criar chave com sucesso:
- Modal Guarde a chave agora exibe o segredo completo
- Use Copiar e armazene em cofre de senhas ou secret manager
- Fechar — o segredo não será mostrado novamente
Revogar e reativar
| Ação | Efeito |
|---|---|
| Revogar | Chave passa a Revogada; requests deixam de ser aceitos |
| Reativar | Chave Revogada volta a Ativa (mesmo segredo anterior) |
Revogar em produção interrompe integrações imediatamente. Combine com o time técnico antes de revogar chaves em uso.
Segurança — boas práticas
- Uma chave por integração (ERP, BI, middleware) para facilitar auditoria e revogação.
- Conceda apenas os escopos mínimos necessários.
- Nunca commite o segredo em repositório ou envie por e-mail/chat.
- Defina data de expiração para integrações temporárias ou projetos piloto.
- Monitore Último uso para detectar chaves abandonadas.
- Revogue chaves de fornecedores ao encerrar contrato.
Relação com outras guias
Os escopos de leitura expõem dados cadastrados em:
- Departamentos →
departamentos:read - Cargos →
cargos:read - Colaboradores →
colaboradores:read
Para visão de arquitetura de integrações, veja também Integrações e APIs.