Nexus Atlas

Patrimônio

Integrações › Chaves de API

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…

Onde encontrar/patrimonio/integracoes/chaves · "Configurações" → cartão "Chaves de API"
Quem abrequem tem 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

1Nova chave
Figura 1 — Integrações › Chaves de API
O que cada marcação faz
1
Nova chave
  • Abre a janela "Nova chave de API".

Como a tela está organizada (de cima para baixo)

  1. 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").
  2. Três números: "Chaves em uso" · "Nunca usadas" ("Chave que ninguém usa é porta aberta sem vigia.") · "Expirando em 30 dias".
  3. 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"

1Cancelar2Criar chave
Figura 2 — janela "Nova chave de API": abre por "Nova chave"
O que cada marcação faz
1
Cancelar

Fecha a janela sem gravar nada; a tela de trás continua como estava.

2
Criar chave
  • 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

Nexus Atlas · As imagens mostram o sistema com dados fictícios.