Formulix / 0.1.2

Contrat de l’API

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

Authentification et Origin

X-Formulix-Chave est facultatif. Sans clé, le nom d’hôte d’Origin identifie le site : si un domaine enregistré le couvre, le forfait de ce compte s’applique ; sinon, le forfait Gratuit s’applique, compté pour ce seul nom d’hôte, et la réponse 402 fournit un lien d’inscription dans planos. Avec une clé, celle-ci doit être active et le nom d’hôte d’Origin appartenir aux domaines du compte, sous-domaines compris. Les adresses IP ne sont pas acceptées comme origine. 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 toute origine dotée d’un nom de domaine ou de développement, les méthodes GET/POST et les en-têtes Content-Type/X-Formulix-Chave. Avec une clé, l’appel effectif vérifie encore les domaines 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.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>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.com.br 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. Un Origin valide (et une clé valide, si elle est envoyée) est exigé 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é (sans clé : par IP), 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. Sans clé, le plafond s’applique par IP.
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é invalide ou révoquée.
402 — Monthly insertion limit reached.: Plafond du forfait ou du développement ; planos fournit le lien d’inscription ou du tableau de bord.
403 — Origin not allowed for this key. ou Origin not allowed.: 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.