API e webhooks
Como criar uma chave de API, escolher o que ela pode fazer e receber avisos de eventos em outro sistema.
Em Integrações, crie uma chave de API e marque o que ela pode fazer: só ler, ler e enviar evidências, ou escolher cada permissão. Outro sistema usa a chave para consultar pessoas, evidências, ciclos e planos. Com um webhook, o Prisma Times avisa esse sistema assim que algo acontece, como uma evidência enviada. Só o proprietário cria chaves e webhooks.
Criar uma chave
- Abra Integrações e, em Chaves de API, clique em Criar chave.
- Dê um nome que diga para que serve, como "GLPI produção", e escolha a validade.
- Escolha as permissões. Só leitura é o padrão. Leitura e evidências serve para sistemas que também enviam evidências. Em Personalizada você marca uma a uma.
- Clique em Gerar chave e copie o valor. Ele aparece uma única vez.
Você pode mudar as permissões depois, sem trocar a chave, em Permissões. Para encerrar o acesso, use Revogar: a chave deixa de funcionar na hora.
O que cada permissão libera
- Organização: nome, área, plano e configuração de ciclo e rotina. Sem dados de cobrança.
- Modelo: níveis, funções e critérios. Com a permissão de escrita, também cria e edita. Mudar o contrato de um critério gera uma versão nova, como no aplicativo.
- Pessoas: função, nível, liderança e vínculo. O e-mail só aparece com a permissão própria. Com a permissão de escrita, convida e altera pessoas respeitando as vagas do plano.
- Progressão: a situação de cada pessoa em cada critério do próximo nível.
- Evidências: consulta sem os arquivos. Os anexos têm permissão própria e chegam como links que vencem em poucos minutos. Com a permissão de escrita, o sistema envia uma evidência em nome de uma pessoa e ela aparece na fila de avaliação como enviada por integração.
- Avaliações, Ciclos, Rotina e Planos: consulta. O texto das atualizações da rotina tem permissão própria.
Uma chave sem a permissão recebe o erro 403, sem revelar se o dado existe.
Receber avisos com webhooks
- Em Webhooks de saída, clique em Criar webhook.
- Informe a URL de destino. Ela precisa ser https e acessível pela internet. Endereços internos ou locais são recusados.
- Marque os eventos que interessam e clique em Criar webhook. Copie o segredo: ele aparece uma vez e serve para conferir a assinatura de cada aviso.
- Clique em Enviar teste para ver se o seu sistema responde. A lista de entregas mostra o resultado e permite Reenviar.
Cada aviso é pequeno e traz só identificadores, como o da evidência e o da pessoa. Para ver o resto, o seu sistema consulta a API. O seu sistema deve responder com sucesso em até 10 segundos. Se falhar, o Prisma Times tenta de novo uma vez por dia. Se o webhook ficar 3 dias sem entregar, ele é desativado e você recebe um aviso no sino.
Conferir a assinatura
Cada entrega traz o cabeçalho Prisma-Signature, no formato t=<momento>,v1=<assinatura>. A assinatura é o HMAC-SHA256 de <momento>.<corpo> com o segredo do webhook. Recuse avisos com mais de 5 minutos de diferença. Os exemplos em Node e Python estão na referência da API.
Limites e erros
- Cada chave pode fazer 1.000 requisições por dia. Os cabeçalhos
RateLimit-RemainingeRetry-Aftermostram o consumo. - Se a assinatura da organização estiver inativa, a API responde 402.
- Todo envio aceita o cabeçalho
Idempotency-Key: repetir o mesmo pedido não cria nada em duplicidade. - Os erros vêm em um formato padrão, com um código estável para o seu sistema tratar.