API contract

Preview, insertion confirmation और periodic table के routes।

Authentication और Origin

X-Formulix-Chave वैकल्पिक है। Key के बिना Origin का hostname site की पहचान करता है: अगर कोई registered domain उसे कवर करता है तो उस खाते का plan लागू होता है; नहीं तो Free plan लागू होता है, जो केवल उसी hostname से गिना जाता है, और 402 response के planos में sign-up link आता है। Key के साथ, key active हो और Origin का hostname खाते के domains या subdomains में हो। IP addresses origin के रूप में स्वीकार नहीं होते। Browser Origin भेजता है; JavaScript से इसे manually set न करें। Valid origin के बिना request अस्वीकार होती है।

OPTIONS preflight domain name वाला कोई भी origin या development origins, GET/POST और Content-Type/X-Formulix-Chave headers स्वीकार करता है। Key के साथ, वास्तविक call फिर key के मालिक खाते के domains जाँचती है। Responses में Vary: Origin और Cache-Control: no-store हैं। Allowed origin वापस भेजा जाता है, wildcard नहीं। Denied origin browser में केवल CORS error के रूप में दिख सकता है।

Key public है, admin key नहीं; browser के बाहर Origin जाली किया जा सकता है। Revocation और domain changes default में लगभग 5 seconds में reload होते हैं।

POST /v1/calc — preview

JSON body: { op, dados, idioma, notacao }। op operation चुनता है, dados उसके parameters देता है। Default language en है; हिन्दी के लिए hi भेजें। notacao optional है, जैसे { "decimal": "." }। Operation के अनुसार JSON में HTML, LaTeX, SVG या सहायक data मिलता है। सफल call 1 preview और 0 insertions गिनती है।

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>कोई समीकरण नहीं</p>' },
    idioma: 'hi'
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.erro);
// इस उदाहरण में: { eqs: [] }

मान्य operations: 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। ये code identifiers हैं; इनका अनुवाद न करें। dados fields operation के अनुसार बदलते हैं; adapter से request बनाएँ। Parameters का एक ही schema नहीं है।

POST /v1/inserir — अंतिम output

Body में tipo, नीचे के specific fields और optional idioma/notacao हैं। Response JSON का common envelope नहीं है।

// सूत्र का body; preview वाले headers ही भेजें।
{
  "tipo": "formula",
  "latex": "x^2",
  "bloco": false,
  "idioma": "hi"
}
// 200 response: { "html": "<math ...>...</math>" }

Client SVG को PNG में बदलकर platform से upload करता है। Calculation API images store नहीं करती। हर accepted confirmation गिनी जाती है, re-edit भी; ID से idempotency नहीं है। पहली confirmation स्वीकार हुई या नहीं पता न हो तो उसे स्वतः दोहराने से बचें।

GET /v1/tabela?idioma=hi

Periodic table के लिए elements का array { z, s, nome, pos, cor } लौटाता है। Public data होने पर भी valid Origin चाहिए (और key भेजी जाए तो valid key भी)। Preview/insertion नहीं गिनता; प्रति मिनट limit लागू है। Default language English है।

Limits

• Body अधिकतम 15 MiB। बड़े request में 413 response के बाद connection बंद हो सकता है।
• हर process में प्रति key (key के बिना: प्रति IP) 1,200 requests/मिनट, previews और table सहित। कई processes हों तो यह global limit नहीं है।
• Free 500 / Starter 5,000 / School 25,000 insertions; Network में संख्यात्मक ceiling नहीं। Free में account और domain दोनों के ceilings हैं; paid usage खाते में जुड़ता है।
• Development: default 300 insertions/माह/खाता, FORMULIX_DEV_LIMITE से configurable। localhost, .localhost subdomains, 127.0.0.1, [::1] और .test शामिल हैं। Key के बिना limit प्रति IP लागू होती है।
• Processes में usage default में हर 5 seconds sync होता है; हर request पर global transactional counter नहीं है। महीना UTC में है।

Errors

Application errors JSON { "erro": "message" } देते हैं। Calculation validation के कुछ messages localized हो सकते हैं।

/saude बिना authentication { "ok": true } देता है; इससे किसी key का access प्रमाणित नहीं होता।