Referência da API

Esta página é o mapa rápido da API v1. Para ver cada parâmetro, os formatos de resposta e testar as chamadas no navegador, use a referência interativa em /docs/api. Ela é gerada a partir do próprio código e está sempre em dia com a versão no ar. A especificação OpenAPI fica em /docs/api.json, pronta para importar no Postman, Insomnia ou no gerador de cliente da sua preferência.

Todos os caminhos abaixo são relativos a https://gedflow.com.br/api/v1. A coluna Limite indica as rotas pesadas, que têm limite próprio menor (veja Limites de uso).

Autenticação e conta#

Método	Caminho	Escopo	Limite	O que faz
POST	/auth/login	(sem token)	login	Login dos aplicativos: devolve um token para o aparelho.
POST	/auth/logout	(aplicativos)	normal	Revoga o token do aparelho atual. Integrações recebem 403.
GET	/me	nenhum	normal	Quem é o cliente: usuário, prefeitura e, para integrações, nome e escopos.

Detalhes em Autenticação.

Documentos#

Método	Caminho	Escopo	Limite	O que faz
GET	/documents	documents:read	normal	Lista paginada dos documentos visíveis, com filtros.
GET	/documents/{document}	documents:read	normal	Detalhe: metadados, ficha, arquivos com hashes e autenticação vigente. Fica na auditoria.
POST	/documents	documents:write	pesada	Cadastra um documento em um setor do recorte.

Filtros de GET /documents (todos opcionais):

Parâmetro	Exemplo	Efeito
document_type	01J9ZC4A1B2C3D4E5F6G7H8J9K	Só deste tipo documental (identificador de /document-types).
sector	01J9ZC2X9Y8W7V6U5T4S3R2Q1P	Só deste setor (identificador de /sectors).
category_code	005.02	Só desta classe do plano, incluindo as subclasses.
status	authenticated	Só nesta situação (veja a tabela abaixo).
updated_since	2026-09-01T00:00:00Z	Só os alterados a partir desta data e hora.
per_page	100	Itens por página: padrão 20, máximo 100.
page	2	Página desejada.

A lista vem ordenada da alteração mais recente para a mais antiga. Na lista, cada documento vem sem files e sem authentication; esses dois só aparecem no detalhe.

Corpo de POST /documents:

Campo	Obrigatório	Descrição
sector	sim	Identificador do setor (precisa estar no recorte).
document_type	sim	Identificador do tipo documental.
title	sim	Título (até 255 caracteres).
subject	não	Assunto ou palavras-chave (até 2.000 caracteres).
author	não	Quem produziu o documento original.
produced_at	não	Data de produção, AAAA-MM-DD.
produced_place	não	Local de produção.
confidentiality	não	public, restricted ou confidential.
custom_fields	não	Objeto com os campos da ficha, pela chave (veja GET /fields).

curl https://gedflow.com.br/api/v1/documents \
  -H "Authorization: Bearer $GEDFLOW_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "sector": "01J9ZC2X9Y8W7V6U5T4S3R2Q1P",
    "document_type": "01J9ZC4A1B2C3D4E5F6G7H8J9K",
    "title": "Requerimento de certidão de valor venal",
    "produced_at": "2026-09-28",
    "custom_fields": { "inscricao": "01.02.003" }
  }'

Resposta 201 com o documento dentro de data.

Busca e consulta por campo#

Método	Caminho	Escopo	Limite	O que faz
GET	/search?q=...	search	pesada	Busca em texto livre nos metadados e no OCR. Aspas para frase exata. q até 300 caracteres; per_page e page opcionais.
GET	/lookup?field=...&value=...	lookup	pesada	Documentos com o valor exato em um campo da ficha (ex.: field=inscricao&value=01.02.003). Até 100 resultados. Campo sensível exige também sensitive.

Campo inexistente ou inativo na ficha da prefeitura: 422 "Campo inexistente na ficha desta prefeitura."

Catálogo#

Método	Caminho	Escopo	Limite	O que faz
GET	/document-types	documents:read	normal	Tipos documentais ativos: id, name, classification (código da classe) e default_confidentiality.
GET	/sectors	documents:read	normal	Setores ativos: id e name.
GET	/fields	documents:read	normal	Campos da ficha: key, label, type, options, required, sensitive e visible. Informe sector e document_type para a ficha completa daquela combinação.

Tipos de campo possíveis em type: text, number, date, cpf, cnpj, cpf_cnpj, select, multiselect e boolean.

Arquivos: download#

Método	Caminho	Escopo	Limite	O que faz
GET	/documents/{document}/files/{file}/download	download	pesada	URL pré-assinada, válida por poucos minutos, do PDF autenticado (ou do mestre de preservação, se ainda não houver autenticação). Fica na auditoria.

{
  "url": "https://...",
  "expires_at": "2026-09-30T18:05:00+00:00",
  "authenticated": true,
  "sha256": "3f8a1c...e94b"
}

• Baixe logo: a URL expira em poucos minutos. Peça outra se precisar.
• Confira o SHA-256 do arquivo baixado com o campo sha256.
• 404: o arquivo ainda não tem versão enviada. 409: o arquivo ainda está em processamento.

Arquivos: envio#

O envio de arquivos é feito direto para o armazenamento, em partes, sem passar pelo servidor da API. Funciona para arquivos de qualquer tamanho, inclusive pranchas grandes.

Método	Caminho	Escopo	Limite	O que faz
POST	/documents/{document}/files	documents:write	pesada	Acrescenta um arquivo ao documento. Corpo: kind (body corpo, sheet prancha ou annex anexo) e label opcional. Devolve o id do arquivo.
POST	/files/{file}/uploads	documents:write	pesada	Abre o envio de uma versão. Corpo: filename, mime, size (bytes), sha256 e, a partir da segunda versão, reason. Opcionais: digitized_at, digitization_place. Devolve version, part_size e part_count.
POST	/uploads/{version}/parts	documents:write	pesada	Gera as URLs para enviar as partes. Corpo: parts (lista de números, até 50 por chamada). Devolve urls, um objeto com o número da parte e a URL.
POST	/uploads/{version}/complete	documents:write	pesada	Conclui o envio. Corpo: parts, lista de { "number": 1, "etag": "..." }. Devolve version, number e status.
DELETE	/uploads/{version}	documents:write	pesada	Cancela um envio em andamento.

O roteiro completo:

1. Calcule o SHA-256 do arquivo inteiro.
2. POST /documents/{document}/files (só se o arquivo ainda não existir no documento).
3. POST /files/{file}/uploads com nome, tipo, tamanho e hash. Guarde version, part_size e part_count.
4. POST /uploads/{version}/parts com os números das partes (de 1 a part_count, até 50 por vez).
5. Para cada parte, faça um PUT do pedaço correspondente do arquivo (part_size bytes; a última pode ser menor) na URL recebida, e guarde o cabeçalho ETag da resposta.
6. POST /uploads/{version}/complete com a lista de números e ETags.

Depois da conclusão, o GedFlow reconfere o hash do arquivo gravado e faz o processamento (OCR, PDF/A, derivados). Se o hash não bater, a versão falha: nada é aceito em silêncio.

Situações do documento (status)#

Valor	Na tela
registered	Cadastrado
capturing	Em captura
in_review	Em controle de qualidade
rejected	Rejeitado
approved	Aprovado
delivered	Entregue
validated	Validado
authenticated	Autenticado

Outros valores que aparecem nas respostas#

Campo	Valores
confidentiality	public (Público), restricted (Restrito), confidential (Sigiloso)
produced_at_precision	day (dia exato), month (só mês e ano), year (só o ano)
classification.final_destination	elimination (Eliminação), permanent (Guarda permanente) ou null
files[].kind	body (Corpo), sheet (Prancha), annex (Anexo)
files[].current_version.status	uploading, uploaded, verifying, verified, processing, ready, failed

No detalhe do documento, authentication traz verification_code, verification_url (a página pública de verificação) e authenticated_at, ou null se o documento ainda não foi autenticado. Em cada versão de arquivo, sha256 é o hash do arquivo enviado e master_sha256 o do mestre de preservação gerado a partir dele.

Webhooks#

Os avisos não são endpoints que você chama: são chamadas que o GedFlow faz para o seu sistema. Veja Webhooks.