A API auto-hospedada do promptShield roda a mesma detecção do aplicativo de desktop dentro da sua infraestrutura. Os documentos não saem do seu perímetro. O que sai é uma verificação de licença, a cada 6 horas.
Quem tem o documento durante a detecção
O debate costuma ser nuvem contra local. A pergunta útil é outra: quem tem o documento no instante da detecção. Nesse instante, o texto está legível e inteiro, com nomes, CPF, CNPJ, CEP e dados bancários.
Com uma API na nuvem, quem tem o documento é o fornecedor. Você ganha automação e escala, mas o arquivo atravessa a internet antes de ser protegido. Com um aplicativo de desktop, o documento fica com você, só que ninguém o integra num fluxo de quatro mil contratos por noite.
A API auto-hospedada junta as duas coisas: detecção dentro do seu perímetro, com chamada REST, linha de comando e o balanceador que você já tem. O Presidio, criado na Microsoft e hoje mantido pela comunidade, também roda dentro de casa e é uma alternativa séria. A diferença está no que vem pronto, sobretudo para digitalizações, como explicamos em ferramentas de ocultação feitas para desenvolvedores.
O que a LGPD diz sobre esse trajeto
A lei não proíbe enviar documentos a um fornecedor. Ela define quem responde pelo quê. O controlador (art. 5º, VI) decide sobre o tratamento, e o operador (inciso VII) trata os dados em nome dele. Uma API na nuvem que recebe seus contratos é operador, e o tratamento precisa de uma base legal do art. 7º.
O art. 6º, X exige responsabilização e prestação de contas. O controlador precisa saber para onde os dados foram, quem os teve e por quanto tempo. Cada operador a mais é um contrato a revisar e uma cadeia de suboperadores a acompanhar.
As sanções do art. 52 chegam a 2% do faturamento no Brasil no último exercício, limitadas a R$ 50 milhões por infração. O custo mais frequente aparece antes, no questionário de segurança de um cliente que quer saber onde seus documentos estiveram.
Para advogados, o art. 34, VII da Lei nº 8.906/1994 trata a violação do sigilo como infração disciplinar. O art. 154 do Código Penal tipifica a violação de segredo profissional. Cabe ao jurídico de cada empresa dizer se um fluxo cumpre esses deveres. Rodar a detecção em casa reduz o número de terceiros nessa análise.
A chamada que sai, e com que frequência
Versões anteriores da nossa página de desenvolvedores diziam que a API não dependia de nós. Não era verdade, e um engenheiro que monitora o tráfego de saída veria isso na primeira tarde.
O servidor da API revalida a chave junto ao nosso servidor de licenças a cada seis horas. Se a rede cair, ele continua atendendo com um cache local de no máximo três dias, e depois para. A chamada não leva documento, trecho de texto nem resultado de detecção.
Mesmo assim, coloque essa saída no seu diagrama, com uma regra de firewall e um alerta para falhas de revalidação. Um ambiente totalmente isolado da rede não serve para a API. O desktop tem um modo isolado no plano Pro, sem chamada de licença e sem relatório de falhas, mas é outro mecanismo.
Há ainda uma saída que só existe se você a ligar. A Análise profunda usa um modelo de linguagem e vem desligada por padrão. Se você a apontar para um endpoint remoto de terceiro, o texto das páginas vai para lá.
O que roda dentro do contêiner
Padrões de alta precisão tratam valores de formato fixo, como o CPF no formato 123.456.789-09 ou o CNPJ com 14 dígitos. Um modelo de entidades (spaCy, BERT ou GLiNER, conforme a implantação) procura nomes, empresas e endereços. Um modelo de linguagem opcional vem desligado por padrão.
Os resultados são combinados, deduplicados e filtrados, e um nome achado na página 1 é marcado também na página 4. Nenhum modelo local acha todos os identificadores, por isso a revisão humana faz parte do produto.
Uma página digitalizada é renderizada a 300 dpi e lida pelo Tesseract com o idioma do documento mais o inglês. Os pixels dos dados são cobertos e uma camada de texto pesquisável é refeita por baixo. Há sete pacotes de idioma: inglês, francês, alemão, espanhol, italiano, holandês e português. Com o pacote errado, a leitura sai ruim e sem aviso.
Ocultar remove o conteúdo, em vez de cobrir com uma tarja preta um texto que continua selecionável. A exportação trata também ActualText, texto alternativo, metadados XMP, PieceInfo, destinos nomeados e campos de formulário. Ali vai o código do valor ou um marcador neutro.
Miniaturas anteriores à ocultação são descartadas, porque não há como substituir texto numa imagem. Reverter um código é uma chamada local ao próprio serviço.
No mesmo grupo de documentos, o mesmo valor recebe o mesmo código. Pela API, um documento enviado sozinho forma o próprio grupo. Se o contrato e a correspondência de um caso precisam do mesmo código, envie-os juntos. Só um código fixado manualmente vale em qualquer lugar.
Os primeiros cinco minutos
O pacote ainda não está publicado no PyPI com o nome do produto. A partir de um checkout do repositório, instale com pip install -e .. O comando promptshield serve não inicia sem uma chave na variável PROMPTSHIELD_API_KEY.
Toda requisição leva o cabeçalho Authorization: Bearer com a chave. Só a rota /health responde sem ela. Uma chave com escopo só de detecção recebe 403 nas outras operações, inclusive na exportação do mapa de códigos.
A documentação interativa no navegador responde 401, porque o navegador não anexa o cabeçalho de autorização. Peça o esquema OpenAPI com curl e o mesmo cabeçalho.
Perguntas frequentes
A API manda meus documentos para algum lugar?
Não. Upload, detecção, ocultação e exportação acontecem no servidor que você instalou. Só saem a validação da licença, sem conteúdo de documento, e a Análise profunda, se você a apontar para um endpoint remoto.
Ela roda sem rede nenhuma?
Não. Sem conexão, o servidor usa um cache de licença de no máximo 3 dias e depois para.
O mesmo cliente recebe o mesmo código em todas as chamadas?
Só dentro do mesmo grupo de documentos. Arquivos enviados separadamente recebem códigos diferentes para o mesmo valor.
Por que contar a parte que sai
Temos interesse em que você escolha nossa API. Mas o comprador que mais se importa com isso vai abrir o monitor de tráfego no primeiro dia. Se encontrar uma conexão que não mencionamos, deixa de acreditar que seus documentos não saem.