Escopos e recorte

Uma integração tem duas camadas de permissão, e as duas precisam deixar passar:

• Escopos dizem o que o sistema pode fazer (ler, buscar, baixar, cadastrar...).
• Recorte diz sobre quais documentos ele pode fazer (setores e classes do plano de classificação).

Um sistema tributário, por exemplo, pode ter os escopos de leitura e consulta por campo, com recorte só no setor de Cadastro Imobiliário. Ele consegue achar o processo pela inscrição imobiliária, mas nunca vai ver um prontuário da Saúde.

Os dois são definidos pelo administrador da prefeitura. Veja Integrações com outros sistemas.

Os escopos#

Escopo	Nome na tela	O que libera
documents:read	Ler documentos e metadados	GET /documents, GET /documents/{id}, GET /document-types, GET /sectors, GET /fields
search	Buscar no acervo (metadados e OCR)	GET /search
lookup	Consultar por campo (ex.: inscrição imobiliária)	GET /lookup
download	Baixar arquivos (assinado ou mestre)	GET /documents/{id}/files/{file}/download
documents:write	Cadastrar documentos e enviar arquivos	POST /documents, POST /documents/{id}/files e o envio em partes (/files/{file}/uploads, /uploads/{version}/...)
webhooks	Receber avisos (webhooks)	Recebimento dos eventos de documento no endereço cadastrado
sensitive	Ver campos sensíveis (CPF, nomes)	Valores reais dos campos sensíveis nas respostas e consulta por campo sensível

GET /me e os endpoints de autenticação não exigem escopo.

Sem o escopo, a resposta é 403:

{ "message": "A integração não tem o escopo \"download\"." }

Alguns detalhes que fazem diferença#

• Busca e consulta por campo são escopos separados da leitura. A busca procura no texto de OCR das páginas; a consulta por campo procura um valor exato em um campo da ficha (ex.: inscricao = 01.02.003).
• Download entrega o PDF autenticado (o que tem valor legal) quando existe. Se o documento ainda não foi autenticado, entrega o mestre de preservação. O campo authenticated da resposta diz qual dos dois veio.
• Cadastro cria o documento já no setor indicado e permite enviar arquivos depois. Novas versões de um arquivo exigem o campo reason (motivo), porque a versão anterior continua preservada.

O recorte#

O recorte é a lista de setores e de classes do plano de classificação que a integração enxerga.

Como o documento entra no recorte	Público	Restrito	Sigiloso
O setor do documento está no recorte	sim	sim	só com Incluir documentos sigilosos
A classe do documento (ou uma classe acima dela) está no recorte	sim	sim	só com Incluir documentos sigilosos

• Escolher uma classe vale também para todas as subclasses dela. Escolher 005.02 inclui 005.02.01, 005.02.01.03 e assim por diante.
• Integração sem nenhum setor e sem nenhuma classe não enxerga nada.
• Fora do recorte, o documento simplesmente não existe para a integração: não aparece em listas nem em buscas, e o detalhe responde 404 (e não 403), para não revelar que ele existe.

O que exige o setor (e não basta a classe)#

Algumas ações mexem no documento ou entregam o arquivo original, e por isso exigem que o setor do documento esteja no recorte. A classe dá acesso de leitura, mas não estas ações:

Ação	Precisa
Cadastrar documento (POST /documents)	O setor informado no corpo dentro do recorte. Fora dele: 403 "Setor fora do seu acesso."
Acrescentar arquivo e enviar versões	Setor do documento no recorte
Baixar o arquivo	Setor do documento no recorte, além do escopo download

Catálogo#

GET /sectors e GET /document-types listam o catálogo da prefeitura inteira (só nomes e identificadores), para o seu sistema saber os códigos válidos. Estar no catálogo não significa estar no recorte.

Campos sensíveis#

A prefeitura marca alguns campos da ficha como sensíveis: CPF de requerente, nome de paciente, nome de servidor. Sem o escopo sensitive, o valor desses campos vem mascarado:

"custom_fields": {
  "inscricao": "01.02.003",
  "cpf_requerente": "•••"
}

Com o escopo sensitive, vem o valor gravado. Campos de CPF e CNPJ são gravados só com os dígitos:

"custom_fields": {
  "inscricao": "01.02.003",
  "cpf_requerente": "52998224725"
}

Outras regras:

• O texto de máscara é sempre ••• (três pontos médios, U+2022). Trate-o como "valor oculto", nunca grave por cima de um valor real do seu lado.
• Consulta por campo sensível (GET /lookup?field=cpf_requerente&value=...) exige o escopo sensitive. Sem ele: 403 "Consulta por campo sensível exige o escopo "sensitive"."
• Em GET /fields, cada campo traz sensitive (se é sensível) e visible (se a sua integração vê o valor).
• Nos campos de CPF e CNPJ, a consulta por campo aceita o valor com ou sem pontuação: 529.982.247-25 e 52998224725 dão o mesmo resultado.

Documentos sigilosos#

Documentos com sigilo sigiloso ("confidentiality": "confidential") ficam de fora de qualquer integração, mesmo dentro do recorte, a menos que o administrador marque Incluir documentos sigilosos. Essa opção exige autorização expressa da prefeitura.

Os níveis de sigilo que aparecem no campo confidentiality:

Valor	Na tela
public	Público
restricted	Restrito
confidential	Sigiloso

Auditoria#

Tudo o que a integração faz fica registrado na trilha de auditoria da prefeitura, em nome dela: abertura de documento, busca, consulta por campo, download, cadastro e envio. A prefeitura também vê o histórico de chamadas (rota, situação, duração e IP, sem o conteúdo) na página da integração.