Contrato de la API

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

Autenticación y Origin

Envíe X-Formulix-Chave en todas las rutas /v1/*. La clave debe estar activa y el hostname de Origin debe pertenecer a los dominios de la cuenta, incluidos sus subdominios. El navegador proporciona Origin: no intente establecerlo manualmente con JavaScript. Sin origen válido se rechaza la llamada.

La petición previa OPTIONS acepta orígenes registrados en alguna cuenta o de desarrollo, métodos GET/POST y cabeceras Content-Type/X-Formulix-Chave. La llamada efectiva verifica además el dominio 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.example/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.example 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": "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 clave y Origin válidos 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, 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. Sigue siendo obligatoria una clave válida.
• 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 ausente, inválida o revocada.

402 — Monthly insertion limit reached.

Tope del plan o del desarrollo.

403 — Origin not allowed for this key.

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.