/patrimonio/integracoes/chaves · "Configurações" → cartão "Chaves de API"integration.read ("Ver integrações") — lista e uso. Criar, rotacionar e revogar exigem api-key.manage ("Gerenciar chaves de API"); os botões aparecem para todos, mas sem a chave o servidor recusa ("Você não tem a permissão necessária: Gerenciar chaves de API.").Para que serve
Dar a um sistema externo acesso à API pública do Patrimônio, com escopo limitado (o que ele pode ler ou escrever), limite de chamadas por minuto, faixas de rede permitidas e validade. Sem nenhuma chave, a API pública fica fechada. A chave completa só é mostrada uma vez, na criação ou rotação; na lista aparece só o prefixo (ex.: "pqp_abcd1234…").
A tela, marcação por marcação
As figuras abaixo mostram a tela como ela aparece para quem usa. Os números em vermelho marcam os botões e campos; logo abaixo de cada figura, cada número é explicado: onde fica, o que faz e o que acontece depois.
Visão geral da tela

- Abre a janela "Nova chave de API".
Como a tela está organizada (de cima para baixo)
- Cabeçalho — caminho "Integrações › Chaves", título "Chaves de API", subtítulo "Quem entra pela API pública, com que escopo e de onde." À direita, "Nova chave" (ícone de chave) — só para quem tem
api-key.manage; sem ela também não aparecem "Rotacionar" e "Revogar" (fica só "Ver uso"). - Três números: "Chaves em uso" · "Nunca usadas" ("Chave que ninguém usa é porta aberta sem vigia.") · "Expirando em 30 dias".
- Tabela — "Chave" (nome e prefixo "pqp_…"), "Escopos" (selos com o nome público, ex.: "assets:read"), "Origem" (faixas de rede ou "Qualquer lugar"), "Limite" ("N/min"), "Último uso" (data e endereço de rede de origem), "Situação" ("Ativa", "Em rotação", "Expirada", "Revogada"; embaixo, em laranja, "Expirou", "Expira hoje" ou "Expira em N dias") e três ícones. Vazio: "Nenhuma chave ainda. A API pública fica fechada até a primeira ser criada."
Botões
Os botões marcados nas figuras estão explicados junto de cada figura (seção “A tela, marcação por marcação”). A seguir, os demais botões desta tela — os que só aparecem em outras situações —, com o que fazem e onde ficam.
"Ver uso" (ícone de gráfico de barras, na linha)
- Abre a janela "Uso de <nome>".
"Rotacionar (a antiga vale por mais 24 h)" (setas circulares)
- Aparece ativo quando: a chave não está revogada.
- Pede confirmação? Sim — "Rotacionar a chave de API": "Uma chave nova é gerada para <nome>. A atual ainda vale por mais 24 horas e depois para de funcionar: troque-a no sistema que a usa dentro desse prazo." Botão "Rotacionar".
- O que faz: gera a chave nova e mostra a janela "Sua chave de API" (única vez). A situação passa a "Em rotação" até a antiga expirar.
- Se der errado: "Uma chave revogada não se rotaciona: crie uma chave nova." · "Chave de API não encontrada."
"Revogar agora" (lixeira vermelha)
- Aparece ativo quando: a chave não está revogada. Abre a janela "Revogar chave".
Janelas
"Nova chave de API"

Fecha a janela sem gravar nada; a tela de trás continua como estava.
- Botões: "Cancelar" · "Criar chave".
- Campos:
- "Nome" — "Quem usa esta chave. É o que vai aparecer na trilha." (ex.: "Painel do gabinete"); mínimo 3 caracteres ("Diga quem vai usar esta chave.").
- "Escopos" — "Marque só o que a integração precisa. Ler e escrever são escopos separados de propósito: uma chave de escrita não lê o acervo." Caixas: "assets:read — Listar e consultar bens, com os campos do contrato público." · "assets:write — Criar bens em rascunho e alterar os campos permitidos pela API." · "movements:read — Consultar transferências, empréstimos e devoluções concluídas." · "inventory:read — Consultar campanhas de inventário e suas divergências." · "reports:run — Disparar relatórios e baixar o resultado por link assinado." · "org-units:read — Consultar unidades, departamentos e locais." · "webhooks:manage — Criar e alterar endpoints de webhook pela própria API." Ao menos um ("Escolha ao menos um escopo.").
- "Faixas de rede permitidas" — "Vazio aceita de qualquer lugar. Uma chave presa à rede da instituição vale muito menos quando vaza." (ex.: "200.1.2.0/24"; Enter para cada faixa).
- "Limite por minuto" — 1 a 600 (padrão 120).
- "Expira em" — data; "Opcional. Chave sem prazo vive para sempre." (vale até 23h59 do dia).
- Botões: "Cancelar" · "Criar chave".
- Efeito: abre a janela "Sua chave de API".
- Mensagens do servidor: "A instituição já tem 20 chaves ativas." / "Revogue uma chave que não está mais em uso antes de criar outra…" · "O limite por minuto vai de 1 a 600." · faixa de rede inválida.
"Sua chave de API" (mostrada uma vez)
- Mostra: aviso laranja "Copie agora. Este valor não será exibido novamente — o sistema guarda apenas uma marca que permite conferi-lo, nunca o valor em si.", a instrução "Envie no cabeçalho X-Api-Key de cada chamada à API pública." e a chave completa.
- Botões: "Copiar" (vira "Copiado" por 4 segundos) · "Já guardei, pode fechar". A janela não fecha clicando fora nem com Esc.
"Revogar chave"
- Mostra: aviso vermelho "A chave pqp_…… para de valer imediatamente. Quem estiver usando vai receber 401 na próxima chamada. Não há como desfazer: para voltar, crie uma chave nova."
- Campo: "Por quê?" — "Mínimo de 20 caracteres. Esta explicação fica na trilha de auditoria."
- Botões: "Cancelar" · "Revogar" (vermelho; apagado com texto curto). Balão "Chave revogada. Ela para de valer agora."
"Uso de <nome>"
- Mostra: "Chamadas em 30 dias", "Com erro" (laranja se houver), um gráfico de barras por dia (passar o mouse mostra "<dia>: N chamadas"; barras laranja em dias com erro) — ou "Esta chave ainda não foi usada." — e "Último uso" (data · endereço de rede, ou "Nunca"). Fecha pelo "x".
Perguntas que as pessoas fazem
- Perdi a chave. → Ela não pode ser exibida de novo; use "Rotacionar" (gera outra; a antiga vale mais 24 h) ou crie uma nova.
- O sistema externo recebe 401. → A chave foi revogada, expirou, ou a chamada vem de uma rede fora das "Faixas de rede permitidas".
- Cliquei em "Nova chave" e deu "sem permissão". → Criar exige
api-key.manage; ver a lista exige sóintegration.read. - Para que serve o limite por minuto? → Acima dele, as chamadas daquela chave são recusadas até o minuto seguinte.
Ligações com outros módulos e telas
- Integrações › Webhooks — avisos que o Patrimônio envia para fora.
- Configurações (índice) — índice.
- Notas fiscais do ERP (nota fiscal vira bem) — a integração interna com o ERP não usa chave de API.