Conectar outros sistemas

O acervo digital fica ainda mais útil quando os outros sistemas da prefeitura conversam com ele. O sistema tributário pode mostrar a planta do imóvel ao lado da inscrição imobiliária; o protocolo pode anexar um processo digitalizado; o portal da transparência pode publicar contratos autenticados.

Cada sistema conectado é uma integração. Você cria a integração, decide o que o sistema pode fazer e o que ele enxerga, entrega a chave de acesso (o token) para a equipe técnica do sistema e pode cortar o acesso a qualquer momento.

Esta página é para o administrador da prefeitura e não exige conhecimento de programação. A equipe técnica do sistema encontra o que precisa em Início rápido da API.

Antes de criar#

Converse com o responsável pelo sistema e responda três perguntas:

1. O que o sistema precisa fazer? Só consultar? Buscar? Baixar arquivos? Cadastrar documentos?
2. Quais documentos ele precisa ver? Só os do setor de Tributação? Só a classe de processos de licitação?
3. De onde ele vai acessar? Se o sistema roda num servidor com endereço IP fixo, vale restringir.

A regra de ouro é a do mínimo necessário: dê ao sistema só o que ele precisa. É mais seguro e atende à LGPD.

Criar uma integração#

Abra Organização > Integrações no menu lateral e clique em Nova integração.

Sistema#

• Nome: como o sistema é conhecido na prefeitura, por exemplo "Sistema tributário".
• Ativa: deixe ligado. Desligado, o sistema fica sem acesso, mas a integração continua configurada (útil para pausar temporariamente).
• Descrição: para que serve, quem é o fornecedor, quem é o contato técnico.

O que o sistema pode fazer#

Marque os Escopos, que são as permissões do sistema:

Escopo	Para que serve
Ler documentos e metadados	Consultar um documento e a ficha dele
Buscar no acervo (metadados e OCR)	Pesquisar por texto, como na busca do painel
Consultar por campo (ex.: inscrição imobiliária)	Achar documentos pelo valor de um campo da ficha
Baixar arquivos (assinado ou mestre)	Baixar o PDF autenticado ou, se ainda não houver, o mestre de preservação
Cadastrar documentos e enviar arquivos	Incluir documentos novos no acervo
Receber avisos (webhooks)	Ser avisado quando um documento muda (veja abaixo)
Ver campos sensíveis (CPF, nomes)	Sem este escopo, CPF, nomes e outros campos sensíveis chegam como "•••"

O que o sistema enxerga#

Este é o recorte: os documentos que o sistema alcança. Escolha um ou os dois:

• Setores: o sistema vê os documentos dos setores escolhidos.
• Classes do plano: o sistema vê os documentos das classes escolhidas, de qualquer setor. Ao escolher uma classe, as subclasses dela entram junto.

Documentos públicos e restritos do recorte ficam visíveis. Documentos sigilosos ficam de fora, a menos que você ligue Incluir documentos sigilosos. Faça isso só com autorização expressa de quem responde pelo sigilo.

Segurança e limites#

• Requisições por minuto: quantas chamadas o sistema pode fazer por minuto. Em branco, vale o padrão da plataforma, que aparece no próprio campo; o teto está indicado logo abaixo. Acima do limite, as chamadas são recusadas por alguns instantes, sem afetar os outros sistemas.
• IPs liberados: um endereço por linha, como 200.150.10.20, ou uma faixa, como 200.150.10.0/24. Em branco, qualquer endereço é aceito. Se o sistema roda num servidor com IP fixo, preencha: um token vazado não serve de nada fora daquele endereço.

Avisos (webhooks)#

Os avisos servem para o sistema saber, sem ficar perguntando o tempo todo, que algo mudou no acervo. Preencha só se a equipe técnica pedir:

• Endereço (HTTPS): o endereço que vai receber os avisos, informado pela equipe técnica. Precisa começar com https:// e não pode apontar para a rede interna.
• Eventos: Documento cadastrado, Documento alterado e Documento autenticado.

Os avisos só são enviados se o escopo Receber avisos (webhooks) estiver marcado, e só sobre documentos do recorte. O aviso leva apenas a identificação do documento; o sistema consulta os detalhes depois, com as permissões que tem.

Clique em Criar para terminar.

O token e o segredo: copie na hora#

Logo depois de criar, a página da integração mostra um quadro Copie agora: com:

• o Token, a chave de acesso do sistema;
• o Segredo do webhook, se você preencheu o endereço dos avisos. Ele permite ao sistema conferir que o aviso veio mesmo do GedFlow.

Acompanhar o uso#

Na lista de integrações, a coluna Último uso mostra quando cada sistema chamou o acervo pela última vez. Dentro da integração, duas abas ajudam a investigar:

• Chamadas: as chamadas do sistema, com Quando, Método, Rota, Situação (o código de resposta), Duração e IP. Situação em verde é sucesso; em vermelho, erro (acesso negado, documento fora do recorte, pedido inválido); em amarelo, o código 429, que indica limite por minuto estourado. O conteúdo das chamadas não é guardado, e o histórico fica disponível por 90 dias.
• Webhooks: cada aviso enviado, com o Evento, a Situação (Tentando, Entregue ou Falhou), as Tentativas, a Resposta do sistema, o Último erro e a Próxima tentativa.

Se o sistema estiver fora do ar, o GedFlow tenta entregar o aviso de novo, com intervalos crescentes (de 1 minuto até 6 horas). Para mandar de novo um aviso entregue ou que falhou, clique em Reenviar na linha dele.

Alterar, trocar o token e revogar#

Na página da integração:

• Editar: muda escopos, recorte, limites e avisos. As mudanças valem na hora, com o mesmo token.
• Gerar novo token: cria um token novo e o anterior para de funcionar imediatamente. Use quando o token vazou, quando o fornecedor do sistema mudou ou por rotina de segurança. Combine o momento com a equipe técnica, porque o sistema precisa ser atualizado com o novo token.
• Gerar novo segredo do webhook: aparece quando há endereço de avisos. Cria um novo segredo, que também é mostrado uma única vez.
• Revogar: o sistema perde o acesso imediatamente e de forma definitiva. A integração não pode mais ser editada, mas o histórico de chamadas e avisos continua guardado.

Para uma pausa (manutenção do sistema, contrato suspenso), desligue Ativa em Editar em vez de revogar: depois é só religar, sem trocar o token.

Tudo fica registrado#

O que o sistema faz pelo acervo fica na Trilha de auditoria, em nome de um usuário técnico chamado "Integração: " seguido do nome da integração. Criar, trocar o token, trocar o segredo e revogar também ficam registrados, com o nome de quem fez.

A empresa que opera o GedFlow acompanha o volume de chamadas de todas as integrações para manter a plataforma estável, mas quem cria, configura e revoga é sempre a prefeitura.

Para a equipe técnica: Início rápido, Escopos e recorte, Limites e Webhooks. O botão Documentação da API, na lista de integrações, abre a referência técnica completa.