Integração: guia geral
Como um sistema da sua organização vai se conectar à plataforma. Os detalhes técnicos ficam dentro da aplicação, para quem tem acesso.
Como pedir acesso
Fale com o Administrador da sua organização na plataforma. Ele cadastra o seu sistema, escolhe o que ele pode ler e entrega a chave. A documentação detalhada fica na seção APIs e Webhooks da aplicação, para quem tem login.
Chave por sistema
Cada sistema recebe uma chave própria, mostrada uma única vez; a plataforma guarda só uma versão irreversível dela. A chave pode ser trocada com um período em que a antiga ainda vale, e revogada na hora.
Escopos de leitura
A chave só lê o que o Administrador liberou, sempre dentro da sua organização. Os escopos são de leitura: escrever continua sendo trabalho de pessoas logadas.
Avisos assinados (webhooks)
A plataforma pode avisar um endereço do seu sistema quando algo acontece, por exemplo quando um colaborador é inativado. Cada aviso é assinado: confira a assinatura antes de confiar nele. O aviso não leva nome, CPF, e-mail nem telefone; o seu sistema consulta o que precisar com a chave.
Limites
Cada chave tem limite de chamadas. Os erros seguem um formato padrão, com um código que o seu sistema pode tratar.
Boas práticas
- Guarde a chave num cofre de segredos, nunca no código nem em planilha.
- Use uma chave por sistema, para revogar uma sem parar as outras.
- Confira a assinatura e a hora de cada aviso, e trate o mesmo aviso recebido duas vezes.
- Peça só os escopos de que o sistema precisa.