Contrato da API

Rotas de prévia, confirmação de inserção e tabela periódica.

Autenticação e Origin

Envie X-Formulix-Chave em todas as rotas /v1/*. A chave deve estar ativa e o hostname de Origin deve pertencer aos domínios da conta, incluindo subdomínios. O navegador fornece Origin: não tente defini-lo manualmente no JavaScript. Sem origem válida, a chamada é recusada.

O preflight OPTIONS aceita origens cadastradas em alguma conta ou de desenvolvimento, métodos GET/POST e cabeçalhos Content-Type/X-Formulix-Chave. A chamada efetiva ainda verifica o domínio da conta dona da chave. Respostas usam Vary: Origin e Cache-Control: no-store. A origem permitida é refletida, sem curinga. Origem recusada pode aparecer apenas como erro de CORS no navegador.

A chave é pública, não administrativa; Origin pode ser forjado fora de navegadores. Revogações e alterações de domínios são recarregadas por padrão em cerca de 5 segundos.

POST /v1/calc — prévia

Corpo JSON: { op, dados, idioma, notacao }. op seleciona a operação e dados contém seus parâmetros. Idioma padrão: en; notacao é opcional (por exemplo { "decimal": "," }). A resposta JSON depende da operação: HTML, LaTeX, SVG ou dados auxiliares. Prévia bem-sucedida registra 1 prévia e 0 inserções.

const resposta = await fetch('https://api.formulix.example/v1/calc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Formulix-Chave': 'CHAVE_PUBLICA_DO_CLIENTE'
  },
  body: JSON.stringify({
    op: 'word', dados: { html: '<p>Texto sem equações</p>' },
    idioma: 'pt-BR'
  })
});
const resultado = await resposta.json();
if (!resposta.ok) throw new Error(resultado.erro);
// Neste exemplo: { eqs: [] }

Operações reconhecidas: divisao, multiplicacao, adicao, subtracao, ruffini, mmc, fatoracao, fracoes, regra3, eq1, eq2, sistema, tabela, estudo, grafico, qeq, qmassa, qdist, qvid, qtit, qpaul, qorg, qcad, qtab, word. Os campos de dados variam conforme a operação; use o adaptador para montar esses pedidos. Não há esquema único de parâmetros.

POST /v1/inserir — saída final

O corpo inclui tipo, dados específicos abaixo e, opcionalmente, idioma e notacao. A saída é JSON, sem envelope comum.

// Corpo de uma fórmula; use os mesmos cabeçalhos da prévia.
{
  "tipo": "formula",
  "latex": "x^2",
  "bloco": false,
  "idioma": "pt-BR"
}
// Resposta 200: { "html": "<math ...>...</math>" }

O cliente transforma SVG em PNG e faz upload pela plataforma. A API de cálculo não armazena imagens. Cada confirmação aceita é contabilizada, inclusive reedição; não há idempotência por identificador. Evite repetir automaticamente uma confirmação quando não souber se a primeira foi aceita.

GET /v1/tabela?idioma=pt-BR

Retorna um array de elementos { z, s, nome, pos, cor } para a grade periódica. Exige chave e Origin válidos apesar de serem dados públicos. Não registra inserção nem prévia; está sujeito ao limite por minuto. Idioma padrão: inglês.

Limites

• Corpo: até 15 MiB. Pedidos maiores podem ter a conexão encerrada após a resposta 413.
• Rajada: 1.200 pedidos por chave por minuto, por processo, incluindo prévias e tabela. Com vários processos, esse teto não é global.
• Plano: 500 / 5.000 / 25.000 inserções ou Rede sem teto numérico. Grátis tem teto por conta e domínio; pagos somam a conta.
• Desenvolvimento: teto separado padrão de 300 inserções/mês/conta, configurável por FORMULIX_DEV_LIMITE. Inclui localhost, subdomínios .localhost, 127.0.0.1, [::1] e domínios .test. Uma chave válida continua obrigatória.
• Consumo sincronizado entre processos por padrão a cada 5 segundos: não é contador global transacional por pedido. O mês é UTC.

Erros

Erros de aplicação usam JSON { "erro": "mensagem" }. Validações de cálculo podem ter mensagens traduzidas.

/saude retorna { "ok": true } sem autenticação; não confirma acesso de uma chave ao serviço.