Formulix / 0.1.2

Contrato de la API

Rutas de vista previa, confirmación de inserción y tabla periódica.

Autenticación y Origin

X-Formulix-Chave es opcional. Sin clave, el hostname de Origin identifica el sitio: si un dominio registrado lo cubre, rige el plan de esa cuenta; si no, rige el plan Gratuito, contado solo por ese hostname, y la respuesta 402 incluye en planos un enlace de registro. Con clave, esta debe estar activa y el hostname de Origin debe pertenecer a los dominios de la cuenta, incluidos sus subdominios. No se aceptan direcciones IP como origen. El navegador proporciona Origin: no intente establecerlo manualmente con JavaScript. Sin origen válido se rechaza la llamada.

La petición previa OPTIONS acepta cualquier origen con nombre de dominio o de desarrollo, métodos GET/POST y cabeceras Content-Type/X-Formulix-Chave. Con clave, la llamada efectiva verifica además los dominios de la cuenta propietaria de la clave. Las respuestas usan Vary: Origin y Cache-Control: no-store; reflejan el origen permitido, sin comodín. Un origen rechazado puede aparecer solo como error CORS.

La clave es pública, no administrativa. Origin puede falsificarse fuera del navegador. Las revocaciones y cambios de dominio se recargan por defecto aproximadamente cada 5 segundos.

POST /v1/calc — vista previa

Cuerpo JSON: { op, dados, idioma, notacao }. op elige la operación y dados contiene sus parámetros. Idioma por defecto: en; notacao es opcional, por ejemplo { "decimal": "," }. La respuesta JSON depende de la operación: HTML, LaTeX, SVG o datos auxiliares. Una vista previa correcta registra una vista previa y cero inserciones. Los nombres de campos y operaciones son parte del protocolo y se mantienen sin traducir.

const response = await fetch('https://api.formulix.com.br/v1/calc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Formulix-Chave': 'YOUR_PUBLIC_KEY'
  },
  body: JSON.stringify({
    op: 'word', dados: { html: '<p>Texto sin ecuaciones</p>' },
    idioma: 'es-419'
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.erro);

El ejemplo usa placeholders https://api.formulix.com.br y YOUR_PUBLIC_KEY; sin ecuaciones, devuelve { eqs: [] }. Operaciones reconocidas: 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. Los campos de dados varían; use el adaptador para construir las peticiones. No hay un esquema único de parámetros.

POST /v1/inserir — salida final

Incluya tipo, los datos específicos y, opcionalmente, idioma y notacao. La salida es JSON sin envoltura común.

tipo	Entrada	Salida y consumo
formula	latex; bloco opcional	{ html } con MathML; una inserción. LaTeX no vacío, máximo 20 000 caracteres.
word	html; rtf opcional	{ html }; una inserción por ecuación convertida; cero si no hay ecuaciones.
grafico	dados de la operación de gráfica	{ svg, w, h, funcoes, alt }; una inserción.
conta / quimica	op y dados; operación reconocida salvo grafico/word	{ html }, { bloco: true, html } o { svg, w, h, alt }, según la operación; una inserción.

{
  "tipo": "formula",
  "latex": "x^2",
  "bloco": false,
  "idioma": "es-419"
}

Respuesta 200 de la fórmula: { "html": "<math ...>...</math>" }. El cliente convierte SVG a PNG y lo carga mediante la plataforma. La API de cálculo no almacena imágenes. Cada confirmación aceptada cuenta, incluida la reedición; no hay idempotencia por identificador. No repita automáticamente una confirmación si desconoce si la anterior se aceptó.

GET /v1/tabela?idioma=es-419

Devuelve un array de elementos { z, s, nome, pos, cor } para la tabla periódica. Exige un Origin válido (y una clave válida, si se envía) aunque sean datos públicos. No registra inserciones ni vistas previas, pero está sujeto al límite por minuto. Idioma por defecto: inglés.

Límites

Cuerpo: 15 MiB. Las peticiones mayores pueden cerrar la conexión tras responder 413.
Ráfaga: 1 200 peticiones por clave (sin clave: por IP), minuto y proceso; incluye vistas previas y tabla. Con varios procesos no es un tope global.
Plan: 500 / 5 000 / 25 000 inserciones, o Red educativa sin tope numérico. Gratuito limita cuenta y dominio; los pagos suman la cuenta.
Desarrollo: 300 inserciones/mes/cuenta por defecto, configurable con FORMULIX_DEV_LIMITE. Incluye localhost, subdominios .localhost, 127.0.0.1, [::1] y .test. Sin clave, el tope rige por IP.
Consumo sincronizado entre procesos por defecto cada 5 segundos; no es un contador global transaccional por petición. El mes es UTC.

Errores

Los errores de aplicación usan JSON { "erro": "message" }. Los mensajes de validación de cálculos pueden estar traducidos.

400 — Invalid JSON.: JSON inválido o cuerpo que no es un objeto.
401 — Invalid key.: Clave inválida o revocada.
402 — Monthly insertion limit reached.: Tope del plan o del desarrollo; planos trae el enlace de registro o del panel.
403 — Origin not allowed for this key. o Origin not allowed.: Dominio rechazado; un preflight rechazado puede no incluir cuerpo.
404: Unknown route. o Unknown operation.
413 — Request too large.: Cuerpo demasiado grande.
422: Entrada inválida; mensaje en erro.
429 — Rate limit reached.: Demasiadas peticiones por minuto.
500 — Internal error.: Error interno.

/saude devuelve { "ok": true } sin autenticación; no confirma el acceso de una clave al servicio.