Documentacion API

Referencia tecnica para desarrolladores e integraciones con Calcula.club.

Esquema de configuracion

Cada calculadora se define con un objeto JSON CalculatorConfig:

interface CalculatorConfig {
  name: string;             // Nombre de la calculadora
  description: string;      // Descripcion breve
  icon: string;             // Emoji del icono
  fields: Field[];          // Campos de entrada
  formula: string;          // Formula principal
  resultLabel: string;      // Etiqueta del resultado
  resultFormat: FormatType; // "number" | "currency" | "percent" | "integer"
  category?: string;
  theme?: { primary: string };
  extraResults?: ExtraResult[];
  resultThresholds?: ResultThreshold[];
  breakdown?: BreakdownItem[];
  pieConfig?: { segments: PieSegment[] };
}

Field:

interface Field {
  id: string;        // Identificador unico (usado en formulas)
  label: string;     // Texto visible
  type: "number" | "slider" | "select" | "checkbox" | "section" | "radio" | "date" | "range" | "divider";
  default: number;
  min?: number;
  max?: number;
  step?: number;
  options?: { label: string; value: number }[];
  suffix?: string;
  helpText?: string;
  content?: string;  // Para section/divider
  imageUrl?: string; // Para divider
  showIf?: string;   // Formula de visibilidad condicional
}

Motor de formulas

El motor de formulas soporta:

Operadores (por precedencia):

^ — Potencia

*, /, % — Multiplicacion, division, modulo

+, - — Suma, resta

>, <, >=, <=, ==, != — Comparaciones (devuelven 1 o 0)

Operador unario: - (negacion)

Funciones:

Funcion	Firma	Descripcion
`pow`	`pow(base, exp)`	Potencia
`sqrt`	`sqrt(x)`	Raiz cuadrada
`abs`	`abs(x)`	Valor absoluto
`round`	`round(x)`	Redondeo al entero mas cercano
`floor`	`floor(x)`	Redondeo hacia abajo
`ceil`	`ceil(x)`	Redondeo hacia arriba
`min`	`min(a, b, ...)`	Minimo
`max`	`max(a, b, ...)`	Maximo
`avg`	`avg(a, b, ...)`	Media aritmetica
`sum`	`sum(a, b, ...)`	Suma
`factorial`	`factorial(n)`	Factorial (n!)
`sin`	`sin(x)`	Seno (radianes)
`cos`	`cos(x)`	Coseno
`tan`	`tan(x)`	Tangente
`asin`	`asin(x)`	Arcoseno
`acos`	`acos(x)`	Arcocoseno
`atan`	`atan(x)`	Arcotangente
`ln`	`ln(x)`	Logaritmo natural
`log`	`log(x)`	Logaritmo natural
`log10`	`log10(x)`	Logaritmo base 10
`exp`	`exp(x)`	e^x
`if`	`if(cond, then, else)`	Condicional (evaluacion perezosa)
`lookup`	`lookup(val, t1, r1, ..., default)`	Busqueda por umbrales

Constantes: pi (3.14159...), e (2.71828...)

Variables intermedias: Usa nombre = expresion; para definir variables locales. La ultima expresion es el resultado.

Formato de URL

Las calculadoras se codifican en la URL:

https://calcula.club/c/{config_codificada}
https://calcula.club/es/c/{config_codificada}

La configuracion se serializa como JSON, se comprime con deflate y se codifica en base64url. Para embeber, usa la ruta /embed/{config}.

Parametros de consulta para valores iniciales:

/embed/{config}?campo1=50&campo2=100

Cada parametro corresponde al id de un campo. Solo se aceptan valores numericos.

Embeber

Para embeber una calculadora, usa un iframe:

<iframe
  src="https://calcula.club/embed/{config}"
  width="100%"
  height="600"
  frameborder="0"
  style="border: none; border-radius: 12px;"
></iframe>

O descarga el HTML autocontenido desde el Builder para alojar tu propia copia.

API de mensajes: El iframe comunica cambios de altura al padre via postMessage para ajuste automatico de tamano.