Formulix / 0.1.0

Contrat de l’API

Routes d’aperçu, de confirmation d’insertion et de tableau périodique.

Authentification et Origin

Envoyez X-Formulix-Chave sur toutes les routes /v1/*. La clé doit être active et le nom d’hôte d’Origin appartenir aux domaines du compte, sous-domaines compris. Le navigateur fournit Origin : ne tentez pas de le définir manuellement en JavaScript. Sans origine valide, l’appel est refusé.

La requête préliminaire OPTIONS accepte les origines enregistrées dans un compte ou de développement, les méthodes GET/POST et les en-têtes Content-Type/X-Formulix-Chave. L’appel effectif vérifie encore le domaine du compte propriétaire de la clé. Les réponses utilisent Vary: Origin et Cache-Control: no-store. L’origine autorisée est reprise sans joker. Une origine refusée peut n’apparaître que comme une erreur CORS.

La clé est publique et non administrative ; Origin peut être falsifié hors navigateur. Les révocations et modifications de domaines sont rechargées par défaut environ toutes les 5 secondes.

POST /v1/calc — aperçu

Corps JSON : { op, dados, idioma, notacao }. op choisit l’opération et dados contient ses paramètres. Langue par défaut : en ; notacao est facultatif, par exemple { "decimal": "," }. La réponse JSON dépend de l’opération : HTML, LaTeX, SVG ou données auxiliaires. Un aperçu réussi enregistre un aperçu et zéro insertion. Les noms des champs et opérations appartiennent au protocole et ne se traduisent pas.

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>Texte sans équations</p>' },
    idioma: 'fr'
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.erro);

L’exemple utilise les placeholders https://api.formulix.example et YOUR_PUBLIC_KEY ; sans équation, il renvoie { eqs: [] }. Opérations reconnues : 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. Les champs de dados varient ; utilisez l’adaptateur pour construire les requêtes. Il n’existe pas de schéma unique de paramètres.

POST /v1/inserir — sortie finale

Le corps comprend tipo, les données spécifiques et, facultativement, idioma et notacao. La sortie est du JSON sans enveloppe commune.

tipo	Entrée	Sortie et décompte
formula	latex ; bloco facultatif	{ html } avec MathML ; une insertion. LaTeX non vide, 20 000 caractères maximum.
word	html ; rtf facultatif	{ html } ; une insertion par équation convertie, zéro sans équation.
grafico	dados de l’opération graphique	{ svg, w, h, funcoes, alt } ; une insertion.
conta / quimica	op et dados ; opération reconnue sauf grafico/word	{ html }, { bloco: true, html } ou { svg, w, h, alt }, selon l’opération ; une insertion.

{
  "tipo": "formula",
  "latex": "x^2",
  "bloco": false,
  "idioma": "fr"
}

Réponse 200 de la formule : { "html": "<math ...>...</math>" }. Le client convertit le SVG en PNG et le téléverse via la plateforme. L’API de calcul ne stocke pas les images. Chaque confirmation acceptée est comptée, y compris une modification ; aucune idempotence par identifiant. Ne répétez pas automatiquement une confirmation si vous ignorez si la première a été acceptée.

GET /v1/tabela?idioma=fr

Renvoie un tableau d’éléments { z, s, nome, pos, cor } pour la grille périodique. Clé et Origin valides sont exigés malgré le caractère public des données. Aucun aperçu ni insertion comptabilisé ; le plafond par minute s’applique. Langue par défaut : anglais.

Limites

Corps : 15 MiB. Une requête plus grande peut entraîner la fermeture de la connexion après la réponse 413.
Rafale : 1 200 requêtes par clé, minute et processus, aperçus et tableau inclus. Avec plusieurs processus, ce plafond n’est pas global.
Forfait : 500 / 5 000 / 25 000 insertions, ou Réseau sans plafond numérique. Gratuit limite compte et domaine ; les forfaits payants totalisent le compte.
Développement : 300 insertions/mois/compte par défaut, configurable par FORMULIX_DEV_LIMITE. Inclut localhost, sous-domaines .localhost, 127.0.0.1, [::1] et .test. Une clé valide reste obligatoire.
Consommation synchronisée entre processus par défaut toutes les 5 secondes ; ce n’est pas un compteur global transactionnel par requête. Le mois est UTC.

Erreurs

Les erreurs applicatives utilisent du JSON { "erro": "message" }. Les messages de validation des calculs peuvent être traduits.

400 — Invalid JSON.: JSON invalide ou corps qui n’est pas un objet.
401 — Invalid key.: Clé absente, invalide ou révoquée.
402 — Monthly insertion limit reached.: Plafond du forfait ou du développement.
403 — Origin not allowed for this key.: Domaine refusé ; un preflight refusé peut être sans corps.
404: Unknown route. ou Unknown operation.
413 — Request too large.: Corps trop volumineux.
422: Entrée invalide ; message dans erro.
429 — Rate limit reached.: Trop de requêtes par minute.
500 — Internal error.: Erreur interne.

/saude renvoie { "ok": true } sans authentification ; cela ne confirme pas qu’une clé a accès au service.