# GovMachine — API de Editais (referência para desenvolvedores)

> API pública, somente-leitura, para os seus próprios sistemas (ERP, BI, CRM)
> consultarem os editais que a sua empresa acompanha na GovMachine: em triagem,
> em análise, em precificação, prontos, descartados ou expirados. Autenticação
> por chave de API por empresa. Escopo de dados isolado por empresa via
> Row-Level Security.

- **Base URL:** `https://app.govmachine.com.br`
- **Formato:** JSON
- **Autenticação:** chave de API por empresa (prefixo `gmk_`)
- **Especificação OpenAPI 3.1:** https://govmachine.com.br/openapi-editais.yaml
- **Página de documentação:** https://govmachine.com.br/developers

## Autenticação

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

```
Authorization: Bearer gmk_sua_chave_aqui
```

ou

```
X-API-Key: gmk_sua_chave_aqui
```

### Como gerar uma chave

Um administrador da empresa gera e revoga chaves no app, em **Configurações → API de Editais**. A chave completa é exibida **uma única vez** no momento da criação — copie e guarde em local seguro. Depois disso, apenas o prefixo fica visível. Membros com perfil somente-leitura conseguem listar chaves, mas não criar nem revogar.

A chave resolve para uma única empresa. O isolamento é garantido no banco por Row-Level Security: uma chave nunca enxerga dados de outra empresa. A API é **somente-leitura** — não há endpoints de escrita.

## Endpoints

### GET /api/v1/editais — lista os editais da empresa

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

**Parâmetros de query**

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

**Exemplo**

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

**Resposta 200**

```json
{
  "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).

### GET /api/v1/editais/{id} — detalha um edital

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

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

### GET /api/v1/editais/{id}/analysis — análise estruturada

Retorna a camada estruturada que a GovMachine **já extraiu e avaliou** do edital — pensada para o seu ERP/BI e para **agentes de IA** consumirem, em vez de reprocessar o PDF do edital. É o trabalho que já fazemos bem, entregue pronto para máquina.

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

Estrutura da resposta:

| Campo | Descrição |
|---|---|
| `analysis_level` | Profundidade já executada: `none` / `simple` / `medium` / `deep`. Seções vazias são honestas — um edital só em triagem ainda não tem requisitos/itens projetados. |
| `analyzed` | `false` quando `analysis_level = none`. |
| `verdict` | `{ recommendation (participar\|cautela\|nao_recomendado), reason, summary, bullets[] }`. |
| `overview` | Panorama estruturado (nível simple): identidade, valor, lei aplicável, prazos, logística, participação (`is_srp`, `exclusivo_me_epp`, `restricoes_participacao`, `atestado_capacidade_exigido`, `visita_tecnica_obrigatoria`), lotes. |
| `requirements[]` | Requisitos de habilitação exigidos: `{ category, title, required, current, status (red\|yellow\|green), ai_notes, metadata }`. `metadata` traz o detalhe (CCT, pisos salariais, entrega, gatilho de Programa de Integridade…). |
| `items[]` | Itens e lotes: `{ numero_item, descricao, quantidade, unidade_medida, valor_unitario_estimado, valor_total, material_ou_servico (M\|S), numero_lote, criterio_julgamento_nome, ai_selected, ai_reasoning, ai_confidence }`. |
| `alerts[]` | Alertas de risco jurídico (somente publicados): `{ type (risk\|opportunity\|info), severity, title, description, action_type (impugnacao\|esclarecimento\|recurso\|contrarrazao\|none), legal_thesis }`. |
| `pricing` | `{ investimento_total, garantia_proposta, garantia_contratual, margem_min, margem_max, risco_pagamento, is_srp, sigiloso }` — ou `null` até rodar avaliação medium. |
| `orgao_report` | `{ payment_risk, status }` — confiabilidade de pagamento do órgão (transparência pública). |
| `operational` | Logística de entrega/execução (prazo, faseamento, locais). |

**Proveniência:** esses dados vêm da avaliação da GovMachine sobre o edital (extração do PDF via OCR + LLM, aritmética de prazos por lei, projeção War Room). A avaliação é acionada quando a empresa faz a triagem/análise do edital — então `analysis_level` reflete quão fundo a análise já foi. É a mesma camada que a equipe vê no app.

## O objeto Edital

| Campo | Tipo | Sempre presente | 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 (ver tabela abaixo). |
| `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 por esta API — só o que os seus sistemas precisam para acompanhar um edital da triagem ao resultado.

## Status do ciclo de vida

| Status | Significado |
|---|---|
| `screening` | Em triagem — descoberto e sendo avaliado quanto à relevância. |
| `analysis` | Em análise — passou na triagem, sob avaliação detalhada. |
| `pricing` | Em precificação — montando a proposta de preço. |
| `ready` | Pronto — preparado para participar. |
| `discarded` | Descartado — ver `discard_reason`. |
| `expired` | Expirado — a janela do edital passou. |

## Erros

| Código | Quando |
|---|---|
| `400` | `status` inválido no filtro (`{"error":"invalid_status","detail":"unknown status: ..."}`). |
| `401` | Chave ausente ou inválida. |
| `404` | Edital não encontrado para esta empresa. |
| `500` | Erro 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/revogada** — regenere no app se necessário.
- **A API é somente-leitura.** Para agir sobre um edital (participar, descartar, precificar), use o app ou o agente da GovMachine.
- **Guarde a chave em segredo** e prefira uma chave por sistema integrador (a descrição ajuda a rastrear o uso).