O que há de novo na QAPI

Duas novidades para você conhecer melhor o que a base QAPI oferece: uma página aberta com a composição completa das questões e novos campos de localização nos concursos, com filtros na API, no MCP e no site.

• Nova página Estatísticas — sem necessidade de login. Gráficos de pizza mostram o percentual de questões por cargo, banca (pela sigla), órgão, ano da prova e disciplina, e, para cada uma das 10 disciplinas com mais questões, os assuntos mais cobrados.
• Os 10 maiores de cada grupo, o resto em “Outros”: cada gráfico destaca os 10 maiores itens e soma os demais em uma única fatia, para a leitura continuar clara mesmo com centenas de bancas, órgãos e assuntos.
• Gráficos de barras abertos a todos: o ranking de questões por disciplina e por banca e a distribuição por ano, que antes só apareciam para usuários logados em Analytics, agora fazem parte da página pública.
• Atualização diária: os números são recalculados uma vez por dia (de madrugada) e a página informa a data da última atualização — a consulta é rápida e não pesa na base.
• Concursos por região e estado: todo concurso agora traz regiao (norte, nordeste, centro-oeste, sudeste, sul ou nacional), estado (ex.: “Paraíba”) e siglaEstado (ex.: “PB”). A região é derivada do estado; concursos nacionais não têm estado.
• Novos filtros em GET /api/concursos e na ferramenta MCP get_concursos: regiao, estado (nome ou sigla, sem distinção de acento) e siglaEstado, combináveis com os filtros existentes. Valores inexistentes retornam 400. A página Concursos também ganhou os seletores de região e estado.
• Compatibilidade: o campo estado, que guardava só a sigla, agora traz o nome completo — a sigla passou para siglaEstado. Nenhum campo foi removido nem exige mudança de custo: as requisições continuam consumindo 1 cota (2 via MCP).

Passamos a hospedar em nuvem os PDFs originais das provas e dos gabaritos processados pelo nosso pipeline, com acesso permanente aos arquivos pela API. Manter esses arquivos armazenados e entregá-los gera um custo próprio — de armazenamento e de transferência de dados — que se soma ao do servidor e do banco de dados. Por isso, a rota de provas passa a ter uma tarifa diferenciada, descontada do seu saldo de cotas.

• R$ 1,00 por requisição (100 cotas) em GET /api/provas e GET /api/provas/:id — as demais rotas continuam custando 1 cota (R$ 0,01).
• Até 10 provas por requisição (size máximo continua sendo 10): o custo equivale a ≈ R$ 0,10 por prova com link de PDF de prova e gabarito.
• Via MCP o custo é o dobro: get_provas e get_prova_por_id consomem 200 cotas por chamada, seguindo a regra do MCP (2x o valor da requisição REST equivalente). As descrições das ferramentas já avisam o preço ao agente.
• Só paga quem recebe: a cobrança ocorre apenas quando a resposta é 200. Prova não encontrada (404) ou falha do nosso lado (502) não consomem cotas.
• Saldo insuficiente: com menos de 100 cotas, a rota de provas responde 402 — sem consumir nada e sem chamar o armazenamento — informando o custo (cost_quota) e o seu saldo. O restante da API continua funcionando normalmente com saldo baixo.
• Por que cobrar mais aqui? o download em massa de PDFs também gera custo por volume de transferência no serviço de hospedagem. A tarifa diferenciada embute esse custo no acesso aos arquivos originais, em vez de repassá-lo a todos os usuários da API.
• Demonstrativo mensal: o PDF/e-mail do demonstrativo ganhou a linha “Acesso às provas”, com as requisições à tarifa diferenciada e as cotas adicionais — o total consumido continua fechando com o seu saldo.

Esta versão traz um identificador estável para cada questão, formatação rica em enunciados e alternativas, correções na documentação de paginação e um novo ritmo de crescimento da base. Atenção ao item de Markdown: se você exibe enunciados e alternativas como texto simples, é preciso ajustar sua aplicação.

• Novo campo qCode em toda questão: um código externo único e estável no formato Q-XXXXXXX (ex.: Q-7KD4M2P). Ele nunca muda depois de criado — use-o como chave da questão na sua aplicação, no lugar do _id interno do banco.
• Busca pelo qCode: o filtro qCode foi adicionado a GET /api/questoes (combina com os demais filtros; aceita o código sem o prefixo e em minúsculas; código inexistente retorna lista vazia) e à ferramenta MCP get_questoes. O Playground também ganhou o campo.
• Markdown em enunciados e alternativas (importante): as bancas destacam o termo cobrado dentro do próprio enunciado e da alternativa, e servir texto puro apagava parte desse destaque. Por isso enunciado e opcaoA–opcaoE agora podem trazer Markdown (negrito, itálico, sublinhado, listas...). Se você renderizava esses campos como texto, as marcações vão aparecer cruas na tela (ex.: **termo**) — renderize Markdown na sua aplicação e sanitize o HTML resultante.
• Paginação: 10 itens por página em todas as listagens. A documentação de Provas e Concursos (e de Flashcards) ainda indicava máximo de 100; o correto — e o que sempre foi aplicado — é 10. Corrigimos a documentação, os exemplos de código (que usavam size=20) e passamos a aplicar o limite também nos catálogos (bancas, órgãos, cargos, matérias e assuntos) e nas ferramentas MCP equivalentes. Valores maiores que 10 são reduzidos para 10 automaticamente.
• Base com mais de 27.000 questões — e crescendo. A regra antiga de 250 questões por dia foi encerrada: a partir de 11/10/2026 o pipeline processa 1 prova por hora, 24 provas por dia. O total de questões novas varia conforme a quantidade de questões de cada prova.
• Vantagens em destaque na documentação: o crédito não expira (as cotas ficam na conta até serem usadas) e gabarito e comentário vêm inclusos em cada questão, sem custo extra. Também corrigimos a tabela de recargas da documentação, que ainda mostrava os valores antigos.
• Termos de Serviço v1.4: nova seção 03-B · Vedação a Serviços Concorrentes. A base de questões pode ser usada livremente como parte de projetos educacionais (apps de estudo, simulados, plataformas de cursos), mas não pode ser usada para criar, alimentar ou operar um serviço concorrente nem ser redistribuída como base, API ou dataset.
• Estabilidade: o servidor de questões que alimenta a QAPI passou a aplicar um limite de 1.000 requisições por minuto, dimensionado para a demanda dos clientes, protegendo a base contra picos de tráfego e mantendo o tempo de resposta estável para todos.

Hoje, por uma falha nossa, clientes que já haviam adquirido créditos antecipados receberam por e-mail uma fatura de cobrança do mês. Essa fatura não era devida: o QAPI é pré-pago desde 01/08/2026 e o consumo já é debitado do saldo de cotas que você pagou ao recarregar. Pedimos desculpas pelo transtorno — desconsidere qualquer fatura recebida; não há nada a pagar.

• O que causou o erro: a rotina de fechamento mensal ainda tratava o registro de uso como "consumo pós-pago a cobrar". Como esse registro voltou a ser gravado a cada requisição (para os gráficos do dashboard), todo cliente com uso passou a parecer devedor.
• Correção definitiva: a fatura foi removida do sistema, e não apenas desativada — junto com o QR Code PIX de cobrança, o envio de fatura por e-mail e a suspensão automática por fatura em aberto. Sem esse código, o sistema não tem mais como gerar valor a pagar.
• Novo demonstrativo mensal de uso: no último dia de cada mês você recebe por e-mail (com PDF anexo) o quanto consumiu do seu saldo naquele mês — requisições REST e MCP, cotas consumidas (MCP conta em dobro), recargas creditadas no período — e o saldo de cotas que ainda tem disponível. É um documento puramente informativo, sem valor a pagar nem vencimento.
• Quem recebe: apenas clientes com saldo de cotas maior que zero. Cada cliente recebe no máximo um demonstrativo por mês, mesmo que o envio seja repetido por algum motivo técnico.
• Consulte quando quiser: em /payments, a antiga tabela de faturas virou Demonstrativos mensais de uso, com o PDF de cada mês em que você usou a API. O saldo exibido no PDF é o da data de emissão.

GET /api/questoes (e a ferramenta MCP get_questoes) ganharam um novo filtro enunciado — busca textual livre no texto da questão — e os filtros banca/orgao agora casam tanto pelo nome completo quanto pela sigla da instituição, nos dois sentidos.

• Novo filtro enunciado: busca parcial, case-insensitive, no texto da questão — ex: ?enunciado=direitos+fundamentais.
• Busca por sigla: ?banca=FGV agora encontra questões salvas com o nome completo ("Fundação Getulio Vargas") e vice-versa — o mesmo vale para orgao. GET /api/bancas e /api/orgaos também passaram a aceitar sigla no parâmetro search.
• Novos campos na resposta: cada questão agora traz siglaBanca/siglaOrgao (a sigla resolvida no catálogo; null quando não cadastrada) — opcionais de usar, já que o filtro cobre os dois formatos automaticamente.

Lançamos o QAPI MCP Server: todos os métodos da API hoje disponíveis para clientes com API Key ativa e saldo agora também estão acessíveis via Model Context Protocol (MCP) — o padrão aberto que Claude, ChatGPT e outros agentes de IA usam para chamar ferramentas externas. Ver a documentação completa em destaque na página inicial.

• Endpoint único: https://qapi.otunac.com/mcp, autenticado pela mesma Q-Api-Key da sua conta.
• 26 ferramentas — uma para cada endpoint hoje protegido por API Key (questões, textos, provas, concursos, disciplinas, conteúdo programático, flashcards, apostilas, simulados, comentários e suporte), descobertas automaticamente pelo agente.
• Custo em dobro por chamada: cada chamada de ferramenta via MCP debita 2 cotas — o dobro de uma requisição REST equivalente (1 cota), pelo mesmo saldo pré-pago de sempre. Agentes de IA, sobretudo em fluxos multi-agente/paralelos, tendem a multiplicar requisições em relação a um cliente tradicional; o custo em dobro contém abuso sem proibir o uso legítimo.
• Erros legíveis pelo agente: chave ausente/inválida/suspensa, saldo insuficiente ou recurso não encontrado chegam como um resultado de erro (isError: true) com mensagem clara — sem consumir cotas nem quebrar o fluxo do agente.

A recarga de cotas passa a ser 100% automática: o PIX agora é gerado e confirmado diretamente pelo gateway de pagamento, sem mais espera por confirmação manual da nossa equipe nem envio de comprovante. Junto com essa mudança, a diretoria aprovou um reajuste de tarifa e uma nova cláusula nos Termos de Serviço, detalhados abaixo.

• PIX automático: ao clicar em "Gerar PIX e Pagar" em /payments, o QR Code e o código copia-e-cola são gerados na hora pelo gateway; assim que o pagamento é confirmado, as cotas são creditadas automaticamente na sua conta — normalmente em segundos.
• Motivo do reajuste: identificamos, após avaliação da diretoria, que parte dos usuários vinha utilizando a API para copiar a base de questões por completo — não para consumir o serviço, mas para reaproveitar o conteúdo em aplicativos próprios. Para preservar o modelo de negócio sem proibir o uso legítimo da API, decidimos tornar esse tipo de cópia proporcional ao seu custo real.
• Limite de itens por requisição reduzido: de 100 para 10 itens por chamada em todos os endpoints de listagem.
• Tarifa por requisição reajustada: de R$ 0,50 para R$ 10,00 a cada 1.000 requisições (R$ 0,01/requisição; R$ 1,00 = 100 cotas). Na prática, obter a base inteira (~21.000 questões, a 10 itens/requisição) custa hoje ~R$ 21,00 via uso normal da API — valor que cresce junto com a base e que poderá ser reajustado novamente no futuro conforme a diretoria avaliar o padrão de uso.
• Novo ticket de entrada: de R$ 5,00 por 10.000 cotas para R$ 50,00 por 5.000 cotas. Recarga mínima de R$ 50,00, sempre em múltiplos de R$ 50,00.
• Termos de Serviço atualizados (v1.3): nova cláusula "Não Comercialização Direta da Base" — a QAPI não vende cópias da base como produto à parte, mas mantém a política de importação em massa para uso em produtos de terceiros, desde que com atribuição de fonte obrigatória e visível (ex.: "Questões fornecidas por QAPI"), inclusive para conteúdo já importado após o fim do contrato. Também foi formalizado o direito da QAPI de reajustar a tarifa conforme necessidades operacionais da plataforma. Veja os Termos de Serviço completos.

A partir de hoje, a QAPI passa a adotar o modelo de créditos antecipados (pré-pago): a API só responde a requisições de contas com cotas em saldo. Não há mais cobrança pós-paga nem fatura no fim do mês — o consumo é sempre debitado de um saldo pré-carregado.

• Tarifa reduzida pela metade: de R$ 1,00 para R$ 0,50 a cada 1.000 requisições — R$ 1,00 agora equivale a 2.000 cotas.
• Recarga mínima de R$ 5,00, sempre em múltiplos de R$ 5,00 (R$ 5, R$ 10, R$ 15, R$ 20, ...). R$ 5,00 = 10.000 requisições.
• Sem cotas em saldo, todas as chamadas retornam 402 Payment Required com um corpo de erro explicando a mudança de política e como recarregar — nenhuma requisição é processada sem crédito disponível.
• Novos avisos por e-mail: quando o saldo cai abaixo de 1.000 cotas e quando o saldo chega a zero, para você nunca ser pego de surpresa.
• Faturas geradas antes de 01/08/2026, referentes ao modelo de cobrança anterior, continuam disponíveis para consulta em /payments.

A QAPI deixa de ser puramente somente-leitura: agora é possível montar simulados sob demanda, comentar em questões (dúvidas ou gabarito incorreto) e abrir chamados de suporte diretamente pela API, sem sair do seu código.

• GET /api/simulados — monta um simulado na hora a partir de filtros (banca, órgão, cargo, matéria, assunto, ano) e de size (quantidade de questões, máx. 100). Nada é salvo — a mesma chamada devolve uma seleção e ordem diferentes a cada vez.
• POST /api/comentarios e GET /api/comentarios?questao=:id — crie e liste comentários em qualquer questão. PUT e DELETE /api/comentarios/:id editam ou removem um comentário existente.
• POST /api/suporte — abre um chamado (bug na API, questão incorreta, falha de serviço etc.) informando incidente, descrição, nome e e-mail de contato. Este endpoint é intencionalmente apenas para abertura — consulta e gestão dos chamados continuam restritas à equipe QAPI, para não expor dados de um cliente a outro.
• Todos os endpoints novos requerem Q-Api-Key e são contabilizados no billing como qualquer outra requisição.

A partir desta versão, clientes da API podem consultar as provas de concurso armazenadas no sistema. Cada prova reúne metadados do exame e, quando disponível, links diretos para os PDFs da prova e do gabarito oficial.

• GET /api/provas — lista provas com paginação e filtros por banca, órgão, cargo e ano. Ordenação: mais recentes primeiro. Máximo de 100 itens por página.
• GET /api/provas/:id — retorna uma prova pelo ID, incluindo linkProva, linkGabarito e metadados de upload (nome do arquivo, tamanho, data). Retorna 404 quando não encontrada.
• Ambos os endpoints requerem autenticação via header Q-Api-Key.
• Endpoint adicionado ao Playground para testes interativos.

Usuários autenticados passaram a contar com um ambiente de testes integrado e um canal de suporte direto com a equipe.

• Playground — teste qualquer endpoint com sua API Key diretamente no navegador, veja o JSON de resposta e o tempo de execução.
• Chat de suporte em tempo real entre usuários e administradores.
• Painel administrativo de chat com histórico por conversa.

• Geração automática de faturas mensais em PDF.
• Confirmação de pagamento por comprovante PIX.
• Suspensão e reativação de API Keys pelo painel admin.
• Histórico de pagamentos disponível no dashboard do usuário.
• Logs de acesso detalhados por endpoint e API Key.

Primeira versão pública da API de questões de concursos públicos.

• Endpoint GET /api/questoes com filtros por banca, órgão, cargo, matéria, assunto e ano.
• Endpoint GET /api/textos/:codigo para recuperar textos base de questões.
• Catálogos de filtros: /bancas, /orgaos, /cargos, /materias, /assuntos.
• Autenticação via API Key com prefixo qb_.
• Dashboard de uso com gráfico diário e resumo mensal.
• Registro de conta com CPF único por usuário.