# EditalMD — referência completa da API > Gerada do catálogo em https://staging.editalmd.com · build `e65e2630` > 98 endpoints · 52 estruturas > Índice curto: https://staging.editalmd.com/llms.txt · Spec: https://staging.editalmd.com/openapi.json · MCP: https://staging.editalmd.com/mcp > Referência completa para pesquisar licitações, acessar documentos e acompanhar mudanças. > Cada comprador paga $0.02 por página pelo próprio acesso, inclusive ao texto pronto, via x402/crédito ou depósito USDC. Geração necessária incluída. Cinco exemplos livres; piloto individual oferece um premium e 100 básicos até 50 páginas com X-Agent-Pass (/api/avaliacao, guia /avaliacao.md), sujeito a validade, capacidade e orçamento. Básico não revisado; premium não equivale a aprovação de fidelidade. Conta opcional em /conta/global; /api/me/documentos e /compras são privados. Compra autenticada vincula automaticamente; a anônima pode ser vinculada em POST /api/documento/:id/vincular com sessão e X-Editalmd-Acesso. Depois do vínculo só a conta abre. Sem vínculo, guarde acesso.codigo. GET nunca inicia geração. > > Pagamento: x402 por requisição **ou** crédito pré-pago (`POST /api/credito?usd=10` → token `cred_…` em `Authorization: Bearer`, válido em todos os produtos da casa). ## Como ler - Cada endpoint traz caminho, auth, parâmetros, corpo, estrutura da resposta, erros e uma chamada que roda. - `Pagina` é referência: os campos estão em **Estruturas**, no fim, uma vez só. - `(opcional)` num campo quer dizer que ele pode não vir; `(pode ser null)` quer dizer que vem com valor nulo. - Fatie o que precisa: `https://staging.editalmd.com/llms-full.txt?prefix=/api/` devolve só aquele ramo. ## Autenticação - `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. - `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. - `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo. - `agente` — X-Agent-Pass da inscrição em api.editalmd.com/licitacoes/api/agente. Concessão individual temporária; sem conta humana ou pagamento. - `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. - `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. - `cobranca` — X-Cobranca: token de 64 hex minúsculos escolhido aleatoriamente pelo cliente; conserve para consultar e retomar sua cobrança. - `origem` — X-Editalmd-Secret: credencial privada de integração interna. Não é uma porta para clientes ou agentes públicos. ## Endpoints ## Avaliação ### `GET /api/avaliacao` Cotas documentais deste agente: um premium patrocinado e 100 leituras básicas. - **URL:** `https://staging.editalmd.com/api/avaliacao` - **Auth:** `agente` — X-Agent-Pass da inscrição em api.editalmd.com/licitacoes/api/agente. Concessão individual temporária; sem conta humana ou pagamento. **Headers** - `X-Agent-Pass` (string, obrigatório) — Credencial individual persistente obtida em POST https://api.editalmd.com/licitacoes/api/agente. Não é User-Agent. **Resposta `200`** - `expires_at` (string) — Fim da concessão individual, limitado pelo piloto. - `premium` (object) — granted:1, used, document_id e max_pages:50. - `basic` (object) — granted:100, used, max_pages:50 e reviewed:false. **Erros** - `400` — Campos ou consulta desconhecidos; POST aceita corpo ausente ou {}. - `401` — Credencial de agente ausente ou inválida. - `402` — Cota individual usada ou expirada; veja purchase_url para comprar. - `404` — Documento ou solicitação deste agente inexistente. - `409` — Fonte ou cotação indisponível/alterada; nenhuma cobrança. - `422` — Premium até 50 páginas; básico PDF até 50 páginas e 32 MiB. - `503` — Piloto encerrado, orçamento esgotado ou fila sem capacidade; preserve a credencial e tente depois. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/avaliacao -H "X-Agent-Pass: $AGENT_PASS" ``` ### `POST /api/documento/:id/avaliacao/premium` Concede um documento premium por agente; gera se necessário, sem cobrar o agente. Franquia por credencial, até a menor data entre os 30 dias do agente e o fim do piloto. Repetição do mesmo documento não consome outra unidade. Não envie pagamento. Premium: guarde evaluation.access_code e use X-Editalmd-Avaliacao junto de X-Agent-Pass nas leituras e no GET /geracao. Básico não abre conteúdo premium. Piloto sujeito ao orçamento global; sem renovação automática. - **URL:** `https://staging.editalmd.com/api/documento/:id/avaliacao/premium` - **Auth:** `agente` — X-Agent-Pass da inscrição em api.editalmd.com/licitacoes/api/agente. Concessão individual temporária; sem conta humana ou pagamento. **Parâmetros de caminho** - `id` (string, obrigatório) — ID positivo do documento do acervo. Ex.: `9927611`. **Headers** - `X-Agent-Pass` (string, obrigatório) — Credencial individual persistente obtida em POST https://api.editalmd.com/licitacoes/api/agente. Não é User-Agent. **Resposta `200`** - `documento_id` (int) — Documento solicitado. - `status` (string, opcional) — ready, pending, running ou failed; access_granted recupera a concessão premium, sem afirmar processamento concluído. Preparação premium também pode trazer error. - `error` (string, opcional, pode ser null) — Causa da falha, quando houver. - `retry_after_s` (int, opcional) — Intervalo para o próximo GET. - `evaluation` (object) — kind basic ou sponsored_premium. Premium inclui access_code privado, access_header e expires_at; cobrança zero. - `state_url` (string, opcional) — GET de acompanhamento do premium, com os dois headers de avaliação. - `result` (object, opcional) — Somente básico pronto: pages [{page,text}], page_count, ocr_page_count, source_sha256, reviewed:false, structured_tables:false e empty_pages. **Erros** - `400` — Campos ou consulta desconhecidos; POST aceita corpo ausente ou {}. - `401` — Credencial de agente ausente ou inválida. - `402` — Cota individual usada ou expirada; veja purchase_url para comprar. - `404` — Documento ou solicitação deste agente inexistente. - `409` — Fonte ou cotação indisponível/alterada; nenhuma cobrança. - `422` — Premium até 50 páginas; básico PDF até 50 páginas e 32 MiB. - `503` — Piloto encerrado, orçamento esgotado ou fila sem capacidade; preserve a credencial e tente depois. **Exemplo** ```sh curl -s -X POST https://staging.editalmd.com/api/documento/9927611/avaliacao/premium -H "X-Agent-Pass: $AGENT_PASS" ``` ### `POST /api/documento/:id/avaliacao/basico` Enfileira uma leitura básica individual: texto nativo e OCR local, sem revisão. Franquia por credencial, até a menor data entre os 30 dias do agente e o fim do piloto. Repetição do mesmo documento não consome outra unidade. Não envie pagamento. Premium: guarde evaluation.access_code e use X-Editalmd-Avaliacao junto de X-Agent-Pass nas leituras e no GET /geracao. Básico não abre conteúdo premium. Piloto sujeito ao orçamento global; sem renovação automática. - **URL:** `https://staging.editalmd.com/api/documento/:id/avaliacao/basico` - **Auth:** `agente` — X-Agent-Pass da inscrição em api.editalmd.com/licitacoes/api/agente. Concessão individual temporária; sem conta humana ou pagamento. **Parâmetros de caminho** - `id` (string, obrigatório) — ID positivo do documento do acervo. Ex.: `9927611`. **Headers** - `X-Agent-Pass` (string, obrigatório) — Credencial individual persistente obtida em POST https://api.editalmd.com/licitacoes/api/agente. Não é User-Agent. **Resposta `200`** - `documento_id` (int) — Documento solicitado. - `status` (string, opcional) — ready, pending, running ou failed; access_granted recupera a concessão premium, sem afirmar processamento concluído. Preparação premium também pode trazer error. - `error` (string, opcional, pode ser null) — Causa da falha, quando houver. - `retry_after_s` (int, opcional) — Intervalo para o próximo GET. - `evaluation` (object) — kind basic ou sponsored_premium. Premium inclui access_code privado, access_header e expires_at; cobrança zero. - `state_url` (string, opcional) — GET de acompanhamento do premium, com os dois headers de avaliação. - `result` (object, opcional) — Somente básico pronto: pages [{page,text}], page_count, ocr_page_count, source_sha256, reviewed:false, structured_tables:false e empty_pages. **Erros** - `400` — Campos ou consulta desconhecidos; POST aceita corpo ausente ou {}. - `401` — Credencial de agente ausente ou inválida. - `402` — Cota individual usada ou expirada; veja purchase_url para comprar. - `404` — Documento ou solicitação deste agente inexistente. - `409` — Fonte ou cotação indisponível/alterada; nenhuma cobrança. - `422` — Premium até 50 páginas; básico PDF até 50 páginas e 32 MiB. - `503` — Piloto encerrado, orçamento esgotado ou fila sem capacidade; preserve a credencial e tente depois. **Exemplo** ```sh curl -s -X POST https://staging.editalmd.com/api/documento/9927611/avaliacao/basico -H "X-Agent-Pass: $AGENT_PASS" ``` ### `GET /api/documento/:id/avaliacao/basico` Recupera estado e texto básico por página, somente para o agente que solicitou. Franquia por credencial, até a menor data entre os 30 dias do agente e o fim do piloto. Repetição do mesmo documento não consome outra unidade. Não envie pagamento. Premium: guarde evaluation.access_code e use X-Editalmd-Avaliacao junto de X-Agent-Pass nas leituras e no GET /geracao. Básico não abre conteúdo premium. Piloto sujeito ao orçamento global; sem renovação automática. - **URL:** `https://staging.editalmd.com/api/documento/:id/avaliacao/basico` - **Auth:** `agente` — X-Agent-Pass da inscrição em api.editalmd.com/licitacoes/api/agente. Concessão individual temporária; sem conta humana ou pagamento. **Parâmetros de caminho** - `id` (string, obrigatório) — ID positivo do documento do acervo. Ex.: `9927611`. **Headers** - `X-Agent-Pass` (string, obrigatório) — Credencial individual persistente obtida em POST https://api.editalmd.com/licitacoes/api/agente. Não é User-Agent. **Resposta `200`** - `documento_id` (int) — Documento solicitado. - `status` (string, opcional) — ready, pending, running ou failed; access_granted recupera a concessão premium, sem afirmar processamento concluído. Preparação premium também pode trazer error. - `error` (string, opcional, pode ser null) — Causa da falha, quando houver. - `retry_after_s` (int, opcional) — Intervalo para o próximo GET. - `evaluation` (object) — kind basic ou sponsored_premium. Premium inclui access_code privado, access_header e expires_at; cobrança zero. - `state_url` (string, opcional) — GET de acompanhamento do premium, com os dois headers de avaliação. - `result` (object, opcional) — Somente básico pronto: pages [{page,text}], page_count, ocr_page_count, source_sha256, reviewed:false, structured_tables:false e empty_pages. **Erros** - `400` — Campos ou consulta desconhecidos; POST aceita corpo ausente ou {}. - `401` — Credencial de agente ausente ou inválida. - `402` — Cota individual usada ou expirada; veja purchase_url para comprar. - `404` — Documento ou solicitação deste agente inexistente. - `409` — Fonte ou cotação indisponível/alterada; nenhuma cobrança. - `422` — Premium até 50 páginas; básico PDF até 50 páginas e 32 MiB. - `503` — Piloto encerrado, orçamento esgotado ou fila sem capacidade; preserve a credencial e tente depois. **Exemplo** ```sh curl -s -X GET https://staging.editalmd.com/api/documento/9927611/avaliacao/basico -H "X-Agent-Pass: $AGENT_PASS" ``` ## Análise de participação ### `GET /api/me/empresas/:cnpj/documentos` Lista os anexos privados da empresa; não inicia leitura ou análise. - **URL:** `https://staging.editalmd.com/api/me/empresas/:cnpj/documentos` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `cnpj` (string, obrigatório) — CNPJ de 14 dígitos vinculado ao dono. Ex.: `00394460000141`. **Resposta `200`** Estrutura: `DocumentosEmpresa`. - `itens` (DocumentoEmpresa[]) — Até 20 anexos da empresa deste dono. → ver `DocumentoEmpresa` em **Estruturas**. - `revisao` (string) — Hash do conjunto de documentos; alterações invalidam análises anteriores. - `limite` (int) — 20 documentos. - `limite_bytes` (int) — 8 MiB por PDF; 80 MiB no conjunto. - `limite_paginas` (int) — 50 páginas somadas entre os anexos. **Erros** - `400` — Entrada inválida. - `401` — Sessão da conta ou convidado válido necessário. - `402` — Acesso ao edital necessário. - `403` — Origem recusada. - `404` — Empresa ou documento ausente para este dono. - `409` — Fontes ou checkpoint indisponíveis. - `413` — Limite de documentos, páginas ou bytes. - `429` — Processamento em curso; tente depois. - `502` — Core indisponível. - `503` — Configuração ou orçamento de processamento indisponível. **Exemplo** ```sh curl -s -X GET 'https://staging.editalmd.com/api/me/empresas/00394460000141/documentos' -H 'X-Guest-Token: $GUEST' ``` ### `POST /api/me/empresas/:cnpj/documentos` Adiciona PDF de atestado, certidão ou outro comprovante à empresa. 201. JSON até 11.200.000 bytes; PDF até 8 MiB, 20 documentos/80 MiB/50 páginas por empresa. Arquivo idêntico é reaproveitado. A leitura automática acontece somente ao solicitar a análise. - **URL:** `https://staging.editalmd.com/api/me/empresas/:cnpj/documentos` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `cnpj` (string, obrigatório) — CNPJ de 14 dígitos vinculado ao dono. Ex.: `00394460000141`. **Corpo** (`application/json`) - `nome` (string) — Nome até 160 caracteres. - `tipo` (string) — atestado, certidao, licenca, contrato_social ou outro. - `arquivo_base64` (string) — PDF em base64 canônico, sem prefixo data:. Prefira envio HTTP a partir do arquivo local. **Resposta `200`** Estrutura: `DocumentosEmpresa`. - `itens` (DocumentoEmpresa[]) — Até 20 anexos da empresa deste dono. → ver `DocumentoEmpresa` em **Estruturas**. - `revisao` (string) — Hash do conjunto de documentos; alterações invalidam análises anteriores. - `limite` (int) — 20 documentos. - `limite_bytes` (int) — 8 MiB por PDF; 80 MiB no conjunto. - `limite_paginas` (int) — 50 páginas somadas entre os anexos. **Erros** - `400` — Entrada inválida. - `401` — Sessão da conta ou convidado válido necessário. - `402` — Acesso ao edital necessário. - `403` — Origem recusada. - `404` — Empresa ou documento ausente para este dono. - `409` — Fontes ou checkpoint indisponíveis. - `413` — Limite de documentos, páginas ou bytes. - `429` — Processamento em curso; tente depois. - `502` — Core indisponível. - `503` — Configuração ou orçamento de processamento indisponível. **Exemplo** ```sh curl -s 'https://staging.editalmd.com/api/me/empresas/00394460000141/documentos' -H 'Authorization: Bearer $SESS' -H 'Content-Type: application/json' --data-binary @anexo.json ``` ### `GET /api/me/empresas/:cnpj/documentos/:arquivo` Baixa o PDF privado, sem chamada de IA. - **URL:** `https://staging.editalmd.com/api/me/empresas/:cnpj/documentos/:arquivo` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `cnpj` (string, obrigatório) — CNPJ de 14 dígitos vinculado ao dono. Ex.: `00394460000141`. - `arquivo` (string, obrigatório) — SHA-256 retornado no envio. Ex.: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`. **Resposta `200`** PDF binário com Content-Disposition: attachment; use HTTP autenticado para baixar. **Erros** - `400` — Entrada inválida. - `401` — Sessão da conta ou convidado válido necessário. - `402` — Acesso ao edital necessário. - `403` — Origem recusada. - `404` — Empresa ou documento ausente para este dono. - `409` — Fontes ou checkpoint indisponíveis. - `413` — Limite de documentos, páginas ou bytes. - `429` — Processamento em curso; tente depois. - `502` — Core indisponível. - `503` — Configuração ou orçamento de processamento indisponível. **Exemplo** ```sh curl -s -X GET 'https://staging.editalmd.com/api/me/empresas/00394460000141/documentos/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' -H 'X-Guest-Token: $GUEST' ``` ### `DELETE /api/me/empresas/:cnpj/documentos/:arquivo` Remove o anexo desta empresa e invalida a análise que o utilizou. - **URL:** `https://staging.editalmd.com/api/me/empresas/:cnpj/documentos/:arquivo` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `cnpj` (string, obrigatório) — CNPJ de 14 dígitos vinculado ao dono. Ex.: `00394460000141`. - `arquivo` (string, obrigatório) — SHA-256 do anexo. Ex.: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`. **Resposta `200`** Estrutura: `DocumentosEmpresa`. - `itens` (DocumentoEmpresa[]) — Até 20 anexos da empresa deste dono. → ver `DocumentoEmpresa` em **Estruturas**. - `revisao` (string) — Hash do conjunto de documentos; alterações invalidam análises anteriores. - `limite` (int) — 20 documentos. - `limite_bytes` (int) — 8 MiB por PDF; 80 MiB no conjunto. - `limite_paginas` (int) — 50 páginas somadas entre os anexos. **Erros** - `400` — Entrada inválida. - `401` — Sessão da conta ou convidado válido necessário. - `402` — Acesso ao edital necessário. - `403` — Origem recusada. - `404` — Empresa ou documento ausente para este dono. - `409` — Fontes ou checkpoint indisponíveis. - `413` — Limite de documentos, páginas ou bytes. - `429` — Processamento em curso; tente depois. - `502` — Core indisponível. - `503` — Configuração ou orçamento de processamento indisponível. **Exemplo** ```sh curl -s -X DELETE 'https://staging.editalmd.com/api/me/empresas/00394460000141/documentos/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' -H 'X-Guest-Token: $GUEST' ``` ### `POST /api/me/empresas/:cnpj/analises/:id` Inicia ou retoma comparação de requisitos, atestados e obrigações com a empresa. 202 após aceitar e preservar o pedido; 200 ao reaproveitar análise concluída. Usa perfil e anexos deste dono. Pedidos interrompidos podem ser retomados; falhas informam motivo e próxima ação. POST explícito retoma uma pausa. Até 2 mil fatos e 100 editais por empresa, sujeitos à capacidade e ao orçamento disponíveis. Não cobra nova compra nesta operação. Acompanhamento somente por GET. A análise oferece triagem com evidências, não decisão definitiva de habilitação nem consulta jurídica externa. - **URL:** `https://staging.editalmd.com/api/me/empresas/:cnpj/analises/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `cnpj` (string, obrigatório) — CNPJ de 14 dígitos vinculado ao dono. Ex.: `00394460000141`. - `id` (string, obrigatório) — ID do documento com dossiê pronto e acesso autorizado. Ex.: `1993401`. **Query** - `v` (string, obrigatório) — SHA-256 do Markdown aberto, 64 hex minúsculos. **Resposta `200`** - `analise` (object) — Estado inicial: id, status, etapa, processados, total, CNPJ, hashes e datas. **Erros** - `400` — Entrada inválida. - `401` — Sessão da conta ou convidado válido necessário. - `402` — Acesso ao edital necessário. - `403` — Origem recusada. - `404` — Empresa ou documento ausente para este dono. - `409` — Fontes ou checkpoint indisponíveis. - `413` — Limite de documentos, páginas ou bytes. - `429` — Processamento em curso; tente depois. - `502` — Core indisponível. - `503` — Configuração ou orçamento de processamento indisponível. **Exemplo** ```sh curl -s -X POST 'https://staging.editalmd.com/api/me/empresas/00394460000141/analises/1993401?v=HASH_DO_MARKDOWN' -H 'Authorization: Bearer $SESS' ``` ### `GET /api/me/empresas/:cnpj/analises/:id` Consulta andamento ou resultados paginados; não inicia IA nem modifica a análise. Pendências reúne precisa_comprovar (falta prova), divergente (evidência incompatível) e acompanhar (obrigação futura). Cadastro, anexos ou dossiê diferentes retornam outdated sem resultados atuais. A data de referência é conservada na retomada; dia anterior retorna data_atual=false. Os lotes validados continuam disponíveis durante falhas/processamento com parcial=true e processados/total; nunca representam conclusão das exigências ainda não comparadas. GET não executa a fila nem inicia IA. - **URL:** `https://staging.editalmd.com/api/me/empresas/:cnpj/analises/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `cnpj` (string, obrigatório) — CNPJ de 14 dígitos vinculado ao dono. Ex.: `00394460000141`. - `id` (string, obrigatório) — ID do documento. Ex.: `1993401`. **Query** - `v` (string, obrigatório) — SHA-256 do Markdown aberto, 64 hex minúsculos. - `grupo` (string) — pendencias, atendidos ou nao_aplicavel; omitido retorna todos. - `kind` (string) — requirement, attestation ou obligation. - `after` (int) — Último ID recebido; padrão 0. - `limit` (int) — 1 a 30; padrão 30. **Resposta `200`** Estrutura: `AnaliseParticipacao`. - `analise` (object, pode ser null) — null quando nunca solicitada; id, status (queued/processing/retrying/paused/ready/failed/outdated/interrupted), atual, parcial, data_atual, etapa, processados, total, CNPJ, hashes, datas, erro, falha_etapa, problema (motivo/acao/automatico), historico e proxima_tentativa_em. atual permite consultar lotes validados; somente ready é cobertura concluída. data_atual=false exige conferir a data de referência. interrupted permite retomar pedido sem entrada de fila, inclusive legado. - `itens` (object[]) — Até 30 pares fact/analysis: fato do dossiê e avaliação com fact_id, status, reason, action, evidence (source_id/page/quote), edital_quote e edital_page. - `contagens` (object, opcional) — Totais pendencias, atendidos e nao_aplicavel dos lotes já validados da análise atual, inclusive durante processamento ou pausa; parcial=true não representa cobertura completa. - `tipos` (object, opcional) — Mesmas contagens separadas por requirement, attestation e obligation. - `next` (int, pode ser null) — Último ID desta página; use after até null. **Erros** - `400` — Entrada inválida. - `401` — Sessão da conta ou convidado válido necessário. - `402` — Acesso ao edital necessário. - `403` — Origem recusada. - `404` — Empresa ou documento ausente para este dono. - `409` — Fontes ou checkpoint indisponíveis. - `413` — Limite de documentos, páginas ou bytes. - `429` — Processamento em curso; tente depois. - `502` — Core indisponível. - `503` — Configuração ou orçamento de processamento indisponível. **Exemplo** ```sh curl -s 'https://staging.editalmd.com/api/me/empresas/00394460000141/analises/1993401?v=HASH_DO_MARKDOWN&grupo=pendencias&limit=30' -H 'Authorization: Bearer $SESS' ``` ## Empresas ### `GET /api/me/empresas` Lista as empresas importadas e a seleção privada do dono; GET não grava. - **URL:** `https://staging.editalmd.com/api/me/empresas` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Resposta `200`** Estrutura: `EmpresasConta`. - `itens` (EmpresaConta[]) — Até 20 vínculos, por CNPJ crescente; coleção completa. → ver `EmpresaConta` em **Estruturas**. - `selecionada` (string, pode ser null) — CNPJ selecionado pelo dono, ou null. - `limite` (int) — 20 empresas por dono. **Erros** - `400` — CNPJ ou busca inválida. - `401` — Sessão da conta ou convidado válido necessário. - `403` — Origem recusada. - `404` — Empresa ausente para este dono ou na base. - `405` — Método não permitido. - `409` — Limite de 20 empresas. - `503` — Origem, conta ou orçamento indisponível. **Exemplo** ```sh curl -s -X GET 'https://staging.editalmd.com/api/me/empresas' -H 'X-Guest-Token: $GUEST' ``` ### `GET /api/me/empresas/busca` Busca até oito sugestões por razão social ou CNPJ completo; não cadastra. - **URL:** `https://staging.editalmd.com/api/me/empresas/busca` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Query** - `q` (string, obrigatório) — CNPJ com ou sem pontuação ou razão social, de 3 a 120 caracteres. **Resposta `200`** - `itens` (SugestaoEmpresa[]) — Até oito resultados; refine a busca quando necessário. → ver `SugestaoEmpresa` em **Estruturas**. **Erros** - `400` — CNPJ ou busca inválida. - `401` — Sessão da conta ou convidado válido necessário. - `403` — Origem recusada. - `404` — Empresa ausente para este dono ou na base. - `405` — Método não permitido. - `409` — Limite de 20 empresas. - `503` — Origem, conta ou orçamento indisponível. **Exemplo** ```sh curl -s 'https://staging.editalmd.com/api/me/empresas/busca?q=padaria' -H 'X-Guest-Token: $GUEST' ``` ### `PUT /api/me/empresas/:cnpj` Importa os dados cadastrais e vincula o CNPJ ao dono. 201 ao criar, 200 na repetição sem nova consulta/escrita. Até 20 empresas. Importa os dados cadastrais disponíveis, sem sócios ou contatos; nenhuma análise é iniciada. - **URL:** `https://staging.editalmd.com/api/me/empresas/:cnpj` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `cnpj` (string, obrigatório) — CNPJ completo, 14 dígitos com verificação válida. Ex.: `00394460000141`. **Resposta `200`** Estrutura: `EmpresasConta`. - `itens` (EmpresaConta[]) — Até 20 vínculos, por CNPJ crescente; coleção completa. → ver `EmpresaConta` em **Estruturas**. - `selecionada` (string, pode ser null) — CNPJ selecionado pelo dono, ou null. - `limite` (int) — 20 empresas por dono. **Erros** - `400` — CNPJ ou busca inválida. - `401` — Sessão da conta ou convidado válido necessário. - `403` — Origem recusada. - `404` — Empresa ausente para este dono ou na base. - `405` — Método não permitido. - `409` — Limite de 20 empresas. - `503` — Origem, conta ou orçamento indisponível. **Exemplo** ```sh curl -s -X PUT 'https://staging.editalmd.com/api/me/empresas/00394460000141' -H 'X-Guest-Token: $GUEST' ``` ### `PUT /api/me/empresas/:cnpj/selecionar` Seleciona uma empresa já cadastrada para trabalhar no edital. Seleção persistida para este dono; vincular a conta permite recuperá-la em outros aparelhos. Não executa análise; repetir a seleção atual não grava. - **URL:** `https://staging.editalmd.com/api/me/empresas/:cnpj/selecionar` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `cnpj` (string, obrigatório) — CNPJ completo, 14 dígitos com verificação válida. Ex.: `00394460000141`. **Resposta `200`** Estrutura: `EmpresasConta`. - `itens` (EmpresaConta[]) — Até 20 vínculos, por CNPJ crescente; coleção completa. → ver `EmpresaConta` em **Estruturas**. - `selecionada` (string, pode ser null) — CNPJ selecionado pelo dono, ou null. - `limite` (int) — 20 empresas por dono. **Erros** - `400` — CNPJ ou busca inválida. - `401` — Sessão da conta ou convidado válido necessário. - `403` — Origem recusada. - `404` — Empresa ausente para este dono ou na base. - `405` — Método não permitido. - `409` — Limite de 20 empresas. - `503` — Origem, conta ou orçamento indisponível. **Exemplo** ```sh curl -s -X PUT 'https://staging.editalmd.com/api/me/empresas/00394460000141/selecionar' -H 'X-Guest-Token: $GUEST' ``` ### `DELETE /api/me/empresas/:cnpj` Remove somente o vínculo do próprio dono e limpa a seleção se necessário. - **URL:** `https://staging.editalmd.com/api/me/empresas/:cnpj` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `cnpj` (string, obrigatório) — CNPJ completo, 14 dígitos com verificação válida. Ex.: `00394460000141`. **Resposta `200`** Estrutura: `EmpresasConta`. - `itens` (EmpresaConta[]) — Até 20 vínculos, por CNPJ crescente; coleção completa. → ver `EmpresaConta` em **Estruturas**. - `selecionada` (string, pode ser null) — CNPJ selecionado pelo dono, ou null. - `limite` (int) — 20 empresas por dono. **Erros** - `400` — CNPJ ou busca inválida. - `401` — Sessão da conta ou convidado válido necessário. - `403` — Origem recusada. - `404` — Empresa ausente para este dono ou na base. - `405` — Método não permitido. - `409` — Limite de 20 empresas. - `503` — Origem, conta ou orçamento indisponível. **Exemplo** ```sh curl -s -X DELETE 'https://staging.editalmd.com/api/me/empresas/00394460000141' -H 'X-Guest-Token: $GUEST' ``` ## Conta ### `GET /api/auth/bootstrap` Prepara o navegador para entrar na conta global. Define cookie HttpOnly restrito ao host. CSRF vinculado à sessão atual. Sem CORS. - **URL:** `https://staging.editalmd.com/api/auth/bootstrap` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** - `csrf` (string) — X-CSRF-Token - `context` (string) — Opaque view context, also in X-MM-Context; not a credential / contexto opaco da vista, não é credencial. **Erros** - `400` — invalid_request - `403` — invalid_origin / invalid_csrf - `503` — auth_unavailable: a sessão anterior é preservada / the previous session is preserved ### `GET /api/account/profile` Consulta seu perfil global. Lê preferências atuais da conta. Altere-as na página da conta; produtos não mantêm perfil autoritativo separado. - **URL:** `https://staging.editalmd.com/api/account/profile` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Resposta `200`** {profile:{name,locale,timeZone,theme,revision}} **Erros** - `401` — invalid_session - `503` — auth_unavailable **Exemplo** ```js await fetch("https://staging.editalmd.com/api/account/profile", {credentials: "same-origin"}).then(r => r.json()); ``` ### `GET /api/account/avatar` Consulta sua foto de perfil global. WebP privado de até 64 KiB, sem cache. Altere-o na conta. Não aceita ID de usuário ou URL de objeto. - **URL:** `https://staging.editalmd.com/api/account/avatar` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Resposta `200`** image/webp; Cache-Control: no-store **Erros** - `401` — invalid_session - `404` — not_found: no photo / sem foto - `503` — auth_unavailable **Exemplo** ```js await fetch("https://staging.editalmd.com/api/account/avatar", {credentials: "same-origin"}).then(r => {if (!r.ok) throw new Error("HTTP " + r.status); return r.blob();}); ``` ### `POST /api/auth/logout` Revoga esta sessão do produto. Exige bootstrap/CSRF deste navegador e sessão. As sessões de outros produtos permanecem ativas. - **URL:** `https://staging.editalmd.com/api/auth/logout` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Resposta `200`** - `ok` (bool) — true **Erros** - `400` — invalid_request - `403` — invalid_origin / invalid_csrf - `503` — auth_unavailable: a sessão anterior é preservada / the previous session is preserved **Exemplo** ```js // Execute no console da página do produto / Run in the product page console. (async () => { const origin = "https://staging.editalmd.com"; const {csrf} = await fetch(origin + "/api/auth/bootstrap").then(r => r.json()); const r = await fetch(origin + "/api/auth/logout", { method: "POST", credentials: "same-origin", headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf}, body: JSON.stringify({}) }); if (!r.ok) throw new Error("Auth HTTP " + r.status); return r.json(); })(); ``` ### `GET /api/account/keys` Lista suas chaves de API neste produto. Nunca devolve a chave: nome, 4 últimos caracteres, organização, criação, último uso (por hora) e se ainda vale. - **URL:** `https://staging.editalmd.com/api/account/keys` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Resposta `200`** - `keys` (object[]) — `id`, `name`, `organizationId`, `last4`, `createdAt`, `lastUsedAt`, `revokedAt`, `active` (false quando revogada ou parada por troca de senha / encerrar todos os acessos). **Erros** - `401` — invalid_session - `503` — auth_unavailable **Exemplo** ```js await fetch("https://staging.editalmd.com/api/account/keys", {credentials: "same-origin"}).then(r => r.json()); ``` ### `POST /api/account/keys/create` Cria uma chave de API para agentes e scripts. Exige entrada nos últimos 5 minutos; a de organização também exige segundo fator na sessão e o papel de dona/administradora com o produto ligado. No máximo 10 chaves vivas por conta e produto. A chave (`secret`) volta UMA vez. - **URL:** `https://staging.editalmd.com/api/account/keys/create` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Corpo** (`application/json`) - `name` (string, obrigatório) — Até 60 caracteres. - `organizationId` (string, obrigatório) — `null` para chave da conta. **Exemplo de corpo** ```json { "name": "agent", "organizationId": null } ``` **Resposta `200`** - `key` (object) — `id`, `name`, `organizationId`, `last4`, `createdAt`. - `secret` (string) — `mmk_…`, mostrada uma vez. **Erros** - `400` — invalid_key_name / invalid_organization - `401` — invalid_session / reauth_required - `403` — invalid_origin / invalid_csrf / organization_forbidden / organization_mfa_required - `409` — key_limit_reached - `503` — auth_unavailable **Exemplo** ```js (async () => { const {csrf} = await fetch("https://staging.editalmd.com/api/auth/bootstrap").then(r => r.json()); const r = await fetch("https://staging.editalmd.com/api/account/keys/create", {method: "POST", credentials: "same-origin", headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf}, body: JSON.stringify({name: "agent", organizationId: null})}); return r.json(); })(); ``` ### `POST /api/account/keys/revoke` Revoga uma das suas chaves de API. Para a chave na hora. Repetir não faz mal. - **URL:** `https://staging.editalmd.com/api/account/keys/revoke` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Corpo** (`application/json`) - `id` (string, obrigatório) — O `id` da chave. **Exemplo de corpo** ```json { "id": "…" } ``` **Resposta `200`** - `ok` (bool) — true **Erros** - `400` — invalid_key_id - `401` — invalid_session - `403` — invalid_origin / invalid_csrf - `404` — key_not_found - `503` — auth_unavailable **Exemplo** ```js (async () => { const {csrf} = await fetch("https://staging.editalmd.com/api/auth/bootstrap").then(r => r.json()); const r = await fetch("https://staging.editalmd.com/api/account/keys/revoke", {method: "POST", credentials: "same-origin", headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf}, body: JSON.stringify({id: "…"})}); return r.json(); })(); ``` ### `POST /api/auth/claim` Passa para a conta o que o convidado criou: as Salvas, os Alertas e as Vigias que a conta ainda não tem (uma lista de cada por conta), o segredo do webhook se ela ainda não tem um, e as compras do convidado. Exige bootstrap/CSRF deste navegador; a página faz isso logo depois de entrar. Só passa o que o convidado ainda tem, numa transação, e o que colide com o que a conta já tem fica com o convidado. O que o convidado comprou passa junto. Token antigo, sem assinatura, que não é dono de nada aqui é recusado. Repetir não faz mal (move zero). - **URL:** `https://staging.editalmd.com/api/auth/claim` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Corpo** (`application/json`) - `guest_token` (string, obrigatório) — Convidado `edm_…` deste navegador. **Exemplo de corpo** ```json { "guest_token": "edm_…" } ``` **Resposta `200`** - `ok` (bool) — Se o convidado foi reconhecido e passou. - `claimed` (object) — `product.movidos` (linhas que mudaram de dono, por tabela), `product.apagados` (duplicatas do convidado descartadas) e `product.direitos` (compras que passaram). **Erros** - `400` — invalid_product_claim / invalid_body - `401` — invalid_session - `403` — invalid_origin / invalid_csrf - `409` — unknown_guest (em `claimed.reason` / in `claimed.reason`) - `503` — product_claim_pending / auth_unavailable **Exemplo** ```js (async () => { const {csrf} = await fetch("https://staging.editalmd.com/api/auth/bootstrap").then(r => r.json()); const r = await fetch("https://staging.editalmd.com/api/auth/claim", {method: "POST", credentials: "same-origin", headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf}, body: JSON.stringify({guest_token: localStorage.getItem("editalmd_token")})}); return r.json(); })(); ``` ### `GET /api/me` Identifica sua conta, conta seus acessos e acompanhamentos e aponta biblioteca e histórico. A conta global já é a pessoa no EditalMD: não há ativação por produto. - **URL:** `https://staging.editalmd.com/api/me` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Query** - `locais` (string) — Até 90 IDs positivos de documentos separados por vírgula, no máximo 1529 caracteres; omita se não houver acessos locais para conciliar. **Resposta `200`** - `user` (object) — id (o id da conta global) e email da conta. - `documentos_url` (string) — Biblioteca privada. - `compras_url` (string) — Histórico privado. - `totais` (object) — documentos (IDs distintos com direito comprado), salvas e alertas (incluindo pausados) da conta; zero quando vazio. - `acompanhamento_vinculado` (bool) — Sempre true: a conta é dona direto das listas dela. - `locais_vinculados` (int[]) — Dos IDs informados em locais, somente os que já pertencem à conta atual; evita duplicar o contador do navegador. Não concede acesso. **Erros** - `400` — Corpo/cursor inválido. - `401` — Sessão ausente, inválida ou encerrada (`session_ended`: entre de novo). - `403` — Origem de mutação ou CSRF recusados. - `404` — Aquisição não encontrada para este cliente. - `405` — Método não permitido. - `503` — Conta ou limite global indisponível. **Exemplo** ```js await fetch("https://staging.editalmd.com/api/me", {credentials: "same-origin"}).then(r => r.json()); ``` ### `GET /api/me/documentos` Documentos comprados por esta conta; reabertura sem novo pagamento. - **URL:** `https://staging.editalmd.com/api/me/documentos` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Query** - `antes` (string) — proximo_antes da página anterior; hex, cursor exclusivo do cliente. **Resposta `200`** - `itens` (object[]) — Direitos de documento da conta (direito global do pagamento): id, documento_id, via (x402, credito, deposito ou simulado), created_at, abrir_url, geracao_url, markdown_url. - `proximo_antes` (string, pode ser null) — Sempre null: a coleção vem inteira, até 200. **Erros** - `400` — Corpo/cursor inválido. - `401` — Sessão ausente, inválida ou encerrada (`session_ended`: entre de novo). - `403` — Origem de mutação ou CSRF recusados. - `404` — Aquisição não encontrada para este cliente. - `405` — Método não permitido. - `503` — Conta ou limite global indisponível. **Exemplo** ```js await fetch("https://staging.editalmd.com/api/me/documentos", {credentials: "same-origin"}).then(r => r.json()); ``` ### `GET /api/me/compras` Histórico privado das aquisições, mais recentes primeiro. - **URL:** `https://staging.editalmd.com/api/me/compras` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Query** - `antes` (string) — proximo_antes da página anterior; hex, cursor exclusivo do cliente. **Resposta `200`** - `itens` (object[]) — Direitos de documento da conta (direito global do pagamento): id, documento_id, via (x402, credito, deposito ou simulado), created_at, abrir_url, geracao_url, markdown_url. - `proximo_antes` (string, pode ser null) — Sempre null: a coleção vem inteira, até 200. **Erros** - `400` — Corpo/cursor inválido. - `401` — Sessão ausente, inválida ou encerrada (`session_ended`: entre de novo). - `403` — Origem de mutação ou CSRF recusados. - `404` — Aquisição não encontrada para este cliente. - `405` — Método não permitido. - `503` — Conta ou limite global indisponível. **Exemplo** ```js await fetch("https://staging.editalmd.com/api/me/compras", {credentials: "same-origin"}).then(r => r.json()); ``` ### `POST /api/documento/:id/vincular` Associa sua aquisição anônima à conta autenticada, sem nova cobrança. Exige sessão e prova privada da aquisição. Grava o direito global da conta pelo recibo do pagamento: idempotente para o mesmo dono, e outro dono não pode reivindicar. O código continua abrindo o documento sozinho. - **URL:** `https://staging.editalmd.com/api/documento/:id/vincular` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Parâmetros de caminho** - `id` (string, obrigatório) — ID positivo do documento comprado. **Headers** - `X-Editalmd-Acesso` (string) — Capacidade privada recebida após pagamento. Cookie documental também aceito. **Resposta `200`** - `vinculado` (bool) — Aquisição pertence à conta. - `documento_id` (int) — Documento. **Erros** - `400` — Corpo/cursor inválido. - `401` — Sessão ausente, inválida ou encerrada (`session_ended`: entre de novo). - `403` — Origem de mutação ou CSRF recusados. - `404` — Aquisição não encontrada para este cliente. - `405` — Método não permitido. - `503` — Conta ou limite global indisponível. **Exemplo** ```js (async () => { const {csrf} = await fetch("https://staging.editalmd.com/api/auth/bootstrap").then(r => r.json()); const r = await fetch("https://staging.editalmd.com/api/documento/2110258/vincular", {method: "POST", credentials: "same-origin", headers: {"X-CSRF-Token": csrf, "X-Editalmd-Acesso": ACESSO}}); return r.json(); })(); ``` ### `GET /api/documento/:id/acesso` Confere vínculo e permite exportar o código da aquisição ainda anônima. - **URL:** `https://staging.editalmd.com/api/documento/:id/acesso` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — ID positivo do documento comprado. **Headers** - `X-Editalmd-Acesso` (string) — Código de acesso; sessão/cookie equivalente aceitos. **Resposta `200`** - `documento_id` (int) — Documento. - `vinculado` (bool) — A conta atual possui este documento. - `recuperacao` (string, pode ser null) — Código privado exportável somente enquanto não vinculado. **Erros** - `400` — Corpo/cursor inválido. - `401` — Sessão ausente, inválida ou encerrada (`session_ended`: entre de novo). - `402` — Acesso não comprado. - `403` — Origem de mutação ou CSRF recusados. - `404` — Aquisição não encontrada para este cliente. - `405` — Método não permitido. - `503` — Conta ou limite global indisponível. **Exemplo** ```js await fetch("https://staging.editalmd.com/api/documento/2110258/acesso", {credentials: "same-origin"}).then(r => r.json()); ``` ### `GET /api/me/acompanhamento` Confere que Salvas/Alertas/Vigias são da conta da sessão. As listas de um convidado edm_… passam para a conta em `POST /api/auth/claim`; o POST desta rota responde 410 com o caminho. - **URL:** `https://staging.editalmd.com/api/me/acompanhamento` - **Auth:** `session` — Conta: cookie HttpOnly `__Host-mm-session-editalmd-web`, gravado por `/api/auth/callback` depois de entrar em `/conta/global`; escrita exige a mesma origem e `X-CSRF-Token` de `/api/auth/bootstrap`. Não há bearer para pessoas. Conta não concede documentos sem compra vinculada. **Resposta `200`** - `vinculado` (bool) — Sempre true com sessão: a conta é dona direto das listas dela. **Erros** - `400` — Corpo/cursor inválido. - `401` — Sessão ausente, inválida ou encerrada (`session_ended`: entre de novo). - `403` — Origem de mutação ou CSRF recusados. - `404` — Aquisição não encontrada para este cliente. - `405` — Método não permitido. - `503` — Conta ou limite global indisponível. **Exemplo** ```js await fetch("https://staging.editalmd.com/api/me/acompanhamento", {credentials: "same-origin"}).then(r => r.json()); ``` ## Descoberta ### `GET /api/` Índice auto-descrito: rotas, regime de cobrança, preço e MCP. - **URL:** `https://staging.editalmd.com/api/` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** - `name` (string) — Nome do produto. - `description` (string) — O que o produto faz. - `build` (string) — Commit publicado. - `base_url` (string) — Origem em que esta API está servindo. - `docs` (object) — Links para llms.txt, OpenAPI, MCP e a UI. - `endpoints` (object[]) — Catálogo de endpoints. - `mcp_tools` (string[]) — Tools do MCP. - `regime` (string) — A regra de cobrança por recência, em uma frase. - `gratis_acima_de_dias` (int) — Idade de publicação a partir da qual o documento é amostra grátis. - `pago` (object) — Rota paga e o preço por requisição. - `cota` (object) — O que é grátis, o que é pago e como pagar. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/ ``` ### `GET /api/health` Saúde da origem e tamanho do acervo. - **URL:** `https://staging.editalmd.com/api/health` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** Estrutura: `Saude`. - `ok` (bool) — `true` quando a origem respondeu. - `build` (string) — Commit publicado (`env.BUILD`), o mesmo do `/api/`. - `acervo` (Acervo) — Números do acervo. → ver `Acervo` em **Estruturas**. - `preco_markdown_usd` (string) — Tarifa por página por comprador, com geração incluída. - `gratis_acima_de_dias` (int) — Legado, sempre zero; nenhuma faixa de data concede gratuidade. **Erros** - `503` — Origem indisponível. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/health ``` ### `POST /mcp` MCP Streamable HTTP — as tools deste catálogo, despachadas neste mesmo Worker. - **URL:** `https://staging.editalmd.com/mcp` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** JSON-RPC 2.0 (`initialize`, `tools/list`, `tools/call`). **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ### `GET /okf/:arquivo` Bundle OKF (Open Knowledge Format v0.1): markdown com frontmatter para o agente ler o produto inteiro sem parsear HTML. - **URL:** `https://staging.editalmd.com/okf/:arquivo` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `arquivo` (string, obrigatório) — `index.md`, `sobre.md`, `api.md` ou `faq.md`. Ex.: `index.md`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** `text/markdown`. Comece por `/okf/index.md`, que lista o bundle. **Erros** - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. **Exemplo** ```sh curl -s https://staging.editalmd.com/okf/index.md ``` ### `GET /.well-known/:arquivo` Descoberta de máquina antes da home: `api-catalog` (RFC 9727, linkset com a API e o MCP), `security.txt` (RFC 9116), `x402` (manifesto de pagamento: rede, carteira e rotas que cobram), `agent-card.json` (identidade do agente: ferramentas MCP e portas de descoberta; também em `/agent.json`) e `mcp-registry-auth` (chave do registro oficial de MCP). - **URL:** `https://staging.editalmd.com/.well-known/:arquivo` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Parâmetros de caminho** - `arquivo` (string, obrigatório) — `api-catalog`, `security.txt`, `x402`, `agent-card.json`, `mcp-registry-auth` ou `apis.json`. Ex.: `api-catalog`. **Resposta `200`** `application/linkset+json` no api-catalog; `application/json` no x402, no agent-card.json e no apis.json; `text/plain` nos outros dois. **Erros** - `404` — Nome fora dos seis publicados. **Exemplo** ```sh curl -s https://staging.editalmd.com/.well-known/api-catalog ``` ### `GET /apis.json` APIs.json (apisjson.org, 0.19): o índice que o APIs.io colhe — a API, o MCP, OpenAPI, guia e bundle OKF num arquivo só. Também em `/.well-known/apis.json`. - **URL:** `https://staging.editalmd.com/apis.json` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** `application/json` no formato APIs.json 0.19: `apis[]` com `baseURL`, `humanURL` e `properties[]`. **Exemplo** ```sh curl -s https://staging.editalmd.com/apis.json ``` ### `GET /agent.json` Cartão do agente: identidade, quem opera, documentação, o endpoint MCP e as ferramentas que ele serve. Mesmo documento de `/.well-known/agent-card.json`. - **URL:** `https://staging.editalmd.com/agent.json` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** `application/json`: `name`, `provider`, `protocol` (`mcp`), `interfaces[]` e `skills[]`. **Exemplo** ```sh curl -s https://staging.editalmd.com/agent.json ``` ### `GET /okf/:tipo/:id.md` O mesmo registro que a API responde, em markdown OKF: `documento` (Documento do acervo). Via de acesso para quem já tem o id, não catálogo. - **URL:** `https://staging.editalmd.com/okf/:tipo/:id.md` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `tipo` (string, obrigatório) — Um de: `documento`. Ex.: `documento`. - `id` (string, obrigatório) — O id do registro, como a API o aceita. Ex.: `123`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** `text/markdown` com frontmatter OKF; `resource` aponta o JSON equivalente. Sem `.md` responde 301 para o canônico. **Erros** - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. **Exemplo** ```sh curl -s https://staging.editalmd.com/okf/documento/123.md ``` ### `GET /feed.xml` RSS 2.0 das compras publicadas mais recentemente no acervo. - **URL:** `https://staging.editalmd.com/feed.xml` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** `application/rss+xml`. **Exemplo** ```sh curl -s https://staging.editalmd.com/feed.xml ``` ### `GET /feed.json` JSON Feed 1.1 das compras publicadas mais recentemente — o mesmo stream do RSS. - **URL:** `https://staging.editalmd.com/feed.json` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** `application/feed+json`. **Exemplo** ```sh curl -s https://staging.editalmd.com/feed.json ``` ### `GET /api/pricing` Preços vigentes e franquias gratuitas. - **URL:** `https://staging.editalmd.com/api/pricing` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** - `product` (string) — Product name. - `quota` (PaymentQuota) — Public allowances and current list prices; not personal usage. → ver `PaymentQuota` em **Estruturas**. - `pricing` (string) — Absolute URL of the current price list. - `billing` (string) — Absolute URL of payment discovery or the existing billing summary. - `api_index` (string) — Absolute URL of the API catalog. **Erros** - `405` — Use GET ou HEAD. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/pricing ``` ### `GET /api/billing` Descoberta pública de pagamento e crédito pré-pago. - **URL:** `https://staging.editalmd.com/api/billing` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** - `product` (string) — Product name. - `quota` (PaymentQuota) — Public allowances and current list prices; not personal usage. → ver `PaymentQuota` em **Estruturas**. - `pricing` (string) — Absolute URL of the current price list. - `billing` (string) — Absolute URL of payment discovery or the existing billing summary. - `api_index` (string) — Absolute URL of the API catalog. - `payment` (PaymentX402) — Public x402 configuration; pay_to=null means not configured. → ver `PaymentX402` em **Estruturas**. - `credit` (PaymentCredit) — Prepaid credit entry point. Never contains a balance or token. → ver `PaymentCredit` em **Estruturas**. **Erros** - `405` — Use GET ou HEAD. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/billing ``` ## Acervo ### `GET /api/busca` Busca compras públicas por termo. Consulta grátis. - **URL:** `https://staging.editalmd.com/api/busca` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Query** - `q` (string, obrigatório) — Termo de busca; mínimo 3 letras. - `uf` (string) — Filtra por sigla de UF. - `abertas` (string) — `1` devolve só compras com prazo de proposta ainda por vencer. Valores: `1`. - `limite` (int) — 1 a 50 (padrão 20). **Resposta `200`** Estrutura: `Busca`. - `itens` (Compra[]) — Compras que casaram com o termo. → ver `Compra` em **Estruturas**. - `preco_markdown_usd` (string) — Tarifa por página por comprador, inclusive texto pronto. - `gratis_acima_de_dias` (int) — Legado, sempre zero; nenhuma faixa de data concede gratuidade. - `pago` (bool) — Sempre `false`: buscar não custa. **Erros** - `400` — Termo com menos de 3 letras. - `502` — Origem indisponível. - `503` — Busca demorada (combinação rara de filtro e offset acima do teto da origem): `busca_demorada`, com `Retry-After` — refine o termo ou reduza o offset. **Exemplo** ```sh curl -s 'https://staging.editalmd.com/api/busca?q=uniforme%20escolar&uf=GO' ``` ### `GET /api/cnaes` Atividades econômicas (CNAE), descrições e sugestões de termos para alertas. Grátis. Sem `q`, lista atividades com mais fornecedores registrados. Com `q`, busca por prefixo do código (`1412`, `1412-6/01`) ou por palavra da descrição. `familia`/`termos` nulos dizem que o CNAE ainda não está no dicionário: um alerta por CNPJ não o usa. - **URL:** `https://staging.editalmd.com/api/cnaes` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Query** - `q` (string) — Prefixo do código (2 a 7 dígitos) ou palavra da descrição (2+ letras). - `limite` (int) — 1 a 100 (padrão 20), por fornecedores no SICAF, decrescente. **Resposta `200`** - `itens` (Cnae[]) — Os CNAEs que casam, os com mais fornecedores primeiro. → ver `Cnae` em **Estruturas**. - `limite` (int) — Teto aplicado. - `q` (string, pode ser null) — O filtro aplicado. - `dicionario` (object) — `familias`, `cnaes_mapeados` e `medido_em` (quando a cobertura no acervo foi medida). - `fontes` (object) — Créditos dos dados apresentados. **Erros** - `400` — `q` com menos de 2 caracteres. - `503` — Banco indisponível. **Exemplo** ```sh curl -s 'https://staging.editalmd.com/api/cnaes?q=1412' ``` ### `GET /api/compra/:id` Ficha da compra com prazos de proposta e impugnação, documentos e o regime de cobrança de cada um. Servida do cache da borda por até 6 horas — a ficha raramente muda; prazos e preços são calculados a cada pedido. `Cache-Control: no-cache` no pedido lê a origem na hora. O cabeçalho `x-origem-cache` diz `hit`, `miss` ou `bypass`. - **URL:** `https://staging.editalmd.com/api/compra/:id` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador da compra, vindo da busca. Ex.: `42`. **Resposta `200`** Estrutura: `FichaCompra`. - `compra` (Compra) — A compra. → ver `Compra` em **Estruturas**. - `documentos` (Documento[]) — Documentos com texto pronto ou binário disponível. → ver `Documento` em **Estruturas**. - `regime` (Regime) — Acesso individual pago; somente exemplos explícitos gratuitos. → ver `Regime` em **Estruturas**. - `prazos` (Prazos) — Proposta e impugnação da compra — o mesmo objeto de `compra.prazos`. → ver `Prazos` em **Estruturas**. **Erros** - `404` — Compra não encontrada. - `502` — Origem indisponível. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/compra/42 ``` ### `GET /api/documento/:id` Título, tipo, páginas e compra vinculada ao documento. Consulta pública, sem iniciar extração. - **URL:** `https://staging.editalmd.com/api/documento/:id` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento. Ex.: `93998`. **Resposta `200`** - `documento` (object) — id, titulo, tipo, paginas (null quando desconhecidas), tem_texto, tem_binario, disponivel e gratuito. Não inclui texto, arquivos ou caminhos internos. - `compra_id` (int, pode ser null) — Compra vinculada. Consulte /api/compra/:id para listar seus documentos com títulos, tipos e páginas (até 50 por ficha). **Erros** - `400` — ID inválido. - `404` — Documento não encontrado. - `502` — Origem indisponível. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/documento/93998 ``` ### `GET /api/documento/:id/markdown` Markdown com procedência e hash, com acesso comprado ou premium patrocinado. Cinco exemplos gratuitos. - **URL:** `https://staging.editalmd.com/api/documento/:id/markdown` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento, vindo da ficha da compra. Ex.: `123`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** `text/markdown`. Headers: `x-editalmd-regime`, `x-editalmd-sha256`. Leitura não gera recibo ou cobrança. **Erros** - `202` — Texto em preparação no acervo (`extracao_em_andamento`): `retry_after_s` no corpo e `Retry-After` no header. Repita após esse prazo. A preparação ainda não é uma entrega concluída. - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. - `409` — Texto indisponível ou geração necessária. Use geracao_url para consultar páginas e total e autorizar o pagamento. - `502` — Origem indisponível; nenhuma cobrança na leitura. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/documento/123/markdown ``` ### `POST /api/documento/:id/habilitacao` Lista de habilitação com trechos literais. Exige acesso ao documento comprado; sem cobrança adicional nesta fase. Condições, exceções e evidências por página da análise disponível. A consulta não inicia outra análise. Prazos, propostas e demais obrigações estão no dossie; esta lista cobre habilitação e atestados exigidos, sem afirmar o que a empresa possui. - **URL:** `https://staging.editalmd.com/api/documento/:id/habilitacao` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento, vindo da ficha da compra. Ex.: `123`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** Estrutura: `Habilitacao`. - `documento_id` (int) — Documento lido. - `compra_id` (int, pode ser null) — Compra do documento. - `sha256_texto` (string) — Hash do texto fonte do dossiê. - `dossie_versao` (string) — Hash da identidade da análise compartilhada. - `modelo` (string, pode ser null) — Modelo que extraiu. - `cache` (bool) — False: consulta a versão atual disponível. - `recibo` (string, pode ser null) — Recibo da entrega paga; nulo no cache. - `recibo_url` (string, pode ser null) — Onde consultar o recibo. - `aviso` (string) — Lembrete de conferir no edital. - `habilitacao` (ListaHabilitacao) — As exigências por família e o que o edital diz de prazo. → ver `ListaHabilitacao` em **Estruturas**. **Erros** - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. - `409` — Dossiê ainda em preparação. Nenhuma nova análise é iniciada por esta consulta. - `502` — Dossiê inválido ou resposta incompleta da origem. - `503` — Dossiê temporariamente indisponível. **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/api/documento/123/habilitacao ``` ### `GET /api/documento/:id/geracao` Estado, cotação e direito de acesso; consulta gratuita, sem iniciar processamento. - **URL:** `https://staging.editalmd.com/api/documento/:id/geracao` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Parâmetros de caminho** - `id` (string, obrigatório) — ID positivo do documento retornado pela compra. Ex.: `2110000`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** - `documento_id` (int) — Documento solicitado. - `status` (string, opcional) — `pronto` quando a leitura pode ser aberta. - `error` (string, opcional) — `geracao_necessaria`, `extracao_em_andamento`, `geracao_falhou` ou causa da indisponibilidade. - `retry_after_s` (int, opcional) — Intervalo mínimo até o próximo GET de acompanhamento. - `processing` (object, opcional) — Progresso real: `progress.stage` (preparing, reading, verifying, packaging), `pages_total`, `pages_processed`, `pages_completed`, `pass`; `updated_at` e `elapsed_ms`. - `markdown_url` (string) — GET do Markdown, com o acesso comprado. - `geracao_url` (string) — GET para estado/cotação; POST para comprar acesso individual. - `acesso_comprado` (boolean) — Esta credencial pode ler o documento, independentemente do estado global do texto. → ver `boolean` em **Estruturas**. - `acesso` (object, opcional) — Após pagamento confirmado fora da sessão da conta: codigo privado e header X-Editalmd-Acesso. Guarde para reabrir ou para vincular a uma conta (POST /vincular). Não publique, não abre outro documento. - `preco_pagina_usd` (string) — US$ 0,02 por página no site e API (x402 ou crédito). - `cotacao` (object, pode ser null) — Páginas confirmadas no documento: paginas, source_sha256, preco_pagina_usd e preco_total_usd. Nulo quando não é possível cotar. - `pagamento` (object, opcional) — Quando cobrado: `recibo` da porta x402/crédito e `preco_usd`. Conserve mesmo se a origem falhar. **Erros** - `202` — Processamento em curso; acompanhe por GET, respeitando Retry-After. Nunca repita POST para fazer polling. - `404` — Documento inexistente. - `409` — Geração necessária, falha anterior ou binário indisponível; consulte `error`. - `502` — Origem indisponível; não repita pagamento sem conferir o estado e o recibo. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/documento/1993401/geracao ``` ### `POST /api/documento/:id/geracao` Compra acesso individual ao documento por US$ 0,02/página, via x402/crédito. Cada comprador paga, inclusive pronto. Consulte GET ou 402, confira páginas/hash/total e envie cotacao. Sessão da conta (cookie + CSRF do navegador) grava a compra no direito global da conta antes da entrega, sem código avulso; com o convidado edm_… (Bearer), o direito é dele e o código sai junto; agente usa X-Credito. Sem conta, conserve acesso.codigo para reabrir ou vincular depois. Após vínculo somente a conta abre. Texto pronto reutiliza OCR; geração necessária incluída. Cotação desconhecida/alterada não cobra. 152 páginas = US$ 3,04. Corpo até 4096 bytes. Após 202 acompanhe por GET. Pagou e a gravação do direito falhou: 502 `pago_nao_registrado` com o `recibo` — guarde-o, o suporte entrega ou estorna. - **URL:** `https://staging.editalmd.com/api/documento/:id/geracao` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Parâmetros de caminho** - `id` (string, obrigatório) — ID positivo do documento retornado pela compra. Ex.: `2110000`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. - `X-PAYMENT` (string) — Autorização x402 do desafio 402. - `X-Credito` (string) — Token cred_… para descontar do saldo, como alternativa ao x402. - `Authorization` (string) — Bearer cred_… é alternativa ao X-Credito. A conta viaja em cookie, nunca em bearer. - `Idempotency-Key` (string) — Chave de tentativa, até 80 caracteres; preserve em retries de crédito do mesmo documento. **Corpo** (`application/json`) - `cotacao` (object) — Objeto recebido no GET/402: paginas, source_sha256 e preco_total_usd devem coincidir com a cotação atual. Obrigatório ao enviar autorização de pagamento. **Resposta `200`** - `documento_id` (int) — Documento solicitado. - `status` (string, opcional) — `pronto` quando a leitura pode ser aberta. - `error` (string, opcional) — `geracao_necessaria`, `extracao_em_andamento`, `geracao_falhou` ou causa da indisponibilidade. - `retry_after_s` (int, opcional) — Intervalo mínimo até o próximo GET de acompanhamento. - `processing` (object, opcional) — Progresso real: `progress.stage` (preparing, reading, verifying, packaging), `pages_total`, `pages_processed`, `pages_completed`, `pass`; `updated_at` e `elapsed_ms`. - `markdown_url` (string) — GET do Markdown, com o acesso comprado. - `geracao_url` (string) — GET para estado/cotação; POST para comprar acesso individual. - `acesso_comprado` (boolean) — Esta credencial pode ler o documento, independentemente do estado global do texto. → ver `boolean` em **Estruturas**. - `acesso` (object, opcional) — Após pagamento confirmado fora da sessão da conta: codigo privado e header X-Editalmd-Acesso. Guarde para reabrir ou para vincular a uma conta (POST /vincular). Não publique, não abre outro documento. - `preco_pagina_usd` (string) — US$ 0,02 por página no site e API (x402 ou crédito). - `cotacao` (object, pode ser null) — Páginas confirmadas no documento: paginas, source_sha256, preco_pagina_usd e preco_total_usd. Nulo quando não é possível cotar. - `pagamento` (object, opcional) — Quando cobrado: `recibo` da porta x402/crédito e `preco_usd`. Conserve mesmo se a origem falhar. **Erros** - `202` — Processamento em curso; acompanhe por GET, respeitando Retry-After. Nunca repita POST para fazer polling. - `400` — Corpo malformado ou campos desconhecidos. - `401` — Crédito inválido, ou `session_ended` (cookie de sessão vencida: entre de novo); nada cobrado. - `402` — Pagamento necessário ou recusado; anuncia x402, crédito e cotação. - `403` — `invalid_origin` / `invalid_csrf`: compra com o cookie da conta exige a mesma origem e X-CSRF-Token; nada cobrado. - `404` — Documento inexistente. - `409` — Cotação alterada/ausente, páginas desconhecidas ou geração indisponível; nada cobrado antes da autorização. - `413` — Corpo excedeu 4096 bytes. - `502` — Origem indisponível; não repita pagamento sem conferir o estado e o recibo. `pago_nao_registrado`: pagou e a gravação do direito falhou — guarde o `recibo`. - `503` — Pagamento sem configuração, `conta_indisponivel` ou `acesso_exige_pagamento` (documento nunca sai de graça); nada cobrado. **Exemplo** ```sh curl -s -X POST https://staging.editalmd.com/api/documento/1993401/geracao -H "Content-Type: application/json" -d '{}' ``` ### `GET /exemplos` Galeria de cinco documentos reais já processados: leitura, original, Markdown e ZIP gratuitos. - **URL:** `https://staging.editalmd.com/exemplos` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** HTML com exemplos prontos. Abrir ou baixar não gera processamento nem cobrança. **Exemplo** ```sh curl -fsS https://staging.editalmd.com/exemplos ``` ### `GET /api/exemplos` Cinco exemplos prontos, com procedência, páginas, imagens, SHA-256 e links de leitura e download. - **URL:** `https://staging.editalmd.com/api/exemplos` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** - `exemplos` (object[]) — documento_id, compra_id, titulo, local, descricao, paginas, imagens, sha256, gratuito=true, leitura_url, markdown_url, manifesto_url, original_url, arquivos_url e pacote_url. **Exemplo** ```sh curl -fsS https://staging.editalmd.com/api/exemplos ``` ### `POST /api/documento/:id/cobranca` Reserva endereço/QR exclusivo para comprar seu acesso com USDC na Base. Consulte GET /geracao e envie cotacao. Cada comprador paga, inclusive pronto. O serviço confirma USDC no bloco safe da Base; safe aguarda inclusão na L1, sem finalidade absoluta. Envie em até 30 min; observação por 24 h. Pagamento tardio, rede/moeda errada ou extração falha exige atendimento. Carteira/corretora pode cobrar taxa. Mesma X-Cobranca conserva cobrança/endereço. GET pago devolve acesso.codigo e cookie; para guardar na conta, POST /api/documento/:id/vincular com esse código (o site faz isso sozinho para quem está conectado). O pagamento simulado do ambiente de desenvolvimento não vale para depósito. - **URL:** `https://staging.editalmd.com/api/documento/:id/cobranca` - **Auth:** `cobranca` — X-Cobranca: token de 64 hex minúsculos escolhido aleatoriamente pelo cliente; conserve para consultar e retomar sua cobrança. **Parâmetros de caminho** - `id` (string, obrigatório) — ID positivo do documento. Ex.: `2110000`. **Headers** - `X-Cobranca` (string, obrigatório) — 32 bytes aleatórios em 64 caracteres hex minúsculos. Gere e guarde antes do POST; reutilize no GET e em retries. Segredo de acesso à sua cobrança. **Corpo** (`application/json`) - `cotacao` (object, obrigatório) — Cotação recebida no GET /geracao: paginas, source_sha256 e preco_total_usd. **Resposta `200`** - `acesso` (object, opcional) — Após pagamento confirmado fora da sessão da conta: codigo privado e header X-Editalmd-Acesso. Guarde para reabrir ou para vincular a uma conta (POST /vincular). Não publique, não abre outro documento. - `id` (string) — Identificador da cobrança, para atendimento. - `documento_id` (int) — Documento cotado. - `rede` (string) — base; base-sepolia só no ambiente de desenvolvimento. - `chain_id` (int) — 8453 em produção, 84532 no teste. - `moeda` (string) — USDC. - `contrato` (string) — Contrato USDC aceito nesta rede. - `endereco` (string) — Endereço exclusivo desta cobrança. Nunca reutilize para outra. - `paginas` (int) — Páginas físicas confirmadas no documento. - `preco_total_usd` (string) — Páginas × US$ 0,02; valor em USDC equivalente. - `recebido_usdc` (string) — Soma de transferências confirmadas, seis casas decimais. - `restante_usdc` (string) — Valor que falta; taxas da carteira/corretora não entram. - `status` (string) — aguardando, expirada, pago, solicitada, gerando, pronto ou revisao. - `expira_em` (string) — ISO UTC: envie em até 30 minutos. - `verificada_em` (string, pode ser null) — Última observação da rede pelo servidor. - `detalhe` (string, pode ser null) — Orientação quando precisar de atendimento. - `retry_after_s` (int) — 30 segundos entre consultas. - `pagamento_uri` (string, pode ser null) — URI EIP-681 para carteira/QR, com rede, contrato, destinatário e valor restante. Ausente após vencer ou pagar. - `transacoes` (object[]) — hash, valor_usdc e url do explorador para cada transferência. **Erros** - `400` — Documento/corpo inválido ou cotação ausente. - `401` — X-Cobranca inválido. - `404` — Cobrança inexistente para este documento e token. - `409` — Cotação alterada, páginas desconhecidas ou teto de cobranças atingido; não envie dinheiro. - `413` — Corpo maior que 4096 bytes. - `502` — Origem indisponível. - `503` — Checkout por depósito indisponível. **Exemplo** ```sh curl -s -X POST https://staging.editalmd.com/api/documento/1993401/cobranca -H 'X-Cobranca: SEU_TOKEN_64_HEX' -H 'Content-Type: application/json' --data @cotacao.json ``` ### `GET /api/documento/:id/cobranca` Consulta endereço, confirmação, recibo e liberação da sua cobrança gratuitamente. Reutilize X-Cobranca e respeite Retry-After. Consulta não escreve nem faz RPC blockchain. Quando gerando, use GET /geracao para fases/páginas; pronto libera os links de leitura. Em revisao, conserve ID e transações para atendimento, sem pagar novamente. - **URL:** `https://staging.editalmd.com/api/documento/:id/cobranca` - **Auth:** `cobranca` — X-Cobranca: token de 64 hex minúsculos escolhido aleatoriamente pelo cliente; conserve para consultar e retomar sua cobrança. **Parâmetros de caminho** - `id` (string, obrigatório) — ID positivo do documento. Ex.: `2110000`. **Headers** - `X-Cobranca` (string, obrigatório) — 32 bytes aleatórios em 64 caracteres hex minúsculos. Gere e guarde antes do POST; reutilize no GET e em retries. Segredo de acesso à sua cobrança. **Resposta `200`** - `acesso` (object, opcional) — Após pagamento confirmado fora da sessão da conta: codigo privado e header X-Editalmd-Acesso. Guarde para reabrir ou para vincular a uma conta (POST /vincular). Não publique, não abre outro documento. - `id` (string) — Identificador da cobrança, para atendimento. - `documento_id` (int) — Documento cotado. - `rede` (string) — base; base-sepolia só no ambiente de desenvolvimento. - `chain_id` (int) — 8453 em produção, 84532 no teste. - `moeda` (string) — USDC. - `contrato` (string) — Contrato USDC aceito nesta rede. - `endereco` (string) — Endereço exclusivo desta cobrança. Nunca reutilize para outra. - `paginas` (int) — Páginas físicas confirmadas no documento. - `preco_total_usd` (string) — Páginas × US$ 0,02; valor em USDC equivalente. - `recebido_usdc` (string) — Soma de transferências confirmadas, seis casas decimais. - `restante_usdc` (string) — Valor que falta; taxas da carteira/corretora não entram. - `status` (string) — aguardando, expirada, pago, solicitada, gerando, pronto ou revisao. - `expira_em` (string) — ISO UTC: envie em até 30 minutos. - `verificada_em` (string, pode ser null) — Última observação da rede pelo servidor. - `detalhe` (string, pode ser null) — Orientação quando precisar de atendimento. - `retry_after_s` (int) — 30 segundos entre consultas. - `pagamento_uri` (string, pode ser null) — URI EIP-681 para carteira/QR, com rede, contrato, destinatário e valor restante. Ausente após vencer ou pagar. - `transacoes` (object[]) — hash, valor_usdc e url do explorador para cada transferência. **Erros** - `400` — Documento/corpo inválido ou cotação ausente. - `401` — X-Cobranca inválido. - `404` — Cobrança inexistente para este documento e token. - `409` — Cotação alterada, páginas desconhecidas ou teto de cobranças atingido; não envie dinheiro. - `413` — Corpo maior que 4096 bytes. - `502` — Origem indisponível. - `503` — Checkout por depósito indisponível. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/documento/1993401/cobranca -H 'X-Cobranca: SEU_TOKEN_64_HEX' ``` ### `GET /api/documento/:id/dossie` Dados estruturados: exigências, itens, atestados, prazos, condições e evidências por página. Dossiê incluído no acesso documental, sem nova análise ao consultar. Dados parciais informam cobertura; exportação exige versão concluída. - **URL:** `https://staging.editalmd.com/api/documento/:id/dossie` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento na ficha da compra. Ex.: `9558909`. **Query** - `v` (string) — SHA-256 do texto exibido; recusa versão diferente. - `after` (integer) — Cursor next anterior, padrão 0. - `limit` (integer) — 1 a 30 registros, padrão 30. - `kind` (string) — identity, item, requirement, attestation, deadline ou obligation. - `format` (string) — page (padrão) ou json para download completo sem filtro/paginação. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** Página: data.version, data.complete, data.facts e data.next. Fatos conservam details tipados, applicability, exceptions, evidence (page/start/end/quote) e references. Duração exige quantidade e unidade associadas na evidência; duration_verification identifica correção ou revisão necessária, sem alterar a fonte. format=json: schema licitech-document-dossier-v1, version e facts completos, até 16 MiB. **Erros** - `400` — Consulta inválida. - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. - `409` — Versão mudou ou exportação ainda em preparo. - `502` — Origem indisponível. **Exemplo** ```sh curl -fsS "https://staging.editalmd.com/api/documento/1993401/dossie?kind=deadline&limit=20" ``` ### `GET /licitacoes/` Navegação pública do acervo por modalidade, UF, data e município. - **URL:** `https://staging.editalmd.com/licitacoes/` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** HTML com navegação do EditalMD. Cada recorte oferece links para JSON, Markdown e OKF dos metadados. **Exemplo** ```sh curl -fsS https://staging.editalmd.com/licitacoes/ ``` ### `GET /licitacoes/compra/:id/` Ficha pública com documentos em modo de leitura: Markdown paginado, original e arquivos. - **URL:** `https://staging.editalmd.com/licitacoes/compra/:id/` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador da compra. Ex.: `1996190`. **Query** - `doc` (integer) — Documento a abrir. - `pagina` (integer) — Página inicial, a partir de 1. - `vista` (string) — leitura, markdown, dados, exigencias, original, arquivos ou procedencia. - `tipo` (string) — Subaba: dados usa identity, item ou deadline; exigencias usa requirement, attestation ou obligation. **Resposta `200`** HTML navegável. O leitor usa /api/compra/:id e a família /api/documento/:id; agentes devem consumir essas APIs diretamente. **Erros** - `404` — Compra não encontrada. **Exemplo** ```sh curl -fsS https://staging.editalmd.com/licitacoes/compra/1996190/ ``` ### `GET /api/documento/:id/original` Baixar o original preservado, com o acesso comprado. Entrega o arquivo disponível no acervo, sem iniciar nova extração. - **URL:** `https://staging.editalmd.com/api/documento/:id/original` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento na ficha da compra. Ex.: `9558909`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** Binário original (PDF, ZIP ou outro formato), até 96 MiB, com MIME e nome do arquivo. **Erros** - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. - `502` — Origem indisponível. **Exemplo** ```sh curl -fsS https://staging.editalmd.com/api/documento/9558909/original -o original ``` ### `GET /api/documento/:id/partes` Arquivos internos disponíveis no documento comprado. - **URL:** `https://staging.editalmd.com/api/documento/:id/partes` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento na ficha da compra. Ex.: `9558909`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** - `data` (object) — document_id e parts (até 200): id, idx, label, content_type, size_bytes, page_count, page_offset e arquivo_url relativo a /api/documento/:id/partes/:partId/arquivo. Lista vazia indica documento sem peças. **Erros** - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. - `409` — Arquivo ou índice ainda indisponível. - `422` — Pacote não pôde ser lido. - `502` — Origem indisponível. - `503` — Acervo ocupado; respeite Retry-After. **Exemplo** ```sh curl -fsS https://staging.editalmd.com/api/documento/9558909/partes ``` ### `GET /api/documento/:id/partes/:partId/arquivo` Abrir ou baixar uma peça original com o acesso comprado ao documento. - **URL:** `https://staging.editalmd.com/api/documento/:id/partes/:partId/arquivo` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento na ficha da compra. Ex.: `9558909`. - `partId` (string, obrigatório) — id da peça retornado em partes. Ex.: `1`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** Binário pronto, até 96 MiB. PDF pode ser exibido no navegador; outros formatos podem ser baixados. **Erros** - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. - `502` — Origem indisponível. **Exemplo** ```sh curl -fsS https://staging.editalmd.com/api/documento/9558909/partes/1/arquivo -o arquivo.pdf ``` ### `GET /api/documento/:id/leitura` Manifesto do documento comprado: páginas físicas, imagens e hashes da extração atual. Somente recursos prontos. Não inicia OCR. `document_approved: false` identifica a extração automática e não impede sua leitura. - **URL:** `https://staging.editalmd.com/api/documento/:id/leitura` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento na ficha da compra. Ex.: `9558909`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** - `data` (object) — schema licitech-document-package-v1; document_id, source_sha256, text_sha256, markdown_sha256, pages (number/start/end), images (sha256/filename/size_bytes/mime/width/height), occurrences (page/reference/start/end/sha256). Offsets UTF-16 de fonte.md. **Erros** - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. - `409` — Versão do texto alterada; abra o manifesto atual. - `502` — Origem indisponível. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/documento/9558909/leitura ``` ### `GET /api/documento/:id/pacote` Baixar ZIP com Markdown e imagens do documento comprado para leitura fora do site. - **URL:** `https://staging.editalmd.com/api/documento/:id/pacote` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento na ficha da compra. Ex.: `9558909`. **Query** - `v` (string) — text_sha256 do manifesto; fixa a versão exibida no leitor. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** `application/zip`, até 96 MiB: documento.md, pasta imagens, fonte.md literal, manifesto.json e LEIA-ME.txt. Mantenha a pasta imagens junto do Markdown. **Erros** - `400` — Versão inválida. - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. - `409` — Versão do texto alterada; abra o manifesto atual. - `502` — Origem indisponível. **Exemplo** ```sh curl -fsS https://staging.editalmd.com/api/documento/9558909/pacote -o documento.zip ``` ### `GET /api/documento/:id/imagens/:version/:imageSha` Imagem PNG/JPEG do documento comprado, conferida por hash. - **URL:** `https://staging.editalmd.com/api/documento/:id/imagens/:version/:imageSha` - **Auth:** `acesso` — Sessão da conta com aquisição vinculada, X-Editalmd-Acesso de compra anônima, ou X-Editalmd-Avaliacao junto de X-Agent-Pass para o documento patrocinado. Depois do vínculo da compra, exige conta. Cinco exemplos são livres. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do documento na ficha da compra. Ex.: `9558909`. - `version` (string, obrigatório) — text_sha256 do manifesto. Ex.: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`. - `imageSha` (string, obrigatório) — sha256 da imagem presente no manifesto. Ex.: `bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb`. **Headers** - `X-Agent-Pass` (string) — Credencial individual do agente, obrigatória junto de X-Editalmd-Avaliacao. - `X-Editalmd-Avaliacao` (string) — evaluation.access_code do premium patrocinado, exclusivo deste documento e agente, com expiração. Use junto de X-Agent-Pass; não é recibo ou compra. - `X-Editalmd-Acesso` (string) — Código privado em acesso.codigo após pagamento de quem não está na conta; até 4096 caracteres. Autoriza este documento ao portador. Compra feita com a sessão da conta não emite código: vale o direito global da conta (cookie HttpOnly), e o do convidado edm_… vale com o token. Recibo público não concede acesso. **Resposta `200`** `image/png` ou `image/jpeg`, até 20 MiB por imagem. Não aceita URLs nem caminhos externos. **Erros** - `402` — Sem acesso comprado ou patrocinado válido. Use avaliação individual, compre via POST /api/documento/:id/geracao ou depósito; cinco exemplos são gratuitos. - `404` — Aquisição não encontrada para a conta autenticada, ou documento/recurso ausente. - `409` — Versão do texto alterada; abra o manifesto atual. - `502` — Origem indisponível. **Exemplo** ```sh curl -fsS https://staging.editalmd.com/api/documento/9558909/imagens/TEXT_SHA256/IMAGE_SHA256 -o imagem.png ``` ### `GET /api/precos` O preço que ganha para um item parecido: mediana, quartis, desconto sobre a referência, quem vence e quem compra. Grátis. Consulte resultados homologados por descrição do item. Além da amostra (`itens`), a resposta traz `resumo` (n, mediana, p25/p75, menor, maior, desconto mediano sobre o valor estimado pelo órgão, participação de ME/EPP, fornecedores e compradores distintos), `por_uf`, `por_mes`, `vencedores` (top 10 por itens ganhos e valor, com porte) e `compradores` (top 10 órgãos, com a última compra) — calculados sobre todos os candidatos do período, não só sobre a amostra. `amostra` diz o critério (até 2.000 itens mais parecidos pelo texto) e se bateu no teto. Unidade de medida é a publicada, sem normalização: compare `unidade` antes de comparar preço. Valores sem saneamento — a exclusão de inexequíveis/excessivos é decisão de quem pesquisa. Pessoa física vencedora sai sem CPF. Aceita também POST, PUT ou PATCH com os mesmos parâmetros em JSON ou formulário; `query`, `termo`, `busca` e `search` valem como `q`, `estado` como `uf`, `limit` como `limite`. Todo 400 traz `exemplo` e `doc`. `Accept: text/html` abre a aba Preços pagos com a consulta. - **URL:** `https://staging.editalmd.com/api/precos` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Query** - `q` (string, obrigatório) — Descrição do item; mínimo 3 letras, até 200. - `uf` (string) — Sigla da UF do órgão comprador. - `meses` (int) — Janela de homologação em meses, 1 a 36. Padrão: `12`. - `catmat` (string) — Código do item no catálogo do governo, até 64 caracteres. - `limite` (int) — 1 a 100 itens. Padrão: `50`. **Resposta `200`** Estrutura: `Precos`. - `consulta` (PrecosConsulta) — O pedido como a origem o entendeu. → ver `PrecosConsulta` em **Estruturas**. - `estatisticas` (PrecosEstatisticas) — Sobre os valores unitários da amostra devolvida em `itens`. → ver `PrecosEstatisticas` em **Estruturas**. - `resumo` (PrecosResumo, pode ser null) — Sobre todos os candidatos do período (não só a amostra). Nulo quando nada casou. → ver `PrecosResumo` em **Estruturas**. - `por_uf` (PrecosPorUf[]) — Um por UF do órgão comprador, mais resultados primeiro. → ver `PrecosPorUf` em **Estruturas**. - `por_mes` (PrecosPorMes[]) — Um por mês do período, do mais antigo ao mais recente; mês sem homologação vem com `n: 0`. → ver `PrecosPorMes` em **Estruturas**. - `vencedores` (PrecoVencedor[]) — Até 10 fornecedores, por itens ganhos e depois por valor. → ver `PrecoVencedor` em **Estruturas**. - `compradores` (PrecoComprador[]) — Até 10 órgãos, por itens comprados e depois por valor. → ver `PrecoComprador` em **Estruturas**. - `amostra` (PrecosAmostra, pode ser null) — Como os candidatos foram escolhidos e se bateram no teto. → ver `PrecosAmostra` em **Estruturas**. - `itens` (PrecoHomologado[]) — Resultados por relevância e homologação mais recente. → ver `PrecoHomologado` em **Estruturas**. - `base_legal` (string) — A base legal da pesquisa de preços que este dado atende. - `pago` (bool) — Sempre `false`: consultar preços não custa. **Erros** - `400` — Termo com menos de 3 letras, UF, meses, limite ou catmat fora do contrato — com `exemplo` e `doc`. - `502` — Origem indisponível. - `503` — Busca demorada: `busca_demorada`, com `Retry-After` — refine o termo ou filtre por UF. **Exemplo** ```sh curl -s 'https://staging.editalmd.com/api/precos?q=papel%20a4%20resma&uf=MG&meses=12' ``` ## Acompanhar ### `POST /api/dono` Cria o convidado (token edm_…) que abre alertas e vigias, e o segredo que assina os webhooks. Sem cadastro. O token é emitido e assinado pela biblioteca de conta, com teto por rede e por hora, para a franquia grátis não virar infinita. Ele é mostrado uma única vez e não tem recuperação — entre na conta e traga as listas para ela (`POST /api/auth/claim`, que a página da conta faz sozinha ao entrar) para não depender dele. O `webhook_segredo` pode ser relido em `GET /api/dono`. Todo POST do webhook leva `webhook-id`, `webhook-timestamp` (segundos Unix) e `webhook-signature: v1,`: HMAC-SHA256 de `id.timestamp.corpo` com a chave do seu `whsec_…` (o base64 depois do prefixo). É o padrão Standard Webhooks — qualquer biblioteca dele confere; rejeite timestamp fora de 5 minutos. Depois de `POST /api/dono/segredo`, o anterior ainda assina por 24 h (duas partes `v1,` no cabeçalho). - **URL:** `https://staging.editalmd.com/api/dono` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** Estrutura: `Dono`. - `token` (string) — `edm_…` emitido pela biblioteca de conta — guarde; não é mostrado de novo nem recuperável. - `aviso` (string) — Lembrete de guardar o token e como usá-lo. - `webhook_segredo` (string) — `whsec_…` — assina todo POST de webhook (Standard Webhooks). Releia em `GET /api/dono`; rotacione em `POST /api/dono/segredo`. - `webhook_assinatura` (string) — Como conferir a assinatura, em uma linha. - `franquia` (object) — `alertas_gratis` e `vigias_gratis` incluídos. **Erros** - `429` — A rede passou do teto de convidados da hora. - `503` — Conta ou banco indisponível. **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/api/dono ``` ### `GET /api/dono` O estado do dono: conta ou convidado, e-mail dos avisos, franquia e o segredo que assina os webhooks. Todo POST do webhook leva `webhook-id`, `webhook-timestamp` (segundos Unix) e `webhook-signature: v1,`: HMAC-SHA256 de `id.timestamp.corpo` com a chave do seu `whsec_…` (o base64 depois do prefixo). É o padrão Standard Webhooks — qualquer biblioteca dele confere; rejeite timestamp fora de 5 minutos. Depois de `POST /api/dono/segredo`, o anterior ainda assina por 24 h (duas partes `v1,` no cabeçalho). - **URL:** `https://staging.editalmd.com/api/dono` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Resposta `200`** - `tipo` (string) — `conta` (sessão) ou `convidado` (token edm_…). - `email_alertas` (string, pode ser null) — E-mail verificado da conta, mascarado, para onde vão os avisos do canal e-mail; nulo no convidado. - `webhook_segredo` (string) — `whsec_…` — a chave que assina cada POST de webhook. - `assinatura` (string) — Como conferir a assinatura, em uma linha. - `franquia` (object) — `alertas_gratis` e `vigias_gratis` incluídos. **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/dono -H "Authorization: Bearer $EDM" ``` ### `POST /api/dono/segredo` Rotaciona o segredo do webhook. O anterior ainda assina por 24 h, para trocar sem janela de falha. Durante as 24 h o cabeçalho `webhook-signature` traz duas partes `v1,…`: uma com o novo, outra com o anterior. Basta o receptor aceitar qualquer uma que bata. - **URL:** `https://staging.editalmd.com/api/dono/segredo` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Resposta `200`** - `webhook_segredo` (string) — O novo `whsec_…`. - `anterior_valido_ate` (string) — Até quando o segredo anterior ainda assina (ISO 8601). **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/api/dono/segredo -H "Authorization: Bearer $EDM" ``` ### `POST /api/alertas/previa` Testa termos e filtros ou sugere termos pelo CNPJ, sem criar alerta. - **URL:** `https://staging.editalmd.com/api/alertas/previa` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Corpo** (`application/json`) - `termos` (string) — 3 a 200 caracteres; obrigatório sem CNPJ. - `cnpj` (string) — CNPJ para sugerir até 8 famílias de termos, sem ativá-las. - `uf` (string) — Sigla da UF. - `filtros` (FiltrosInteresse) — Recorte adicional: modalidades, municípios, exclusões, valores e propostas abertas. PATCH substitui o recorte inteiro; {} limpa. **Exemplo de corpo** ```json { "termos": "uniforme escolar", "uf": "GO", "filtros": { "modalidades": [ 6 ] } } ``` **Resposta `200`** - `sugestoes` (object[]) — Família, nome, termos editáveis e CNAEs; só no modo CNPJ. - `itens` (Compra[]) — Até 20 compras dos últimos 7 dias; cada uma tem url para a ficha. → ver `Compra` em **Estruturas**. - `aviso` (string) — Limites da amostra ou da sugestão. - `periodo_dias` (int, opcional) — 7, só na amostra por termos. - `limite` (int, opcional) — 20, só na amostra por termos. **Erros** - `400` — Termos, CNPJ, UF ou filtros inválidos. - `404` — Empresa não encontrada. - `503` — Origem indisponível. **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/api/alertas/previa -H 'content-type: application/json' -d '{"termos":"uniforme escolar"}' ``` ### `GET /api/salvas` Lista até 200 licitações salvas pelo dono, gratuitamente. - **URL:** `https://staging.editalmd.com/api/salvas` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Resposta `200`** - `itens` (CompraSalva[]) — Mais recentes primeiro; retrato obtido ao salvar. → ver `CompraSalva` em **Estruturas**. - `limite` (int) — 200 por dono. **Erros** - `401` — Token de dono ausente ou inválido. - `503` — Banco indisponível. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/salvas -H "Authorization: Bearer $EDM" ``` ### `GET /api/salvas/:id` Consulta uma licitação salva pelo dono. Salvar não cria vigia nem notificação. O cliente fornece somente o ID; o retrato vem do acervo. - **URL:** `https://staging.editalmd.com/api/salvas/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador da compra no acervo. Ex.: `42`. **Resposta `200`** - `salva` (CompraSalva) — Licitação salva. → ver `CompraSalva` em **Estruturas**. **Erros** - `401` — Token de dono ausente ou inválido. - `404` — Compra não encontrada. - `409` — Limite de 200 salvas atingido. - `503` — Banco, origem ou orçamento diário indisponível. **Exemplo** ```sh curl -s -XGET https://staging.editalmd.com/api/salvas/42 -H "Authorization: Bearer $EDM" ``` ### `PUT /api/salvas/:id` Salva a licitação gratuitamente; repetir não duplica. Salvar não cria vigia nem notificação. O cliente fornece somente o ID; o retrato vem do acervo. - **URL:** `https://staging.editalmd.com/api/salvas/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador da compra no acervo. Ex.: `42`. **Resposta `200`** - `salva` (CompraSalva) — Licitação salva. → ver `CompraSalva` em **Estruturas**. **Erros** - `401` — Token de dono ausente ou inválido. - `404` — Compra não encontrada. - `409` — Limite de 200 salvas atingido. - `503` — Banco, origem ou orçamento diário indisponível. **Exemplo** ```sh curl -s -XPUT https://staging.editalmd.com/api/salvas/42 -H "Authorization: Bearer $EDM" ``` ### `DELETE /api/salvas/:id` Remove a licitação da lista pessoal; repetir é seguro. Salvar não cria vigia nem notificação. O cliente fornece somente o ID; o retrato vem do acervo. - **URL:** `https://staging.editalmd.com/api/salvas/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador da compra no acervo. Ex.: `42`. **Resposta `200`** 204 sem corpo. **Erros** - `401` — Token de dono ausente ou inválido. - `404` — Compra não encontrada. - `409` — Limite de 200 salvas atingido. - `503` — Banco, origem ou orçamento diário indisponível. **Exemplo** ```sh curl -s -XDELETE https://staging.editalmd.com/api/salvas/42 -H "Authorization: Bearer $EDM" ``` ### `POST /api/alertas` Cria alertas de compra nova: por termos do objeto e UF, ou pelo CNPJ da empresa (um alerta por família de atividade), entregues por pull, webhook ou e-mail. Dois modos. Por `termos`: espaço exige todas as palavras, `|` aceita qualquer uma do grupo (`uniforme|fardamento escolar`). Por `cnpj`: o cadastro da empresa informa as atividades (CNAE), o dicionário (`GET /api/cnaes`) transforma cada CNAE numa família de termos e sai um alerta por família distinta, principal primeiro, até `max_familias`; CNAE fora do dicionário não vira alerta e é listado em `empresa.cnaes` com `familia: null`. O primeiro alerta ativo é grátis (`FRANQUIA_ALERTAS`); os seguintes custam `PRECO_ALERTA` por 30 dias cada — no modo CNPJ, numa cobrança só (N × preço), por x402 ou crédito. O cron confere a cada 30 minutos. Canal e-mail exige a sessão da conta — o aviso vai para o e-mail verificado dela, sem código de confirmação — e só existe com `EMAIL_ALERTAS=1`. - **URL:** `https://staging.editalmd.com/api/alertas` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Corpo** (`application/json`) - `termos` (string) — Palavras do objeto da compra (3 a 200 letras); espaço = todas, `|` = qualquer uma do grupo. Obrigatório sem `cnpj`; ignorado com `cnpj`. - `cnpj` (string) — CNPJ da empresa (14 dígitos, com ou sem pontuação): os termos saem das atividades (CNAE) dela, um alerta por família. - `max_familias` (int) — Só com `cnpj`: quantas famílias viram alerta, principal primeiro (1 a 8). Padrão: `8`. - `uf` (string) — Sigla da UF para restringir; sem UF vale o Brasil inteiro. - `filtros` (FiltrosInteresse) — Recorte adicional: modalidades, municípios, exclusões, valores e propostas abertas. PATCH substitui o recorte inteiro; {} limpa. - `canal` (string) — `pull` (só a API), `webhook` (POST na sua URL https) ou `email` (e-mail verificado da conta; exige sessão). Padrão: `pull`. Valores: `pull`, `webhook`, `email`. - `destino` (string) — URL https pública na porta 443, sem credencial (webhook). Ignorado no pull e no e-mail. **Exemplo de corpo** ```json { "termos": "uniforme|fardamento escolar", "uf": "GO", "canal": "pull" } ``` **Resposta `200`** - `alerta` (Alerta, opcional) — O alerta criado (modo termos). → ver `Alerta` em **Estruturas**. - `alertas` (Alerta[], opcional) — Os alertas criados, um por família (modo CNPJ). → ver `Alerta` em **Estruturas**. - `empresa` (Empresa, opcional) — A ficha resumida e cada CNAE com a família que o acionou (modo CNPJ). → ver `Empresa` em **Estruturas**. - `nao_criados` (FamiliaNaoCriada[], opcional) — Famílias que ficaram de fora por `max_familias` (modo CNPJ). → ver `FamiliaNaoCriada` em **Estruturas**. - `pagamento` (object) — `via` (franquia, credito ou x402), `preco_usd`, `pago_ate` e, no modo CNPJ, `alertas_pagos` e `preco_unitario_usd`. **Erros** - `400` — Termos, CNPJ, UF, canal ou destino inválidos. - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `402` — Acima da franquia sem pagamento — `accepts[]` do x402 e o caminho do crédito. - `403` — `email_exige_conta`: canal e-mail sem a sessão da conta (convidado não tem e-mail); ou `invalid_origin`/`invalid_csrf` na escrita com o cookie da conta. - `404` — CNPJ não encontrado na base consultada. - `422` — CNPJ sem nenhuma atividade no dicionário: crie por termos (a resposta traz os CNAEs). - `502` — `pago_nao_registrado`: o pagamento entrou e a gravação da compra falhou — guarde o `recibo`; o alerta não foi criado. - `503` — Canal e-mail desligado, ou a consulta ao CNPJ indisponível agora (`retry_after`). **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/api/alertas -H "Authorization: Bearer $EDM" -H 'content-type: application/json' -d '{"cnpj":"00.394.460/0001-41","uf":"GO","canal":"pull"}' ``` ### `GET /api/alertas` Lista os alertas deste dono, os mais novos primeiro. - **URL:** `https://staging.editalmd.com/api/alertas` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Resposta `200`** - `itens` (Alerta[]) — Até 50 alertas do dono. → ver `Alerta` em **Estruturas**. - `total` (int) — Total de alertas deste dono, incluindo pausados; não se limita aos 50 itens da resposta. - `franquia_alertas` (int) — Quantos alertas ativos são grátis. **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/alertas -H "Authorization: Bearer $EDM" ``` ### `GET /api/alertas/:id` Um alerta do dono, com os filtros e a data da última verificação. - **URL:** `https://staging.editalmd.com/api/alertas/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do alerta, devolvido na criação. Ex.: `9f3c…`. **Resposta `200`** - `alerta` (Alerta) — O alerta. → ver `Alerta` em **Estruturas**. **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `404` — Alerta inexistente ou de outro dono. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/alertas/$ID -H "Authorization: Bearer $EDM" ``` ### `GET /api/alertas/:id/compras` As compras que já casaram com o alerta — é o canal pull, e a prova do que foi entregue. - **URL:** `https://staging.editalmd.com/api/alertas/:id/compras` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do alerta. Ex.: `9f3c…`. **Query** - `limite` (int) — 1 a 100 (padrão 50), IDs mais altos primeiro. - `antes_compra` (int) — Use proximo_antes da página anterior para continuar. **Resposta `200`** - `alerta` (Alerta) — O alerta. → ver `Alerta` em **Estruturas**. - `itens` (AlertaCompra[]) — Compras casadas, com o status da entrega. → ver `AlertaCompra` em **Estruturas**. - `limite` (int) — Teto aplicado. - `proximo_antes` (int, pode ser null) — Cursor da próxima página; nulo no fim. **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `404` — Alerta inexistente ou de outro dono. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s "https://staging.editalmd.com/api/alertas/$ID/compras?limite=20" -H "Authorization: Bearer $EDM" ``` ### `PATCH /api/alertas/:id` Pausa, reativa ou muda termos, UF, filtros, canal e destino de um alerta. - **URL:** `https://staging.editalmd.com/api/alertas/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do alerta. Ex.: `9f3c…`. **Corpo** (`application/json`) - `ativo` (bool) — `false` pausa sem apagar; `true` reativa. - `termos` (string) — Novos termos do objeto (3 a 200 letras; `|` = qualquer uma do grupo). - `uf` (string) — Nova UF; vazio tira a restrição. - `filtros` (FiltrosInteresse) — Recorte adicional: modalidades, municípios, exclusões, valores e propostas abertas. PATCH substitui o recorte inteiro; {} limpa. - `canal` (string) — Novo canal: `pull`, `webhook` ou `email` (e-mail verificado da conta; exige sessão). Valores: `pull`, `webhook`, `email`. - `destino` (string) — Nova URL https na porta 443 (webhook). Ignorado no pull e no e-mail. **Exemplo de corpo** ```json { "ativo": false } ``` **Resposta `200`** - `alerta` (Alerta) — O alerta depois da mudança. → ver `Alerta` em **Estruturas**. **Erros** - `400` — Nada para mudar ou valor inválido. - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `402` — Reativar além da franquia, fora da janela paga, sem pagamento — `accepts[]` do x402 e o caminho do crédito. - `403` — `email_exige_conta`: canal e-mail sem a sessão da conta; ou `invalid_origin`/`invalid_csrf` na escrita com o cookie da conta. - `404` — Alerta inexistente ou de outro dono. - `502` — `pago_nao_registrado`: o pagamento da reativação entrou e a gravação falhou — guarde o `recibo`; o alerta segue pausado. - `503` — Canal e-mail desligado. **Exemplo** ```sh curl -s -XPATCH https://staging.editalmd.com/api/alertas/$ID -H "Authorization: Bearer $EDM" -H 'content-type: application/json' -d '{"ativo":false}' ``` ### `DELETE /api/alertas/:id` Apaga o alerta e o histórico de compras casadas. Sem volta. - **URL:** `https://staging.editalmd.com/api/alertas/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do alerta. Ex.: `9f3c…`. **Resposta `200`** 204 sem corpo. **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `404` — Alerta inexistente ou de outro dono. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s -XDELETE https://staging.editalmd.com/api/alertas/$ID -H "Authorization: Bearer $EDM" ``` ### `POST /api/vigias` Vigia uma compra: fotografa agora e avisa quando mudar — documento novo, suspensão, prazo adiado, valor — e nos prazos. A primeira vigia ativa é grátis (`FRANQUIA_VIGIAS`); as seguintes custam `PRECO_VIGIA` até 30 dias após o encerramento. As verificações são periódicas; confira a data da última verificação na vigia. Avisos `prazo_impugnacao` (no dia) e `prazo_proposta` (24 h antes) saem uma vez cada. - **URL:** `https://staging.editalmd.com/api/vigias` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Corpo** (`application/json`) - `compra_id` (int, obrigatório) — Identificador da compra no acervo, vindo da busca. - `canal` (string) — `pull` (ler em `/eventos`), `webhook` ou `email` (e-mail verificado da conta; exige sessão). Padrão: `pull`. Valores: `pull`, `webhook`, `email`. - `destino` (string) — URL https pública na porta 443, sem credencial (webhook). Ignorado no pull e no e-mail. **Exemplo de corpo** ```json { "compra_id": 42, "canal": "pull" } ``` **Resposta `200`** - `vigia` (Vigia) — A vigia criada. → ver `Vigia` em **Estruturas**. - `snapshot` (Snapshot) — A fotografia inicial da compra. → ver `Snapshot` em **Estruturas**. - `pagamento` (object) — `via` (franquia, credito ou x402), `preco_usd` e `pago_ate`. **Erros** - `400` — `compra_id`, canal ou destino inválidos. - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `402` — Acima da franquia sem pagamento — `accepts[]` do x402 e o caminho do crédito. - `403` — `email_exige_conta`: canal e-mail sem a sessão da conta; ou `invalid_origin`/`invalid_csrf` na escrita com o cookie da conta. - `404` — Compra não encontrada no acervo. - `502` — `pago_nao_registrado`: o pagamento entrou e a gravação da compra falhou — guarde o `recibo`; a vigia não foi criada. - `503` — Canal e-mail desligado, ou origem indisponível. **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/api/vigias -H "Authorization: Bearer $EDM" -H 'content-type: application/json' -d '{"compra_id":42}' ``` ### `GET /api/vigias` Lista as vigias deste dono, as mais novas primeiro. - **URL:** `https://staging.editalmd.com/api/vigias` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Resposta `200`** - `itens` (Vigia[]) — Até 50 vigias do dono. → ver `Vigia` em **Estruturas**. - `franquia_vigias` (int) — Quantas vigias ativas são grátis. **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/vigias -H "Authorization: Bearer $EDM" ``` ### `GET /api/vigias/:id` Uma vigia do dono com a fotografia mais recente da compra. - **URL:** `https://staging.editalmd.com/api/vigias/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador da vigia, devolvido na criação. Ex.: `2b7e…`. **Resposta `200`** - `vigia` (Vigia) — A vigia. → ver `Vigia` em **Estruturas**. - `snapshot` (Snapshot) — O que o cron viu por último. → ver `Snapshot` em **Estruturas**. **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `404` — Vigia inexistente ou de outro dono. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/vigias/$ID -H "Authorization: Bearer $EDM" ``` ### `GET /api/vigias/:id/eventos` O que mudou na compra vigiada, evento a evento — é a série temporal e o canal pull. - **URL:** `https://staging.editalmd.com/api/vigias/:id/eventos` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador da vigia. Ex.: `2b7e…`. **Query** - `limite` (int) — 1 a 100 (padrão 50), mais recentes primeiro. **Resposta `200`** - `vigia` (Vigia) — A vigia. → ver `Vigia` em **Estruturas**. - `snapshot` (Snapshot) — A fotografia atual. → ver `Snapshot` em **Estruturas**. - `itens` (Evento[]) — Eventos registrados. → ver `Evento` em **Estruturas**. - `limite` (int) — Teto aplicado. **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `404` — Vigia inexistente ou de outro dono. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s "https://staging.editalmd.com/api/vigias/$ID/eventos?limite=20" -H "Authorization: Bearer $EDM" ``` ### `DELETE /api/vigias/:id` Apaga a vigia e seus eventos. Sem volta. - **URL:** `https://staging.editalmd.com/api/vigias/:id` - **Auth:** `owner` — Convidado edm_… assinado pelo SDK (POST /api/guest, sem cadastro), enviado em X-Guest-Token ou Authorization: Bearer; nos bancos fica só seu SHA-256. Também aceita a sessão da conta, dona direta das listas dela — cookie HttpOnly; escrita com a mesma origem e o X-CSRF-Token de /api/auth/bootstrap. Vincular a conta transfere os dados temporários pelo claim do SDK. Com o cookie da conta no pedido, quem pede é a conta. Recurso de outro dono responde 404. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador da vigia. Ex.: `2b7e…`. **Resposta `200`** 204 sem corpo. **Erros** - `401` — Sem token de convidado nem sessão da conta, token desconhecido, ou `session_ended` (cookie de sessão vencida: entre de novo). - `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta fora da mesma origem ou sem X-CSRF-Token. - `404` — Vigia inexistente ou de outro dono. - `503` — `conta_indisponivel`: conta fora do ar agora; nada muda. **Exemplo** ```sh curl -s -XDELETE https://staging.editalmd.com/api/vigias/$ID -H "Authorization: Bearer $EDM" ``` ## Operação ### `POST /api/cobranca/:id/registrar` Operação interna para registrar transferência confirmada no razão financeiro. Uso exclusivo da origem autenticada. A prova é verificada pelo serviço, nunca aceita do corpo. Repetição registra cada evento uma única vez. - **URL:** `https://staging.editalmd.com/api/cobranca/:id/registrar` - **Auth:** `origem` — X-Editalmd-Secret: credencial privada de integração interna. Não é uma porta para clientes ou agentes públicos. **Parâmetros de caminho** - `id` (string, obrigatório) — UUID da cobrança. Ex.: `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`. **Headers** - `X-Editalmd-Secret` (string, obrigatório) — Segredo compartilhado da origem; somente operador. **Resposta `200`** - `registrado` (boolean) — Todos os eventos registrados ou já existentes. → ver `boolean` em **Estruturas**. **Erros** - `401` — Sem autoridade da origem. - `404` — Cobrança inexistente na origem. - `409` — Pagamento não confirmado. - `503` — Registro indisponível; tente novamente conforme a orientação do serviço. **Exemplo** ```sh curl -s -X POST https://staging.editalmd.com/api/cobranca/UUID/registrar -H 'X-Editalmd-Secret: SEGREDO_DA_ORIGEM' ``` ### `POST /api/visit` Ping da interface que incrementa a visita do dia no painel do operador. Agente não precisa chamar. Smoke não conta: `X-MM-Smoke`, User-Agent `mm-smoke` ou `smoke: true` no corpo entram como `counted: false`. - **URL:** `https://staging.editalmd.com/api/visit` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Corpo** (`application/json`) - `p` (string) — Caminho da página visitada, só para agrupar. - `smoke` (bool) — `true` marca a chamada como teste e ela fica fora da contagem. **Exemplo de corpo** ```json { "p": "/" } ``` **Resposta `200`** - `ok` (bool) — Sempre `true`. - `counted` (bool) — Se a visita entrou na contagem do dia. - `reason` (string, opcional) — Por que não contou, quando `counted` é `false`. **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/api/visit -H 'content-type: application/json' -d '{"p":"/"}' ``` ### `POST /api/erro-cliente` Relato de erro do navegador, enviado pela própria interface. Agente não precisa chamar. A interface relata sozinha erro de JS, promessa rejeitada, script/CSS que não carregou e bloqueio de CSP — uma vez por sessão — e o app relata falha tratada por `window.mmErro.relata`. O servidor valida o envelope, redige credencial, e-mail e telefone, junta repetições da mesma falha por minuto e registra um evento operacional; nada é gravado em banco. Não guarda IP, cookie, query nem o User-Agent inteiro. Responde 204 sempre, inclusive para relato inválido. - **URL:** `https://staging.editalmd.com/api/erro-cliente` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Corpo** (`application/json`) - `code` (string, obrigatório) — Código da falha, `UI-` + letras/dígitos (`UI-JS-001` erro global, `UI-PROMESSA-001`, `UI-RECURSO-001`, `UI-CSP-001`, `UI-APP-001` relato do app). - `phase` (string, obrigatório) — Fase em que quebrou, minúsculas: `global`, `promessa`, `script`, `carregar_lista`… - `path` (string) — Caminho da página aberta, sem query. - `message` (string) — Mensagem do erro, até 2000 caracteres. - `stack` (string) — Stack trace, até 12000 caracteres. - `source` (string) — Script de origem; só o caminho é guardado. - `line` (int) — Linha no script de origem. - `column` (int) — Coluna no script de origem. - `visivel` (bool) — Se a aba estava visível quando quebrou. **Exemplo de corpo** ```json { "code": "UI-APP-001", "phase": "carregar_lista", "path": "/", "message": "lista 500" } ``` **Resposta `200`** 204 sem corpo, sempre — relato inválido, repetido ou acima do teto também recebe 204. **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/api/erro-cliente -H 'content-type: application/json' -d '{"code":"UI-APP-001","phase":"carregar_lista","path":"/","message":"lista 500"}' ``` ### `POST /api/pagamento/aberto` A interface relata que exibiu uma cobrança. Agentes não devem chamar. Relato sem corpo, da mesma origem, enviado automaticamente quando uma cobrança fica visível. Não inicia pagamento, não concede acesso e não recebe identidade ou credencial. Não grava banco por relato. Conta eventos, não pessoas únicas. O painel privado do operador separa pedidos de pagamento da API e aberturas da interface por dia UTC; os dois números podem se sobrepor. - **URL:** `https://staging.editalmd.com/api/pagamento/aberto` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Headers** - `Origin` (string, obrigatório) — A origem da página, idêntica à desta rota. - `Sec-Fetch-Site` (string, obrigatório) — `same-origin`, definido pelo navegador. - `X-MM-Payment-View` (string, obrigatório) — `1`, definido pelo componente comum. **Resposta `202`** 202 sem corpo se aceito; 204 se ignorado. Sempre no-store. ### `GET /api/metrics` Métricas dos últimos 7 dias para o painel do operador; com o token, inclui os pagamentos. Sem credencial devolve visitas, uso (entregas de markdown, alertas, vigias). Com `METRICS_TOKEN` em Bearer acrescenta `payments` — só x402 liquidado em Base mainnet. - **URL:** `https://staging.editalmd.com/api/metrics` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Headers** - `Authorization` (string) — `Bearer ` para incluir o bloco financeiro; token errado é 401. **Resposta `200`** Estrutura: `Metricas`. - `app` (string) — Nome do produto. - `today` (string) — Dia de referência (UTC, AAAA-MM-DD). - `today_visits` (int) — Visitas contadas hoje pela interface. - `today_contacts` (int, opcional) — Mensagens de contato hoje — este produto não tem formulário, fica em zero. Só com `METRICS_TOKEN`: contato não sai sem token. - `days` (object[]) — Um registro por dia da janela, com as contagens de cada métrica. - `usage` (object) — Uso por recurso: `markdown` (entregas), `alertas` e `vigias` criados, por dia. - `accounts` (object) — Vazio: pessoas e convidados moram na conta global, não no produto. - `financeiro` (object, opcional) — Agregado do dia: `hoje_usd`, `hoje_count`, `rede`. Só com `METRICS_TOKEN`: dinheiro não sai sem token; a série completa é `payments`. - `payments` (object, opcional) — Resumo financeiro do x402; só com METRICS_TOKEN. **Erros** - `401` — Token de operador errado. - `503` — Worker sem METRICS_TOKEN configurado. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/metrics -H "Authorization: Bearer $METRICS_TOKEN" ``` ## Crédito ### `POST /api/credito` Recarrega crédito pré-pago: paga uma vez com x402 e recebe o token que desconta em qualquer API da casa. - **URL:** `https://staging.editalmd.com/api/credito` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Query** - `usd` (int, obrigatório) — Pacote: 1, 5, 10 ou 25 dólares. **Resposta `200`** - `token` (string) — Token portador do saldo (`cred_…`). Mostrado UMA vez — não há como recuperá-lo. - `saldo_usd` (string) — Saldo creditado. - `guarde` (string) — Aviso de que o token é o portador do crédito. - `usar` (string) — Como apresentar o token nas rotas pagas. - `saldo_em` (string) — Onde consultar saldo e extrato. **Erros** - `400` — Pacote fora da lista (1, 5, 10 ou 25). - `402` — Sem pagamento — o corpo traz `accepts[]` do x402. **Exemplo** ```sh curl -s -XPOST 'https://staging.editalmd.com/api/credito?usd=10' ``` ### `GET /api/credito` Saldo e extrato do crédito — as últimas movimentações, sem devolver o token. - **URL:** `https://staging.editalmd.com/api/credito` - **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo. **Resposta `200`** - `saldo_micros` (int) — Saldo em micro-dólares (1e-6 USD). - `saldo_usd` (string) — Saldo formatado. - `criado_em` (string) — Quando o crédito foi aberto. - `movimentos` (object[]) — Entradas e saídas recentes, com produto e recurso. **Erros** - `401` — Sem token ou token desconhecido. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/credito -H 'Authorization: Bearer cred_…' ``` ## Contato ### `POST /api/contact` Fale com quem faz o produto — de graça, para pessoa e agente. Uma rota para dúvida e para proposta de patrocínio, parceria ou anúncio (`tipo`, com os espaços de `GET /api/partners`). Sem captcha, sem conta, sem pagamento. Uma mensagem a cada 10 segundos por rede: a que chega antes espera a vez e sai — sem erro. A mensagem chega à equipe por e-mail, com o `email` como endereço de resposta. - **URL:** `https://staging.editalmd.com/api/contact` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Corpo** (`application/json`) - `name` (string, obrigatório) — Como chamar quem escreve (alias `nome`). - `email` (string, obrigatório) — Para onde responder. - `message` (string, obrigatório) — O que você quer dizer (alias `mensagem`). - `tipo` (string) — Proposta: `patrocinio`, `parceria` ou `anuncio`. Liga os campos abaixo. - `empresa` (string) — Quem propõe, quando é empresa. - `site` (string) — Site de quem propõe. - `orcamento` (string) — `ate_100`, `100_500`, `500_2000`, `2000_mais` ou `a_combinar`. - `espaco` (string[]) — Ids de placement de `GET /api/partners`, até 6. - `duracao` (string) — Dias de exposição: `30`, `90` ou `365`. - `pagamento` (string) — `usdc`, `deposito` ou `a_combinar`. **Exemplo de corpo** ```json { "name": "Agente", "email": "agent@example.com", "message": "olá, sou um agente" } ``` **Resposta `200`** - `ok` (bool) — Sempre `true` quando a mensagem foi aceita. **Erros** - `400` — Validação: o `code` diz o campo. - `503` — O contato não está configurado neste servidor. **Exemplo** ```sh curl -s -XPOST https://staging.editalmd.com/api/contact -H 'content-type: application/json' -d '{"name":"Agente","email":"agent@example.com","message":"olá, sou um agente"}' ``` ## Números públicos ### `GET /api/vitrine` Os números públicos do produto: tráfego, agentes, uso e confiabilidade, sem dinheiro. Projeção publicada de hora em hora pelo coletor da casa, arredondada a dois dígitos significativos; `null` é medição ausente, nunca zero. Cache de 15 minutos com ETag (`If-None-Match` → 304). Não há como enviar números por esta rota: a publicação é do coletor, com token próprio. - **URL:** `https://staging.editalmd.com/api/vitrine` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** - `v` (int) — Versão do contrato (1). - `produto` (string) — Id do produto. - `publicado` (bool) — `false` antes da primeira publicação do coletor; aí só estas cinco chaves vêm. - `atualizado_em` (string, pode ser null) — Quando o coletor publicou (ISO 8601). - `stale` (bool) — `true` quando a projeção tem mais de 26 h. - `nome` (string, opcional) — Nome do produto. - `desde` (string, opcional, pode ser null) — Dia a partir do qual a série vale. - `fuso` (string, opcional) — Fuso dos dias (`UTC`). - `hoje` (object, opcional) — O dia de hoje: páginas por classe (pessoa, IA, bot), chamadas de API por classe, leituras das superfícies de máquina e uso do produto. - `dias` (object[], opcional) — Até 31 dias, o mais antigo primeiro: `dia`, `paginas`, `api`, `api_ia`, `maquina`, `visitantes`, `uso`. - `janelas` (object, opcional) — Somas de 7 e 30 dias (`d7`, `d30`). - `visitantes` (object, opcional) — Visitantes únicos na borda em 7 dias. - `pessoas` (object, opcional, pode ser null) — GA4 quando há: usuários, sessões, países, aparelhos e quem chegou de IA. - `agentes` (object, opcional) — Os agentes de IA e os bots que mais leem, 7 dias. - `superficies` (object, opcional) — Leituras de OKF, llms, well-known, OpenAPI e MCP em 7 dias. - `mcp` (object, opcional) — Chamadas MCP em 7 dias. - `uso` (object, opcional) — Uso real do produto por recurso: rótulo, hoje, 7 e 30 dias. - `contas` (object, opcional, pode ser null) — Usuários e convidados. - `confiabilidade` (object, opcional) — Percentual de pedidos sem 5xx em 7 dias e o build no ar. - `catalogo` (object, opcional, pode ser null) — Tamanho do acervo, quando o produto tem um. - `apoio` (object, opcional) — Impressões e cliques por patrocinador, quando houver. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/vitrine ``` ### `GET /api/vitrine/operador` O documento completo do produto no painel do operador — só com o token do operador. - **URL:** `https://staging.editalmd.com/api/vitrine/operador` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Headers** - `Authorization` (string, obrigatório) — `Bearer ` — a classe operador. **Resposta `200`** - `produto` (string) — Id do produto. - `atualizado_em` (string, pode ser null) — Quando o coletor publicou. - `operador` (object, pode ser null) — O documento completo do coletor, com o que a projeção pública não carrega. **Erros** - `401` — Sem token, token errado ou token de outra classe. - `503` — Worker sem `METRICS_TOKEN` ou sem o control plane. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/vitrine/operador -H "Authorization: Bearer $METRICS_TOKEN" ``` ### `GET /api/vitrine/painel` O painel da casa inteira, na forma que o gm lê — só com o token do operador. - **URL:** `https://staging.editalmd.com/api/vitrine/painel` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Headers** - `Authorization` (string, obrigatório) — `Bearer ` — a classe operador. **Resposta `200`** - `apps` (object[]) — Um documento do operador por produto, em ordem de id. - `updated` (string, opcional) — Quando o coletor fechou a rodada. - `totals` (object, opcional) — Os totais da casa. **Erros** - `401` — Sem token, token errado ou token de outra classe. - `503` — Worker sem `METRICS_TOKEN` ou sem o control plane. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/vitrine/painel -H "Authorization: Bearer $METRICS_TOKEN" ``` ### `GET /api/vitrine/cursores` O cursor de erro resolvido por produto (`borda`, `cli`) — só com o token do operador. - **URL:** `https://staging.editalmd.com/api/vitrine/cursores` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Headers** - `Authorization` (string, obrigatório) — `Bearer ` — a classe operador. **Resposta `200`** JSON: `{ [produto]: { borda?: ISO, cli?: ISO } }`; vazio é `{}`. **Erros** - `401` — Sem token, token errado ou token de outra classe. - `503` — Worker sem `METRICS_TOKEN` ou sem o control plane. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/vitrine/cursores -H "Authorization: Bearer $METRICS_TOKEN" ``` ## Parceria ### `GET /api/partners` Parceria, patrocínio e anúncio: os espaços do produto com preço sugerido, os números públicos ao lado e como propor. Informação sob consulta, sem ativação: espaços do catálogo da casa com preço em USD por 30 dias (90 e 365 dias com desconto), patrocinadores em vigor, recorte de `/api/vitrine`, carteira da casa (USDC na Base) e o caminho de contato — depósito, PIX ou fatura são combinados na resposta. Cache de 1 hora. - **URL:** `https://staging.editalmd.com/api/partners` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Resposta `200`** - `status` (string) — `sob_consulta`: informação e proposta, sem ativação nem cobrança. - `produto` (string) — Nome do produto. - `idioma` (string) — Idioma dos textos (o do produto). - `titulo` (string) — Título da oferta. - `descricao` (string) — Uma frase sobre a oferta. - `publico` (string) — Quem usa o produto — o público que o patrocinador alcança. - `modalidades` (object[]) — `{ id, nome }`: patrocinio, parceria, anuncio. - `placements` (object[]) — Os espaços do produto: `id`, `nome`, `onde`, `formato`, `exclusivo`, `medicao`, `price_usd_30d` (sugestão; `null` é sob consulta), `exposure[{ dias, price_usd }]` para 30, 90 e 365 dias, `disponivel`. - `house_bundle` (object) — O pacote da casa: rodapé e menção para agentes nos dez produtos, com desconto. - `parcerias` (string[]) — Ideias de parceria que o produto aceita discutir. - `current_sponsors` (object[]) — Patrocinadores em vigor: `id`, `nome`, `url`, `frase`, `espacos`, `ate`. - `stats` (object) — Recorte dos números públicos (`hoje`, `janelas`, `agentes`, `confiabilidade`) e o `link` para `/api/vitrine`; `publicado: false` antes da primeira publicação. - `payment` (object) — Como pagar: `rede`, `chain_id`, `ativo`, `pay_to`, `eip681` (a carteira da casa, quando declarada), `alternativas` e a `nota` — depósito, PIX ou fatura pela resposta. - `contact` (object) — `email`, `form_url`, `api_url` (`POST /api/contact`, livre: uma mensagem a cada 10 s por rede), `campos` (os obrigatórios), `campos_proposta` (os opcionais da proposta, com os valores aceitos de cada um), `message_template`, `instructions`. - `politica` (object) — Rótulo do espaço, setores recusados, pagamento adiantado, prazos. - `_links` (object) — `self`, `stats`, `page` (`null` até a página existir), `contact`, `casa` (o mesmo caminho nos dez produtos). **Exemplo** ```sh curl -s https://staging.editalmd.com/api/partners ``` ## Prova ### `GET /api/recibo/:id` Recibo de uma entrega — a prova de o que saiu, quanto custou e com qual hash. - **URL:** `https://staging.editalmd.com/api/recibo/:id` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Parâmetros de caminho** - `id` (string, obrigatório) — Identificador do recibo (32 hex), do header `x-editalmd-recibo`. Ex.: `0c8f2b…`. **Resposta `200`** - `recibo` (Recibo) — O recibo. → ver `Recibo` em **Estruturas**. **Erros** - `404` — Recibo não encontrado. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/recibo/0c8f… ``` ## API access ### `GET /api/acesso` Discover the monthly data package or inspect a private purchase. - **URL:** `https://staging.editalmd.com/api/acesso` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Headers** - `X-API-Pass` (string) — Private pass: api_<32 random hex>_<64 random hex>. Save before buying. **Resposta `200`** Estrutura: `ApiAccess`. - `offer` (ApiAccessOffer) — Current offer and payment instructions. → ver `ApiAccessOffer` em **Estruturas**. - `enabled` (bool, opcional) — Present in public discovery; false means no purchases. - `id` (string, opcional) — Purchase ID; not a credential. - `status` (string, opcional) — paid, unpaid or pending. - `granted_credits` (int, opcional) — Original grant, not remaining usage. - `expires_at` (string, opcional, pode ser null) — ISO expiry, 30 days after purchase. - `receipt` (string, opcional, pode ser null) — Confirmed payment receipt. - `via` (string, opcional, pode ser null) — x402, credito or gated homolog. - `message` (string, opcional) — Next action in the requested language. **Erros** - `400` — Invalid pass. - `404` — Unknown purchase or wrong owner. - `503` — Purchases disabled. **Exemplo** ```sh curl -s https://staging.editalmd.com/api/acesso ``` ### `POST /api/acesso` Buy 1000 basic data reads for US$1, valid for 30 days. Same pass in retries recovers the same purchase. No automatic renewal. OCR, AI, documents and delivery keep their own tariffs. Send X-API-Pass on eligible data reads; remaining credits come in X-API-Credits-Remaining. - **URL:** `https://staging.editalmd.com/api/acesso` - **Auth:** `none` — Público. Agente não se cadastra: quando a rota cobra, cobra por requisição (x402) ou desconta de crédito pré-pago. **Headers** - `X-API-Pass` (string, obrigatório) — Private pass: api_<32 random hex>_<64 random hex>. Save before buying. - `X-Credito` (string) — Existing prepaid credit token; alternative to x402. - `Authorization` (string) — Bearer cred_… alternative to X-Credito. - `X-PAYMENT` (string) — Signed x402 authorization from the 402 quote, maximum 16 KiB. - `PAYMENT-SIGNATURE` (string) — Alternative name for X-PAYMENT. - `X-API-Transaction` (string) — Confirmed Base transaction hash for reconciliation with the original pass and signed payment. Never creates another charge. **Resposta `200`** Estrutura: `ApiAccess`. - `offer` (ApiAccessOffer) — Current offer and payment instructions. → ver `ApiAccessOffer` em **Estruturas**. - `enabled` (bool, opcional) — Present in public discovery; false means no purchases. - `id` (string, opcional) — Purchase ID; not a credential. - `status` (string, opcional) — paid, unpaid or pending. - `granted_credits` (int, opcional) — Original grant, not remaining usage. - `expires_at` (string, opcional, pode ser null) — ISO expiry, 30 days after purchase. - `receipt` (string, opcional, pode ser null) — Confirmed payment receipt. - `via` (string, opcional, pode ser null) — x402, credito or gated homolog. - `message` (string, opcional) — Next action in the requested language. **Erros** - `400` — Missing or invalid pass/payment. - `401` — Invalid prepaid credit. - `402` — Payment required: x402 accepts[] and prepaid-credit instructions. - `409` — Payment pending; retain the same pass and do not pay again. - `429` — Purchase attempt limit; respect Retry-After. - `503` — Payment unavailable or pending reconciliation. **Exemplo** ```sh curl -s -X POST "https://staging.editalmd.com/api/acesso" -H "X-API-Pass: $API_PASS" ``` ## Estruturas ### `DocumentosEmpresa` - `itens` (DocumentoEmpresa[]) — Até 20 anexos da empresa deste dono. → ver `DocumentoEmpresa` em **Estruturas**. - `revisao` (string) — Hash do conjunto de documentos; alterações invalidam análises anteriores. - `limite` (int) — 20 documentos. - `limite_bytes` (int) — 8 MiB por PDF; 80 MiB no conjunto. - `limite_paginas` (int) — 50 páginas somadas entre os anexos. ### `AnaliseParticipacao` - `analise` (object, pode ser null) — null quando nunca solicitada; id, status (queued/processing/retrying/paused/ready/failed/outdated/interrupted), atual, parcial, data_atual, etapa, processados, total, CNPJ, hashes, datas, erro, falha_etapa, problema (motivo/acao/automatico), historico e proxima_tentativa_em. atual permite consultar lotes validados; somente ready é cobertura concluída. data_atual=false exige conferir a data de referência. interrupted permite retomar pedido sem entrada de fila, inclusive legado. - `itens` (object[]) — Até 30 pares fact/analysis: fato do dossiê e avaliação com fact_id, status, reason, action, evidence (source_id/page/quote), edital_quote e edital_page. - `contagens` (object, opcional) — Totais pendencias, atendidos e nao_aplicavel dos lotes já validados da análise atual, inclusive durante processamento ou pausa; parcial=true não representa cobertura completa. - `tipos` (object, opcional) — Mesmas contagens separadas por requirement, attestation e obligation. - `next` (int, pode ser null) — Último ID desta página; use after até null. ### `EmpresasConta` - `itens` (EmpresaConta[]) — Até 20 vínculos, por CNPJ crescente; coleção completa. → ver `EmpresaConta` em **Estruturas**. - `selecionada` (string, pode ser null) — CNPJ selecionado pelo dono, ou null. - `limite` (int) — 20 empresas por dono. ### `SugestaoEmpresa` - `cnpj` (string) — CNPJ completo, 14 dígitos com verificação válida. - `nome` (string, pode ser null) — Nome exibido pela base. - `municipio` (string, pode ser null) — Município. - `uf` (string, pode ser null) — Sigla da unidade da federação. - `situacao` (string, pode ser null) — Situação cadastral. ### `Saude` Saúde do Worker e da origem. - `ok` (bool) — `true` quando a origem respondeu. - `build` (string) — Commit publicado (`env.BUILD`), o mesmo do `/api/`. - `acervo` (Acervo) — Números do acervo. → ver `Acervo` em **Estruturas**. - `preco_markdown_usd` (string) — Tarifa por página por comprador, com geração incluída. - `gratis_acima_de_dias` (int) — Legado, sempre zero; nenhuma faixa de data concede gratuidade. ### `Busca` Resultado da busca — sempre grátis. - `itens` (Compra[]) — Compras que casaram com o termo. → ver `Compra` em **Estruturas**. - `preco_markdown_usd` (string) — Tarifa por página por comprador, inclusive texto pronto. - `gratis_acima_de_dias` (int) — Legado, sempre zero; nenhuma faixa de data concede gratuidade. - `pago` (bool) — Sempre `false`: buscar não custa. ### `Cnae` Um CNAE (subclasse) como o produto o vê: descrição oficial, dicionário e fornecedores no SICAF. - `codigo` (string) — 7 dígitos. - `cnae` (string) — Formatado, ex. `1412-6/01`. - `descricao` (string, pode ser null) — Descrição oficial (IBGE/Concla). - `familia` (string, pode ser null) — Família de termos no dicionário; nulo se ainda não mapeado. - `familia_nome` (string, pode ser null) — Nome da família. - `termos` (string, pode ser null) — Termos que um alerta por CNPJ usaria para este CNAE. - `fornecedores_sicaf` (int, pode ser null) — Fornecedores ativos com este CNAE no SICAF (dados abertos do compras.gov.br). - `sicaf_medido_em` (string, pode ser null) — Quando essa contagem foi medida. - `ibge_atualizado_em` (string, pode ser null) — Quando a descrição foi atualizada do IBGE. ### `FichaCompra` Compra + documentos disponíveis + o regime que se aplica a eles. - `compra` (Compra) — A compra. → ver `Compra` em **Estruturas**. - `documentos` (Documento[]) — Documentos com texto pronto ou binário disponível. → ver `Documento` em **Estruturas**. - `regime` (Regime) — Acesso individual pago; somente exemplos explícitos gratuitos. → ver `Regime` em **Estruturas**. - `prazos` (Prazos) — Proposta e impugnação da compra — o mesmo objeto de `compra.prazos`. → ver `Prazos` em **Estruturas**. ### `Habilitacao` A lista de habilitação extraída de um edital, por família, com procedência. - `documento_id` (int) — Documento lido. - `compra_id` (int, pode ser null) — Compra do documento. - `sha256_texto` (string) — Hash do texto fonte do dossiê. - `dossie_versao` (string) — Hash da identidade da análise compartilhada. - `modelo` (string, pode ser null) — Modelo que extraiu. - `cache` (bool) — False: consulta a versão atual disponível. - `recibo` (string, pode ser null) — Recibo da entrega paga; nulo no cache. - `recibo_url` (string, pode ser null) — Onde consultar o recibo. - `aviso` (string) — Lembrete de conferir no edital. - `habilitacao` (ListaHabilitacao) — As exigências por família e o que o edital diz de prazo. → ver `ListaHabilitacao` em **Estruturas**. ### `Dono` O convidado (token de dono), mostrado uma única vez, o segredo que assina os webhooks e a franquia. - `token` (string) — `edm_…` emitido pela biblioteca de conta — guarde; não é mostrado de novo nem recuperável. - `aviso` (string) — Lembrete de guardar o token e como usá-lo. - `webhook_segredo` (string) — `whsec_…` — assina todo POST de webhook (Standard Webhooks). Releia em `GET /api/dono`; rotacione em `POST /api/dono/segredo`. - `webhook_assinatura` (string) — Como conferir a assinatura, em uma linha. - `franquia` (object) — `alertas_gratis` e `vigias_gratis` incluídos. ### `Precos` Preços homologados para um item parecido: a amostra (`itens`) e, sobre todos os candidatos, o resumo, a distribuição por UF e por mês, quem vence e quem compra. Sempre grátis. - `consulta` (PrecosConsulta) — O pedido como a origem o entendeu. → ver `PrecosConsulta` em **Estruturas**. - `estatisticas` (PrecosEstatisticas) — Sobre os valores unitários da amostra devolvida em `itens`. → ver `PrecosEstatisticas` em **Estruturas**. - `resumo` (PrecosResumo, pode ser null) — Sobre todos os candidatos do período (não só a amostra). Nulo quando nada casou. → ver `PrecosResumo` em **Estruturas**. - `por_uf` (PrecosPorUf[]) — Um por UF do órgão comprador, mais resultados primeiro. → ver `PrecosPorUf` em **Estruturas**. - `por_mes` (PrecosPorMes[]) — Um por mês do período, do mais antigo ao mais recente; mês sem homologação vem com `n: 0`. → ver `PrecosPorMes` em **Estruturas**. - `vencedores` (PrecoVencedor[]) — Até 10 fornecedores, por itens ganhos e depois por valor. → ver `PrecoVencedor` em **Estruturas**. - `compradores` (PrecoComprador[]) — Até 10 órgãos, por itens comprados e depois por valor. → ver `PrecoComprador` em **Estruturas**. - `amostra` (PrecosAmostra, pode ser null) — Como os candidatos foram escolhidos e se bateram no teto. → ver `PrecosAmostra` em **Estruturas**. - `itens` (PrecoHomologado[]) — Resultados por relevância e homologação mais recente. → ver `PrecoHomologado` em **Estruturas**. - `base_legal` (string) — A base legal da pesquisa de preços que este dado atende. - `pago` (bool) — Sempre `false`: consultar preços não custa. ### `Compra` Uma compra pública disponível no acervo. - `id` (int) — Identificador interno da compra — é ele que abre a ficha. - `pncp` (string, pode ser null) — Número de controle PNCP da compra. - `objeto` (string, pode ser null) — Objeto da compra, como publicado. - `uf` (string, pode ser null) — Sigla da unidade da federação do órgão. - `modalidade` (string, pode ser null) — Modalidade (pregão eletrônico, dispensa…). - `situacao` (string, pode ser null) — Situação da compra no PNCP. - `orgao` (string, pode ser null) — Razão social do órgão comprador. - `unidade` (string, pode ser null) — Unidade administrativa responsável. - `valor_estimado` (number, pode ser null) — Valor total estimado em reais. - `publicado_em` (string, pode ser null) — Data de publicação no PNCP. - `informacao_complementar` (string, pode ser null) — Informação complementar publicada. - `processo` (string, pode ser null) — Número do processo administrativo. - `abertura_proposta` (string, pode ser null) — Início do recebimento de propostas, hora de Brasília. - `encerramento_proposta` (string, pode ser null) — Fim do recebimento de propostas, que é a abertura da sessão — a base da impugnação. - `amparo_legal` (string, pode ser null) — Amparo legal declarado, ex.: `Lei 14.133/2021, Art. 28, I`. - `amparo_legal_codigo` (int, pode ser null) — Código do amparo legal no PNCP. - `modalidade_id` (int, pode ser null) — Código da modalidade no PNCP (6 = pregão eletrônico, 8 = dispensa…). - `situacao_id` (int, pode ser null) — Código da situação: 1 divulgada, 2 revogada, 3 anulada, 4 suspensa. - `municipio` (string, pode ser null) — Município da unidade compradora. - `municipio_ibge` (string, pode ser null) — Código IBGE do município. - `orgao_cnpj` (string, pode ser null) — CNPJ do órgão, só dígitos. - `ano_compra` (int, pode ser null) — Ano da compra na numeração do PNCP. - `sequencial_compra` (int, pode ser null) — Sequencial da compra no órgão e ano. - `atualizado_em` (string, pode ser null) — Última atualização da compra vista pelo acervo. - `prazos` (Prazos) — Proposta e impugnação, calculados pelo Worker. → ver `Prazos` em **Estruturas**. - `pncp_url` (string, pode ser null) — Página humana da compra no PNCP. - `markdown_url` (string) — Atalho para o markdown do documento. - `compra_url` (string) — Ficha completa da compra. ### `FiltrosInteresse` Filtros combinados por E. Listas vazias e valores nulos deixam o campo livre. - `modalidades` (int[]) — Até 10 modalidades do PNCP, IDs 1 a 13. - `municipios` (string[]) — Até 10 nomes exatos ou códigos IBGE; use UF para distinguir homônimos. - `excluir` (string[]) — Até 10 expressões literais de 3 a 80 caracteres a excluir do objeto. - `valor_min` (number, pode ser null) — Valor estimado mínimo em reais. - `valor_max` (number, pode ser null) — Valor estimado máximo em reais. - `abertas` (bool) — Exige prazo de propostas ainda aberto ao coletar. ### `CompraSalva` Licitação da lista pessoal, acessível com o código de acesso do dono. - `compra_id` (int) — ID da compra. - `compra` (object) — Retrato: id, objeto, UF, município, órgão, modalidade e valor estimado. - `salvo_em` (string) — Data ISO de inclusão. - `url` (string) — Ficha pública no acervo. ### `Alerta` Um alerta de compra nova: termos, UF, filtros e canal de entrega. - `id` (string) — Identificador do alerta. - `termos` (string) — Palavras do objeto que o alerta procura (`|` = qualquer uma do grupo). - `origem` (OrigemCnae, pode ser null) — De onde veio um alerta criado por CNPJ; nulo no alerta por termos. → ver `OrigemCnae` em **Estruturas**. - `uf` (string, pode ser null) — UF restrita, ou nulo para o Brasil. - `filtros` (FiltrosInteresse) — Recorte adicional do interesse. → ver `FiltrosInteresse` em **Estruturas**. - `canal` (string) — `pull`, `webhook` ou `email`. - `destino` (string, pode ser null) — URL do webhook; nulo no pull e no e-mail, que vai para o e-mail verificado da conta, lido nela a cada envio (alertas antigos mostram o endereço da época, mascarado). - `ativo` (bool) — Se o cron ainda confere este alerta. - `pago_ate` (string, pode ser null) — Fim da validade paga; nulo na franquia. - `ultimo_check` (string, pode ser null) — Última rodada; não significa que todo o backlog foi entregue. - `falhas_seguidas` (int) — Entregas seguidas que falharam; em 10 o alerta pausa. - `criado_em` (string) — Criação em ISO 8601. - `alerta_url` (string) — URL deste alerta. - `compras_url` (string) — Onde ler as compras casadas (pull). ### `Empresa` A ficha resumida da empresa consultada pelo CNPJ, com a leitura do dicionário para cada CNAE. - `cnpj` (string) — 14 dígitos. - `cnpj_formatado` (string) — Com pontuação, para gente. - `razao_social` (string, pode ser null) — Razão social na Receita. - `nome_fantasia` (string, pode ser null) — O nome comercial, quando difere da razão social. - `situacao` (string, pode ser null) — Situação cadastral (Ativa, Baixada…). - `uf` (string, pode ser null) — UF da sede. - `municipio` (string, pode ser null) — Município da sede. - `cnaes` (CnaeDaEmpresa[]) — Principal primeiro, depois os secundários. → ver `CnaeDaEmpresa` em **Estruturas**. ### `FamiliaNaoCriada` Uma família da empresa que não virou alerta neste pedido. - `familia` (string) — Identificador da família. - `nome` (string) — Nome da família. - `termos` (string) — Os termos que o alerta teria. - `cnaes` (string[]) — CNAEs da empresa que caem nela. - `motivo` (string) — `acima_de_max_familias`. ### `AlertaCompra` Uma compra que casou com o alerta e o que aconteceu com a entrega. - `compra_id` (int) — Identificador da compra no acervo. - `status` (string) — `pull`, `webhook:ok`, `webhook:falhou`, `email:ok`, `email:falhou`, `email:recusado` (a SES recusou em definitivo; não é tentado de novo), `email:sem_conta` (convidado ou conta sem e-mail), `email:nao_confirmado` (anterior a 21/09/2026), `email:teto_do_dia` ou `pendente`. - `visto_em` (string) — Quando o cron viu a compra. - `compra` (Compra, pode ser null) — A compra como estava quando casou, com prazos. → ver `Compra` em **Estruturas**. ### `Vigia` Uma compra vigiada: canal de aviso, validade e o cursor do cron. - `id` (string) — Identificador da vigia. - `compra_id` (int) — Compra vigiada no acervo. - `canal` (string) — `pull`, `webhook` ou `email`. - `destino` (string, pode ser null) — URL do webhook; nulo no pull e no e-mail. - `ativo` (bool) — Se o cron ainda reconfere; encerra 30 dias após o fim das propostas. - `pago_ate` (string, pode ser null) — Fim da validade paga; nulo na franquia. - `ultimo_check` (string, pode ser null) — Última reconferência. - `criado_em` (string) — Criação em ISO 8601. - `vigia_url` (string) — URL desta vigia. - `eventos_url` (string) — Onde ler os eventos (pull). - `compra_url` (string) — Ficha da compra. ### `Snapshot` A fotografia da compra que a vigia compara. - `situacao_id` (int, pode ser null) — Situação: 1 divulgada, 2 revogada, 3 anulada, 4 suspensa. - `situacao` (string, pode ser null) — Situação por extenso. - `encerramento_proposta` (string, pode ser null) — Fim das propostas visto na fotografia. - `valor_estimado` (number, pode ser null) — Valor estimado visto na fotografia. - `atualizado_em` (string, pode ser null) — Última atualização conhecida da compra. - `documentos` (object[]) — Documentos por sequencial do PNCP: `sequencial`, `id`, `titulo`, `tipo`. ### `Evento` Uma mudança vista na compra vigiada, ou um aviso de prazo. - `id` (string) — Identificador do evento. - `tipo` (string) — `situacao`, `prazo_adiado`, `valor`, `documento_novo`, `documento_removido`, `prazo_impugnacao` ou `prazo_proposta`. - `antes` (string, pode ser null) — Valor anterior; nulo em documento novo e nos avisos de prazo. - `depois` (string, pode ser null) — Valor novo; nulo em documento removido. - `visto_em` (string) — Quando o cron viu. - `entregue_em` (string, pode ser null) — Quando o aviso saiu por webhook ou e-mail; nulo no pull ou em falha. ### `Metricas` Painel de 7 dias do operador. `payments` só aparece com o token e só em Base mainnet. - `app` (string) — Nome do produto. - `today` (string) — Dia de referência (UTC, AAAA-MM-DD). - `today_visits` (int) — Visitas contadas hoje pela interface. - `today_contacts` (int, opcional) — Mensagens de contato hoje — este produto não tem formulário, fica em zero. Só com `METRICS_TOKEN`: contato não sai sem token. - `days` (object[]) — Um registro por dia da janela, com as contagens de cada métrica. - `usage` (object) — Uso por recurso: `markdown` (entregas), `alertas` e `vigias` criados, por dia. - `accounts` (object) — Vazio: pessoas e convidados moram na conta global, não no produto. - `financeiro` (object, opcional) — Agregado do dia: `hoje_usd`, `hoje_count`, `rede`. Só com `METRICS_TOKEN`: dinheiro não sai sem token; a série completa é `payments`. - `payments` (object, opcional) — Resumo financeiro do x402; só com METRICS_TOKEN. ### `Recibo` Prova da entrega: o que foi pago, quanto, como e o hash do que saiu. - `id` (string) — Identificador do recibo (32 hex). - `recurso` (string) — Recurso entregue, ex.: `documento/123/markdown`. - `documento_id` (int, pode ser null) — Documento entregue. - `preco_usd` (string) — Preço cobrado — `$0.00` em amostra. - `modo` (string) — `gratuito`, `homolog` ou `onchain`. - `sha256_entregue` (string) — SHA-256 do markdown entregue, ou `nao_entregue`. - `bytes` (int) — Tamanho do que foi entregue. - `criado_em` (string) — Instante da entrega em ISO 8601. ### `ApiAccess` - `offer` (ApiAccessOffer) — Current offer and payment instructions. → ver `ApiAccessOffer` em **Estruturas**. - `enabled` (bool, opcional) — Present in public discovery; false means no purchases. - `id` (string, opcional) — Purchase ID; not a credential. - `status` (string, opcional) — paid, unpaid or pending. - `granted_credits` (int, opcional) — Original grant, not remaining usage. - `expires_at` (string, opcional, pode ser null) — ISO expiry, 30 days after purchase. - `receipt` (string, opcional, pode ser null) — Confirmed payment receipt. - `via` (string, opcional, pode ser null) — x402, credito or gated homolog. - `message` (string, opcional) — Next action in the requested language. ### `PaymentQuota` - `free` (PaymentFree[]) — Free allowances and their windows. → ver `PaymentFree` em **Estruturas**. - `paid` (PaymentPrice[]) — List prices in USD. The operation's 402 is the payable quote. → ver `PaymentPrice` em **Estruturas**. - `how_to_pay` (string) — Payment instructions and availability restrictions. - `live` (string, pode ser null) — Authoritative product quota endpoint. - `free_now` (string[], opcional) — SKUs temporarily free despite their list price. - `trial` (PaymentTrial, opcional) — Registration trial, when offered. → ver `PaymentTrial` em **Estruturas**. ### `PaymentX402` x402 payment configuration in force. Comes from `planPublic` and is the same across the products. - `provider` (string) — Always `x402` — the only billing protocol accepted. - `mode` (string) — Seller mode: `live` charges for real, `dev` lets calls through unpaid. - `network` (string) — USDC network: `base` in production, `base-sepolia` in staging. - `chain_id` (int) — EVM chain ID of the network above, so the wallet signs on the right chain. - `pay_to` (string, pode ser null) — Address that receives the payment. - `homolog` (bool) — Staging seam on: the loop can be closed without spending USDC. - `dev` (bool) — Development mode: the 402 is simulated. - `dev_gate` (bool) — A homologation credential is configured; this grants no access. - `gratis` (string[], opcional) — Temporarily free SKUs. - `facilitator` (string) — URL of the facilitator that verifies and settles the payment. - `asset` (string) — Accepted currency — always `USDC`. - `asset_address` (string) — USDC contract on the network above. - `faucet` (string, pode ser null) — Test-USDC faucet; only on base-sepolia. - `wallets` (object) — Links to wallets that speak x402 (metamask, coinbase, base_app). ### `PaymentCredit` - `url` (string) — POST to purchase credit; GET with X-Credito to inspect its balance. - `header` (string) — Header for a previously issued credit token: X-Credito. ### `DocumentoEmpresa` - `id` (string) — SHA-256 do PDF privado. - `nome` (string) — Nome informado pelo titular. - `tipo` (string) — atestado, certidao, licenca, contrato_social ou outro. - `bytes` (int) — Tamanho do PDF. - `paginas` (int) — Páginas confirmadas no arquivo. - `enviado_em` (string) — Instante do envio. ### `EmpresaConta` Projeção cadastral importada pelo dono, até 24 KiB e 100 CNAEs. Não comprova representação nem habilitação. - `cnpj` (string) — CNPJ completo, 14 dígitos com verificação válida. - `razao_social` (string, pode ser null) — Razão social cadastrada. - `nome_fantasia` (string, pode ser null) — Nome comercial cadastrado. - `situacao` (string, pode ser null) — Situação cadastral. - `situacao_desde` (string, pode ser null) — Data da situação. - `porte` (string, pode ser null) — Porte cadastral. - `natureza_juridica` (string, pode ser null) — Natureza jurídica. - `inicio_atividade` (string, pode ser null) — Data inicial das atividades. - `matriz_filial` (string, pode ser null) — Matriz ou filial. - `capital_social` (number, pode ser null) — Capital social em reais. - `municipio` (string, pode ser null) — Município do estabelecimento. - `uf` (string, pode ser null) — Sigla da unidade da federação. - `cnaes` (AtividadeEmpresa[]) — Principal primeiro; secundários podem não ter descrição. → ver `AtividadeEmpresa` em **Estruturas**. - `fonte` (string) — Crédito de procedência do cadastro. - `importado_em` (string) — Instante da importação; não é a data de atualização do cadastro. ### `Acervo` Tamanho do acervo lido na origem. - `compras` (int) — Compras públicas indexadas. - `documentos_lidos` (int) — Documentos com texto extraído e disponível. ### `Documento` Um documento da compra e os caminhos para leitura ou geração explícita. - `id` (int) — Identificador do documento — é ele que se pede em markdown. - `titulo` (string, pode ser null) — Título do documento no PNCP. - `tipo` (string, pode ser null) — Tipo declarado (edital, anexo, ata…). - `sequencial` (int, pode ser null) — Sequencial do documento dentro da compra no PNCP. - `publicado_em` (string, pode ser null) — Publicação do documento no PNCP. - `caracteres` (int, pode ser null) — Tamanho do texto extraído, em caracteres. - `paginas` (int, pode ser null) — Páginas do documento original. - `motor` (string, pode ser null) — Identificador da extração usada nesta versão. - `formato` (string) — `markdown` quando a extração é estruturada; `plain` no resto. - `sha256` (string, pode ser null) — Hash do texto extraído na origem. - `extraido_em` (string, pode ser null) — Quando a extração rodou. - `gratuito` (bool) — True somente nos cinco exemplos gratuitos; demais documentos exigem compra individual. - `preco_usd` (string, pode ser null) — Nulo até consultar a cotação em /geracao. - `markdown_url` (string) — Onde pedir o markdown deste documento. - `geracao_url` (string) — GET acompanha e informa cotação; POST compra acesso individual, inclusive ao texto pronto. - `preco_pagina_usd` (string) — US$ 0,02 por página no site e API; consulte /geracao para confirmar páginas e total. - `disponivel` (bool) — Há texto pronto ou arquivo disponível para geração autorizada. ### `Regime` Acesso individual pago, independentemente da data ou de o texto já estar pronto. - `gratuito` (bool) — False: a compra não libera documentos para todos; exemplos são marcados individualmente. - `motivo` (string) — `acesso_individual`. - `idade_dias` (int, pode ser null) — Dias desde a publicação no PNCP. ### `Prazos` Os relógios da compra: proposta vem do PNCP; impugnação é estimada pela lei, com feriados nacionais. - `proposta_inicio` (string, pode ser null) — Início do recebimento de propostas. - `proposta_ate` (string, pode ser null) — Fim do recebimento de propostas (abertura da sessão). - `proposta_aberta` (bool) — Se ainda dá para enviar proposta agora. - `impugnacao_ate` (string, pode ser null) — Último dia (AAAA-MM-DD) para impugnar: 3 dias úteis antes da sessão, Lei 14.133 art. 164. - `impugnacao_aberta` (bool) — Se hoje, em Brasília, ainda cabe impugnação. - `estimado` (bool) — Sempre `true`: feriado municipal não está em base nenhuma. - `base_legal` (string, pode ser null) — Regra usada na impugnação. - `feriados` (string) — Calendário considerado: `nacionais`. - `motivo` (string, pode ser null) — Por que não há impugnação: `sem_data_de_encerramento` ou `amparo_sem_regra`. ### `ListaHabilitacao` Exigências de habilitação por família, mais as marcações que o edital traz em texto. - `juridica` (Exigencia[]) — Habilitação jurídica: ato constitutivo, registro, procuração… → ver `Exigencia` em **Estruturas**. - `fiscal_social_trabalhista` (Exigencia[]) — Regularidade fiscal, social e trabalhista: CND federal, FGTS, CNDT… → ver `Exigencia` em **Estruturas**. - `economico_financeira` (Exigencia[]) — Qualificação econômico-financeira: balanço, certidão de falência, índices. → ver `Exigencia` em **Estruturas**. - `tecnica` (Exigencia[]) — Qualificação técnica: atestados, registro em conselho, equipe. → ver `Exigencia` em **Estruturas**. - `exclusivo_me_epp` (bool, pode ser null) — Nulo: participação condicionada por item/lote está nos fatos do dossiê. - `impugnacao_texto` (string, pode ser null) — Nulo nesta projeção: consulte os prazos e condições no dossiê. - `proposta_texto` (string, pode ser null) — Nulo nesta projeção: consulte os prazos e condições no dossiê. - `total` (int) — Exigências aceitas, somando as quatro famílias. - `descartados` (int) — Zero nesta projeção; a validação ocorre durante a preparação do dossiê. ### `PrecosConsulta` - `q` (string) — Termo pesquisado. - `expressao` (string) — Expressão FULLTEXT executada, com os prefixos obrigatórios. - `uf` (string, pode ser null) — UF filtrada. - `catmat` (string, pode ser null) — Código de catálogo filtrado. - `meses` (int) — Janela de homologação, em meses. - `desde` (string) — Primeira data de homologação considerada, `AAAA-MM-DD`. - `limite` (int) — Teto de itens pedido. ### `PrecosEstatisticas` - `total` (int) — Quantos valores unitários entraram na conta. - `media` (number, pode ser null) — Média dos valores unitários, em reais. - `mediana` (number, pode ser null) — Mediana dos valores unitários. - `menor` (number, pode ser null) — Menor valor unitário. - `maior` (number, pode ser null) — Maior valor unitário. - `desvio_padrao` (number, pode ser null) — Desvio padrão populacional. ### `PrecosResumo` O preço que ganha: distribuição dos valores unitários homologados de todos os candidatos. - `n` (int) — Resultados homologados válidos no período. - `mediana` (number, pode ser null) — Mediana dos valores unitários, em reais. - `p25` (number, pode ser null) — Primeiro quartil (25 % dos resultados abaixo). - `p75` (number, pode ser null) — Terceiro quartil (75 % dos resultados abaixo). - `menor` (number, pode ser null) — Menor valor unitário. - `maior` (number, pode ser null) — Maior valor unitário. - `media` (number, pode ser null) — Média dos valores unitários. - `desconto_mediano` (number, pode ser null) — Mediana de `1 − homologado/estimado` nos itens com referência do órgão: `0.10` é 10 % abaixo do estimado. - `com_referencia` (int) — Quantos resultados tinham valor unitário estimado pelo órgão. - `me_epp` (number, pode ser null) — Fração dos resultados vencidos por ME ou EPP, de 0 a 1. - `valor_total` (number, pode ser null) — Soma dos valores totais homologados, em reais. - `fornecedores` (int) — Fornecedores distintos — n alto com 1 fornecedor é uma compra só. - `compradores` (int) — Órgãos distintos. - `ultima_homologacao` (string, pode ser null) — Data do resultado mais recente, `AAAA-MM-DD`. ### `PrecosPorUf` - `uf` (string) — Sigla da UF do órgão comprador. - `n` (int) — Resultados na UF. - `mediana` (number, pode ser null) — Mediana dos valores unitários na UF. - `menor` (number, pode ser null) — Menor valor unitário na UF. - `maior` (number, pode ser null) — Maior valor unitário na UF. - `fornecedores` (int) — Fornecedores distintos na UF. - `compradores` (int) — Órgãos distintos na UF. - `ultima_homologacao` (string, pode ser null) — Resultado mais recente na UF, `AAAA-MM-DD`. ### `PrecosPorMes` - `mes` (string) — `AAAA-MM` da homologação. - `n` (int) — Resultados no mês; `0` quando não houve. - `mediana` (number, pode ser null) — Mediana dos valores unitários no mês. - `menor` (number, pode ser null) — Menor valor unitário no mês. - `maior` (number, pode ser null) — Maior valor unitário no mês. ### `PrecoVencedor` Quem ganha este item: um fornecedor, com o que venceu no período. - `fornecedor_cnpj` (string, pode ser null) — CNPJ, só dígitos; nulo para pessoa física (CPF não é publicado). - `pessoa_fisica` (bool) — `true` quando o vencedor é pessoa física. - `fornecedor` (string, pode ser null) — Razão social ou nome, como publicado. - `porte` (string, pode ser null) — Porte declarado (ME, EPP, Demais). - `itens` (int) — Itens homologados para este fornecedor. - `valor_total` (number, pode ser null) — Soma dos valores totais homologados, em reais. - `menor` (number, pode ser null) — Menor valor unitário que este fornecedor levou. - `maior` (number, pode ser null) — Maior valor unitário que este fornecedor levou. - `compradores` (int) — Órgãos distintos que compraram dele. - `ultima_homologacao` (string, pode ser null) — Última vitória, `AAAA-MM-DD`. ### `PrecoComprador` Quem compra este item: um órgão, com quantas vezes e quando comprou. - `orgao_cnpj` (string, pode ser null) — CNPJ do órgão, só dígitos. - `orgao` (string, pode ser null) — Órgão comprador. - `uf` (string, pode ser null) — UF do órgão. - `itens` (int) — Itens homologados por este órgão. - `compras` (int) — Compras distintas (processos) em que o item foi homologado. - `valor_total` (number, pode ser null) — Soma dos valores totais homologados, em reais. - `fornecedores` (int) — Fornecedores distintos que venderam a ele. - `ultima_homologacao` (string, pode ser null) — Última compra homologada, `AAAA-MM-DD`. ### `PrecosAmostra` - `candidatos` (int) — Itens que o FULLTEXT achou para o termo (antes do período, UF e catálogo). - `limitada` (bool) — `true` quando os candidatos bateram no teto de 2.000: há mais itens parecidos do que o resumo viu. - `criterio` (string) — Como os candidatos foram escolhidos. - `desde` (string) — Primeira homologação considerada, `AAAA-MM-DD`. - `ate` (string, pode ser null) — Última homologação encontrada, `AAAA-MM-DD`. ### `PrecoHomologado` Um item homologado de uma compra pública: valor, fornecedor e órgão comprador. - `compra_id` (int) — Compra no acervo — abre a ficha em `compra_url`. - `item` (int) — Número do item dentro da compra. - `resultado` (int) — Sequencial do resultado (mais de um vencedor em registro de preços). - `pncp` (string, pode ser null) — Número de controle PNCP da compra. - `referencia` (string) — `PNCP · item `, pronto para citar na memória de cálculo. - `descricao` (string, pode ser null) — Descrição do item, como publicada. - `unidade` (string, pode ser null) — Unidade de medida do item. - `catmat` (string, pode ser null) — Código do item no catálogo do governo (CATMAT/CATSER). - `material_ou_servico` (string, pode ser null) — `M` material ou `S` serviço. - `valor_unitario` (number) — Valor unitário homologado, em reais. - `valor_unitario_estimado` (number, pode ser null) — Valor unitário estimado pelo órgão antes da disputa. - `quantidade_homologada` (number, pode ser null) — Quantidade adjudicada ao fornecedor vencedor, na unidade do item. - `fornecedor` (string, pode ser null) — Razão social do fornecedor vencedor. - `fornecedor_cnpj` (string, pode ser null) — CNPJ do fornecedor, só dígitos; nulo para pessoa física (CPF não é publicado). - `pessoa_fisica` (bool) — `true` quando o vencedor é pessoa física. - `fornecedor_porte` (string, pode ser null) — Porte do fornecedor (ME, EPP, demais). - `orgao` (string, pode ser null) — Órgão comprador. - `orgao_cnpj` (string, pode ser null) — CNPJ do órgão, só dígitos. - `municipio` (string, pode ser null) — Município da unidade compradora. - `uf` (string, pode ser null) — UF do órgão. - `modalidade` (string, pode ser null) — Modalidade da compra. - `homologado_em` (string, pode ser null) — Data do resultado, `AAAA-MM-DD`. - `publicado_em` (string, pode ser null) — Data de publicação da compra no PNCP, `AAAA-MM-DD`. - `compra_url` (string) — Ficha pública da compra. ### `OrigemCnae` A empresa e a atividade (CNAE) que geraram um alerta por CNPJ. - `cnpj` (string) — CNPJ da empresa, 14 dígitos. - `familia` (string) — Identificador da família de termos no dicionário. - `cnae` (string) — O primeiro CNAE da empresa que acionou a família, 7 dígitos. - `descricao` (string, pode ser null) — Descrição oficial (IBGE) desse CNAE. - `cnaes` (string[]) — Todos os CNAEs da empresa que caem nesta família. ### `CnaeDaEmpresa` Um CNAE da empresa e o que o dicionário faz com ele. - `codigo` (string) — 7 dígitos. - `cnae` (string) — Formatado como o IBGE escreve, ex. `1412-6/01`. - `descricao` (string, pode ser null) — Descrição oficial. - `principal` (bool) — Se é o CNAE principal da empresa. - `familia` (string, pode ser null) — Família de termos que este CNAE aciona; nulo fora do dicionário. - `termos` (string, pode ser null) — Os termos dessa família; nulo fora do dicionário. ### `ApiAccessOffer` - `id` (string) — Package identifier. - `price_usd` (number) — Price in USD. - `credits` (int) — Basic reads included. - `days` (int) — Validity after payment, in days. - `auto_renew` (bool) — False: the client explicitly buys another package. - `unit` (string) — basic_data_read; one page of up to 20 metadata records. - `products` (string[]) — Data indexes sharing the same package. - `purchase` (string) — Absolute purchase URL. - `method` (string) — HTTP method for the explicit package purchase: POST. - `status` (string) — GET with X-API-Pass checks the private purchase status. - `header` (string) — X-API-Pass. - `payment_methods` (string[]) — x402 or prepaid_credit. - `instructions` (string) — Generate and retain the pass before payment. - `generate_pass` (string) — JavaScript example using cryptographic randomness. - `client` (string, pode ser null) — Auditable ES module client; orchestrates purchase and data retry with caller-owned wallet and durable state. - `guide` (string, pode ser null) — Client setup, explicit budget, recovery and data value. - `workflow` (ApiAccessWorkflow) — Machine-readable purchase and recovery contract. → ver `ApiAccessWorkflow` em **Estruturas**. - `evaluation` (object, pode ser null) — Free evaluation: register URL, X-Agent-Pass header, 1,000 reads per product, 30 days, no renewal. Registration grants independent quotas on the three indexes; preserve the credential. ### `PaymentFree` - `o_que` (string) — Operation or allowance. - `limite` (string) — Allowance and eligibility. - `janela` (string, pode ser null) — Reset window, when applicable. ### `PaymentPrice` - `o_que` (string) — Operation and billing unit. - `price_usd` (number) — Current list price in USD. ### `PaymentTrial` - `days` (int) — Trial duration in days. - `how` (string) — Eligibility and activation steps. ### `AtividadeEmpresa` - `codigo` (string) — Código de 7 dígitos. - `descricao` (string, pode ser null) — Descrição conhecida. - `principal` (bool) — Atividade principal. ### `Exigencia` Um documento ou requisito de habilitação e a linha do edital que o exige. - `exigencia` (string) — Descrição curta, ex.: `Certidão negativa de débitos trabalhistas (CNDT)`. - `trecho` (string) — Trecho literal conferido no Markdown, até 4000 caracteres. - `pagina` (int) — Página física da primeira evidência. - `fato_id` (int) — Identidade do fato no dossiê versionado. - `condicao` (string, pode ser null) — Quando se aplica. - `excecoes` (string, pode ser null) — Ressalvas da fonte. - `evidencias` (object[]) — Todos os trechos com página e offsets UTF-16. ### `ApiAccessWorkflow` - `version` (int) — Workflow version. - `kind` (string) — package_then_retry: buy at purchase, then retry the original data URL. - `purchase_requires_authority` (bool) — The client needs an explicit spending budget. - `retry_same_pass` (bool) — Persist the pass and original signed proof before submitting. - `on_unknown_payment` (string) — Query the purchase or reconcile the original proof; never sign again automatically. ## Acervos públicos de dados Explore endereços e compras por lugar e abra os registros de que precisa. Até 20 itens por página, em formatos prontos para pessoas e agentes. Confira a cobertura e a data de referência antes de usar um resultado. Cada produto informa suas opções de acesso. - [CEPs e endereços](https://api.pontofato.com/enderecos/index.json): Encontre endereços por lugar, com coordenadas e referência de 2022. Não certifica CEP vigente. UF → município → bairro/localidade → rua → endereços. [HTML](https://api.pontofato.com/enderecos/) · [llms.txt](https://api.pontofato.com/enderecos/llms.txt) · [OKF](https://api.pontofato.com/enderecos/okf/index.md) - [Editais e compras públicas](https://api.editalmd.com/licitacoes/index.json): Encontre compras públicas por lugar e período. Consulte documentos e opções de leitura no EditalMD. Modalidade → UF → ano → mês → dia → município → compras. [HTML](https://api.editalmd.com/licitacoes/) · [llms.txt](https://api.editalmd.com/licitacoes/llms.txt) · [OKF](https://api.editalmd.com/licitacoes/okf/index.md)