Desenvolvedores

API de Editais

Conecte seu ERP, BI ou CRM à GovMachine. Uma API pública, somente-leitura, para consultar os editais que a sua empresa acompanha — em triagem, análise, precificação, prontos, descartados ou expirados — e o status de cada um.

OpenAPI 3.1 Versão Markdown

Feito para agentes de IA. GET /api/v1/editais/{id}/analysis entrega a análise do edital já estruturada — requisitos, itens, alertas jurídicos e veredito — para o seu agente consumir sem reprocessar o PDF. Servidor MCP no roadmap.

Visão geral

A API é servida em https://app.govmachine.com.br, o mesmo host onde você acessa o app. Todas as respostas são JSON. O escopo de dados vem inteiramente da chave de API: cada chave resolve para uma única empresa, e o isolamento é garantido no banco por Row-Level Security.

Somente-leitura

Nenhum endpoint de escrita.

Chave por empresa

Prefixo gmk_, gerada no app.

Isolamento por RLS

Nunca vê outra empresa.

Autenticação

Toda requisição precisa de uma chave de API da sua empresa. Envie-a em um dos dois cabeçalhos:

Opção 1 — Bearer

Authorization: Bearer gmk_sua_chave_aqui

Opção 2 — X-API-Key

X-API-Key: gmk_sua_chave_aqui

Como gerar uma chave

Um administrador gera e revoga chaves no app, em Configurações → API de Editais. A chave completa aparece uma única vez na criação — copie e guarde em local seguro; depois só o prefixo fica visível. Membros somente-leitura conseguem listar chaves, mas não criar nem revogar.

Listar editais

GET/api/v1/editais

Retorna os editais da empresa, do mais recente para o mais antigo, com paginação.

Parâmetros de query

Param	Padrão	Descrição
status	(todos)	Filtro por status, separado por vírgula (ex.: `analysis,pricing`). Status desconhecido → 400.
limit	50	Tamanho da página. Máximo 200.
offset	0	Deslocamento para paginação.

Requisição

curl -H "Authorization: Bearer gmk_sua_chave_aqui" \
  "https://app.govmachine.com.br/api/v1/editais?status=analysis,pricing&limit=50"

Resposta 200

{
  "editais": [
    {
      "id": "a1b2c3d4-...",
      "pncp_id": "25944455000196-2025-193",
      "orgao": "Prefeitura Municipal de Exemplo",
      "objeto": "Aquisição de material de escritório",
      "numero": "PE 193/2025",
      "modalidade": "Pregão Eletrônico",
      "uf": "SP",
      "valor_estimado": 150000.0,
      "data_sessao": "2026-08-15T09:00:00Z",
      "pncp_url": "https://pncp.gov.br/app/editais/...",
      "status": "analysis",
      "participation_confirmed": true,
      "committed_at": "2026-07-01T12:00:00Z",
      "created_at": "2026-06-28T08:00:00Z",
      "updated_at": "2026-07-05T14:30:00Z"
    }
  ],
  "count": 1,
  "total": 42,
  "limit": 50,
  "offset": 0
}

count é o tamanho desta página; total é o total de editais que casam com o filtro — use para paginar.

Detalhar um edital

GET/api/v1/editais/{id}

Retorna um único objeto Edital. Um id desconhecido para a empresa retorna 404 — por RLS, um id de outra empresa é indistinguível de inexistente.

Requisição

curl -H "X-API-Key: gmk_sua_chave_aqui" \
  "https://app.govmachine.com.br/api/v1/editais/a1b2c3d4-..."

Análise estruturada

GET/api/v1/editais/{id}/analysis

A camada que a GovMachine já extraiu e avaliou do edital — requisitos de habilitação, itens e lotes, alertas de risco jurídico com tese legal, investimento/garantias e o veredito de participação. Feita para o seu ERP/BI e para agentes de IA consumirem pronto, em vez de reprocessar o PDF do edital.

Campo	Descrição
analysis_level	Profundidade já executada: none / simple / medium / deep. Seções vazias são honestas.
analyzed	false quando analysis_level = none.
verdict	recommendation (participar / cautela / nao_recomendado), reason, summary, bullets[].
overview	Panorama estruturado (nível simple): identidade, valor, lei, prazos, logística, participação, lotes.
requirements[]	Requisitos de habilitação exigidos: category, title, required, current, status (red/yellow/green), ai_notes, metadata.
items[]	Itens e lotes: numero_item, descricao, quantidade, valor_*, material_ou_servico, numero_lote, criterio_julgamento_nome, ai_selected, ai_reasoning, ai_confidence.
alerts[]	Alertas de risco jurídico (publicados): type, severity, title, description, action_type, legal_thesis.
pricing	investimento_total, garantia_proposta, garantia_contratual, margem_min/max, risco_pagamento, is_srp, sigiloso. null até rodar medium.
orgao_report	Confiabilidade de pagamento do órgão: payment_risk, status.
operational	Logística de entrega/execução: prazo, faseamento, locais.

Requisição

curl -H "Authorization: Bearer gmk_sua_chave_aqui" \
  "https://app.govmachine.com.br/api/v1/editais/a1b2c3d4-.../analysis"

Resposta 200 (resumida)

{
  "id": "a1b2c3d4-...",
  "pncp_id": "25944455000196-2025-193",
  "status": "analysis",
  "analysis_level": "medium",
  "analyzed": true,
  "verdict": {
    "recommendation": "participar",
    "reason": "valor dentro da faixa da empresa",
    "summary": "Pregão eletrônico — material de escritório",
    "bullets": ["prazo de impugnação em 3 dias úteis"]
  },
  "overview": {
    "lei_aplicavel": "Lei 14.133/2021",
    "is_srp": true,
    "exclusivo_me_epp": false,
    "prazo_impugnacao": "3 dias úteis antes da sessão"
  },
  "requirements": [
    {
      "category": "qualificacao_tecnica",
      "title": "Atestado de capacidade técnica",
      "required": "1 atestado compatível",
      "status": "yellow"
    }
  ],
  "items": [
    {
      "numero_item": 1,
      "descricao": "Resma de papel A4",
      "quantidade": 100,
      "valor_unitario_estimado": 25.0,
      "valor_total": 2500.0,
      "criterio_julgamento_nome": "Menor preço",
      "ai_selected": true
    }
  ],
  "alerts": [
    {
      "type": "risk",
      "severity": "high",
      "title": "Cláusula restritiva à competição",
      "action_type": "impugnacao",
      "legal_thesis": "art. 3º, §1º, Lei 14.133/2021"
    }
  ],
  "pricing": {
    "investimento_total": 5000.0,
    "garantia_proposta": 1000.0,
    "risco_pagamento": "baixo"
  }
}

Proveniência (para agentes)

Esses dados vêm da avaliação da GovMachine sobre o edital — extração do PDF (OCR + LLM), aritmética de prazos pela lei aplicável e a projeção estruturada que a equipe vê no app. O campo analysis_level diz quão fundo a análise já foi; seções vazias são honestas, não um erro. Um agente pode confiar nessa camada em vez de reextrair o edital.

O objeto Edital

Campo	Tipo	Sempre	Descrição
id	string	sim	ID do edital para esta empresa. Use em GET /api/v1/editais/{id}.
pncp_id	string	sim	Identificador PNCP (cnpj-ano-sequencial).
orgao	string	não	Órgão comprador.
objeto	string	não	Objeto da contratação.
numero	string	não	Número do edital/processo.
modalidade	string	não	Modalidade (ex.: Pregão Eletrônico).
uf	string	não	UF do órgão.
valor_estimado	number	não	Valor estimado (BRL).
data_sessao	datetime	não	Data da sessão pública.
pncp_url	string	não	Link para o edital no portal de origem.
status	string	sim	Fase da empresa neste edital.
participation_confirmed	boolean	sim	Se a empresa confirmou participação.
discard_reason	string	não	Motivo do descarte (quando status = discarded).
committed_at	datetime	não	Quando a participação foi confirmada.
created_at	datetime	sim	Criação do vínculo empresa-edital.
updated_at	datetime	sim	Última atualização.

Campos internos da GovMachine (análise de IA, classificação, estágio de pipeline) não são expostos — só o que os seus sistemas precisam para acompanhar um edital da triagem ao resultado.

Status do ciclo de vida

screeningEm triagem — descoberto e sendo avaliado quanto à relevância.

analysisEm análise — passou na triagem, sob avaliação detalhada.

pricingEm precificação — montando a proposta de preço.

readyPronto — preparado para participar.

discardedDescartado — ver discard_reason.

expiredExpirado — a janela do edital passou.

Erros

400status inválido no filtro ({"error":"invalid_status","detail":"unknown status: ..."}).

401Chave ausente ou inválida.

404Edital não encontrado para esta empresa.

500Erro interno.

Boas práticas

Pagine com limit/offset usando total como referência; não assuma que a primeira página traz tudo.
Trate 401 como chave inválida ou revogada — regenere no app se necessário.
Uma chave por sistema integrador — a descrição ajuda a rastrear o uso e revogar sem afetar as outras.
Guarde a chave em segredo. Ela dá acesso de leitura a todos os editais da empresa.

Recursos

OpenAPI 3.1 (YAML)

Esquema legível por máquina.

Referência em Markdown

A mesma doc em texto puro (LLM-friendly).

Perguntas frequentes

A API é somente-leitura?

Sim. Os endpoints públicos apenas consultam os editais da sua empresa e o status de cada um. Não há endpoints de escrita — para agir sobre um edital (participar, descartar, precificar), use o app ou o agente da GovMachine.

Como consigo uma chave de API?

Um administrador da empresa gera e revoga chaves no app, em Configurações → API de Editais. A chave completa é exibida uma única vez na criação; depois só o prefixo fica visível.

Uma chave pode ver editais de outra empresa?

Não. Cada chave resolve para uma única empresa, e o isolamento é garantido no banco por Row-Level Security. Um id de edital de outra empresa retorna 404, indistinguível de inexistente.

Qual é a URL base da API?

A API é servida em https://app.govmachine.com.br — o mesmo host onde você acessa o app. Os endpoints ficam sob /api/v1/editais.

Meu agente de IA (Claude, Cursor…) pode usar isso?

Sim. Hoje o agente consome a API REST com a chave da empresa — GET /api/v1/editais/{id}/analysis devolve a camada estruturada pronta para máquina (requisitos, itens, alertas, veredito). Um servidor MCP, para o agente conectar e chamar essas rotas como ferramentas nativas, está no roadmap como próximo passo.

Por que consumir a análise em vez de extrair o edital eu mesmo?

Transformar um edital em fatos estruturados confiáveis (itens, requisitos de habilitação, prazos por lei, riscos jurídicos com tese) é caro e propenso a erro. A GovMachine já faz isso e valida. A API entrega essa camada pronta, com proveniência (analysis_level indica a profundidade da análise).