Documentación de la API

Empezar en 5 minutos

1. Cree un token en Ajustes › Seguridad › Tokens de API. Dele un nombre y elija sus permisos (por ejemplo rows:read y rows:write). El token solo se muestra una vez: cópielo.

2. Compruebe que funciona.

export RANGEE_TOKEN="pat…"

curl https://api.rangee.io/v1/me \
  -H "Authorization: Bearer $RANGEE_TOKEN"

La respuesta da su identidad, el nombre del token, sus permisos, su alcance y la cuota del mes.

3. Encuentre sus tablas. La respuesta de GET /v1/bases/app… lista las tablas de la base, con sus identificadores.

curl https://api.rangee.io/v1/bases \
  -H "Authorization: Bearer $RANGEE_TOKEN"

curl https://api.rangee.io/v1/bases/app… \
  -H "Authorization: Bearer $RANGEE_TOKEN"

4. Lea sus filas, con claves por nombre de campo para empezar.

curl "https://api.rangee.io/v1/tables/tbl…/rows?limit=10&fieldKey=name" \
  -H "Authorization: Bearer $RANGEE_TOKEN"

5. Cree una fila.

curl https://api.rangee.io/v1/tables/tbl…/rows \
  -H "Authorization: Bearer $RANGEE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2e7a-creation-atelier-martin" \
  -d '{
    "rows": [
      { "values": { "Nom": "Atelier Martin", "Statut": "Signé", "Montant": 1250 } }
    ]
  }'

En JavaScript:

const res = await fetch("https://api.rangee.io/v1/tables/tbl…/rows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RANGEE_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    rows: [{ values: { Nom: "Atelier Martin", Statut: "Signé", Montant: 1250 } }],
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code} : ${body.error.message}`);

En Python:

import os, uuid, requests

res = requests.post(
    "https://api.rangee.io/v1/tables/tbl…/rows",
    headers={
        "Authorization": f"Bearer {os.environ['RANGEE_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"rows": [{"values": {"Nom": "Atelier Martin", "Statut": "Signé", "Montant": 1250}}]},
)
res.raise_for_status()

Acceso y tokens

Cada llamada lleva un token personal en la cabecera:

Authorization: Bearer pat….…

Un token tiene un nombre, unos permisos, un alcance y, si lo desea, una fecha de caducidad.

Hereda el rol de su creador en cada base. El token de una persona con acceso de solo lectura nunca escribe, ni siquiera con el permiso rows:write.

Se corta de inmediato si usted lo revoca, o si su creador es retirado del workspace o desactivado.

Permisos

Alcance

Un token cubre o bien todas las bases del workspace a las que su creador tiene acceso, o bien una lista de bases elegida. Un token nunca abarca dos workspaces.

Un recurso fuera del alcance del token responde 404, exactamente como un recurso que no existe.

Identidad

GET /v1/me

Devuelve la persona, el nombre del token, sus permisos, su alcance y la cuota de llamadas del mes.

Vocabulario e identificadores

Los identificadores son opacos. No los construya ni los analice: solo el identificador completo tiene sentido.

Convenciones

• Formato. JSON en UTF-8. Fechas y horas en ISO 8601 UTC (2026-11-03T09:30:00.000Z), fechas sin hora en YYYY-MM-DD.
• Recurso o lista. Un recurso único se devuelve tal cual. Una lista tiene la forma { "data": [...], "nextCursor": "…" | null }.
• Paginación. Por cursor opaco: limit (de 1 a 1.000, 100 por defecto) y cursor. Un cursor sigue siendo válido 24 horas. Cuando nextCursor vale null, ya lo ha leído todo.
• Lotes. Una escritura lleva de 1 a 100 filas. Un lote es atómico: pasa todo, o nada.
• Designación. Una tabla, un campo o una vista se designa por su identificador. Los nombres de campo solo se aceptan como claves de values, en escritura.
• Claves de lectura. Los valores tienen como clave el identificador del campo. Añada fieldKey=name a cualquier lectura de filas para recibirlos con el nombre como clave.
• Repetir sin riesgo. Toda petición POST, PATCH, PUT o DELETE acepta una cabecera Idempotency-Key (de 1 a 255 caracteres). La misma llamada repetida en las 24 horas devuelve la misma respuesta sin volver a escribir nada. La misma clave con un cuerpo distinto responde 409 IDEMPOTENCY_CONFLICT.
• Soporte. Cada respuesta lleva una cabecera Request-Id. Cítela al soporte: basta para encontrar la llamada.

Paginar

async function* allRows(tableId) {
  let cursor = null;
  do {
    const url = new URL(`https://api.rangee.io/v1/tables/${tableId}/rows`);
    url.searchParams.set("limit", "1000");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.RANGEE_TOKEN}` } });
    const page = await res.json();
    yield* page.data;
    cursor = page.nextCursor;
  } while (cursor);
}

Filas

{
  "id": "row01JC9…",
  "createdAt": "2026-10-12T08:14:03.000Z",
  "updatedAt": "2026-11-02T17:40:11.000Z",
  "values": {
    "fld01Nom…": "Atelier Martin",
    "fld01Statut…": { "id": "sel…", "name": "Signé" },
    "fld01Montant…": 1250
  }
}

Valores vacíos. Un valor vacío no aparece en values. Para vaciar un valor, escriba null.

Reglas de escritura

PATCH o PUT. PATCH solo toca los campos enviados. PUT reemplaza la fila: los campos ausentes del cuerpo se vacían.

Campos calculados. Rechazan la escritura (422 READ_ONLY_FIELD): fórmula, lookup, rollup, contador, número automático, fechas y autores de creación y de modificación, botón.

Conversión con "coerce": true. Añadida al cuerpo, la opción convierte los textos en números, fechas y casillas, y crea las opciones de selección desconocidas. Sin ella, un valor del tipo equivocado responde 422 INVALID_VALUE.

{ "coerce": true, "rows": [{ "values": { "fld01Montant…": "1 250,50", "fld01Signé…": "oui" } }] }

Upsert.

• matchOn lista de 1 a 3 campos, de tipo texto, correo electrónico, número, número automático, URL o teléfono.
• Cada fila enviada que coincide con exactamente una fila existente la modifica. Si no encuentra ninguna, se crea. Si encuentra varias, la llamada responde 409 UPSERT_AMBIGUOUS.
• La respuesta distingue las filas creadas (created) de las filas modificadas (updated).

curl https://api.rangee.io/v1/tables/tbl…/rows/upsert \
  -H "Authorization: Bearer $RANGEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "matchOn": ["fld01Email…"],
    "rows": [
      { "values": { "fld01Email…": "camille@atelier-martin.fr", "fld01Nom…": "Camille Durand" } }
    ]
  }'

Eliminación. Una fila eliminada va a la papelera de la base durante 30 días. Se restaura desde la aplicación.

Límite del plan. Una creación más allá del número de filas que permite su plan responde 422 ROW_LIMIT, con el número de filas restantes.

Buscar filas

POST /v1/tables/{tableId}/rows/query

El cuerpo retoma la forma de los filtros de las vistas de la aplicación:

filter, search, viewId y formula se combinan con «y».

{
  "viewId": "viw…",
  "filter": {
    "and": [
      { "field": "fld01Statut…", "operator": "isAnyOf", "value": ["En cours", "À valider"] },
      { "or": [
        { "field": "fld01Montant…", "operator": ">=", "value": 10000 },
        { "field": "fld01Prioritaire…", "operator": "is", "value": true }
      ] }
    ]
  },
  "sort": [{ "field": "fld01Echeance…", "direction": "asc" }],
  "limit": 50
}

Operadores: isEmpty, isNotEmpty, is, isNot, contains, doesNotContain, isAnyOf, isNoneOf, hasAnyOf, hasAllOf, linksTo, =, !=, <, <=, >, >=.

Cada tipo de campo solo acepta una parte de estos operadores. Un operador no aceptado responde 422 INVALID_FILTER indicando el campo en cuestión. Una fórmula demasiado costosa se rechaza antes de ejecutarse (422 QUERY_TOO_EXPENSIVE).

Valores por tipo de campo

Automatizaciones

Una automatización se dispara por la API de dos maneras.

Disparador «Llamada a la API».

• La automatización declara sus variables en el editor. Cada variable tiene un nombre (letras, cifras y _), una etiqueta, un tipo, si es obligatoria o no, un valor por defecto y una descripción.
• Tipos posibles: text, number, boolean, date, dateTime, email, rowId, rowIds, json.
• Los pasos leen las variables en trigger.inputs.<nombre>.
• Una variable de tipo rowId indica su tabla. El servidor comprueba que la fila existe y la carga en trigger.inputs.<nombre>.fields.

Disparador «Botón». Se dispara con un rowId, como un clic en la aplicación.

curl https://api.rangee.io/v1/automations/aut…/runs \
  -H "Authorization: Bearer $RANGEE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: relance-devis-2026-11-03" \
  -d '{
    "inputs": { "client": "row…", "montant": 1250, "relance": true },
    "wait": 10
  }'

Para un disparador «Botón», envíe { "rowId": "row…" } en lugar de inputs.

Reglas

Comprobación antes de ejecutar. Una variable obligatoria ausente, una variable desconocida o un valor del tipo equivocado responde 422 INVALID_INPUTS con la lista de errores. Esta llamada no cuenta como ejecución ni en la cuota del plan.

Espera con wait.

• Sin wait: respuesta 202, la ejecución se pone en cola (queued).
• Con wait (de 0 a 30 segundos): el servidor espera el final de la ejecución hasta ese plazo. Responde 200 con el resultado si ha terminado, y si no 202.

Resultado. El paso «Devolver valores» calcula pares de nombre y valor con los datos de la ejecución. Se devuelven en output. Sin este paso, output vale {}.

Estados de una ejecución:

Solo automatizaciones activas. Solo se ejecutan las automatizaciones publicadas y activas; las demás responden 422 AUTOMATION_DISABLED.

Trazabilidad. La ejecución lleva el nombre del token como origen. Aparece en el historial de ejecuciones y en el de las filas escritas.

Servicios sin cabeceras. El disparador «Webhook recibido» sigue disponible para los servicios que no saben enviar la cabecera Authorization. Su URL secreta acepta las mismas variables declaradas.

Webhooks

Rangee le envía los cambios de una base, sin que tenga que volver a leer los datos: cada entrega contiene las filas afectadas.

Eventos: row.created, row.updated, row.deleted, field.created, field.updated, field.deleted, table.created, table.updated, table.deleted.

Filtros. tableIds limita el webhook a ciertas tablas. fieldIds limita row.updated a los cambios de esos campos.

Cuerpo de una entrega:

{
  "id": "evt…",
  "type": "row.updated",
  "createdAt": "2026-11-03T09:30:00.000Z",
  "baseId": "app…",
  "tableId": "tbl…",
  "data": {
    "row": { "id": "row…", "createdAt": "…", "updatedAt": "…", "values": { "fld01Statut…": { "id": "sel…", "name": "Signé" } } },
    "previous": { "values": { "fld01Statut…": { "id": "sel…", "name": "Devis" } } }
  }
}

previous solo contiene los campos cambiados. Con includeValues: false, solo se envían los identificadores.

Verificar la firma

Cada entrega lleva la cabecera:

Rangee-Signature: t=<horodatage>,v1=<signature>

v1 es el HMAC-SHA256, en hexadecimal, de la cadena "<marca de tiempo>.<cuerpo bruto>", calculado con el secreto del webhook. El secreto solo se muestra una vez, al crear el webhook.

Rechace toda entrega cuya marca de tiempo tenga más de 5 minutos, para evitar que se reproduzca.

Node.js:

import crypto from "node:crypto";

export function verifyRangeeSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python:

import hmac, hashlib, time

def verify_rangee_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = parts.get("t", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Calcule la firma sobre el cuerpo bruto recibido, antes de analizar el JSON.

Entrega

• Al menos una vez, en el orden del registro para una misma fila. Elimine duplicados por el id del evento.
• Una respuesta 2xx en menos de 10 segundos cuenta como recibida. Responda rápido y procese después.
• Si no, Rangee reintenta durante 24 horas, con una espera creciente. Tras 24 horas de fallos, el webhook se desactiva y se avisa a los Admins del workspace.
• Un webhook no caduca: existe hasta que se elimina.
• Solo direcciones HTTPS, sin direcciones privadas ni locales.
• 20 webhooks por base como máximo.

Esquema

Descripción de un campo. Un campo se describe con { id, name, type, description, readOnly, options }. El contenido de options depende del tipo, y conserva la misma forma en lectura y en escritura.

Nombres de tipos. Retoman los de la aplicación, con «row» en lugar de «record»: multipleRowLinks, rowId. Los disparadores siguen la misma regla: rowCreated, rowUpdated, rowMatches, rowEntersView.

Cambiar de tipo. Un PATCH con un nuevo type cambia el tipo del campo y convierte los valores como lo hace la aplicación.

Eliminar un campo.

• Hace falta el rol Admin o User. El campo va a la papelera.
• Un campo usado por una fórmula, una automatización o una interfaz responde 409 FIELD_IN_USE con la lista de sus usos.
• Añada ?force=true para eliminarlo de todos modos.

Adjuntos y comentarios

Añadir un adjunto se hace en dos pasos:

1. Suba el archivo. Recibe { id, filename, size, type }.
2. Coloque { "id": "att…" } en un valor de adjuntos en la hora siguiente. Un archivo no usado en ese plazo se elimina.

curl https://api.rangee.io/v1/bases/app…/attachments \
  -H "Authorization: Bearer $RANGEE_TOKEN" \
  -F "file=@devis-atelier-martin.pdf"

Comentarios. Un comentario menciona a un miembro con @[usr…]. Solo su autor puede modificarlo o eliminarlo.

Errores

Todos los errores tienen la misma forma:

{
  "error": {
    "code": "INVALID_VALUE",
    "message": "« Montant » attend un nombre",
    "details": { "path": "rows[2].values.fld01Montant…" }
  }
}

Nada se ignora en silencio. Un valor no válido, un campo desconocido, un campo calculado escrito o una variable ausente responden 422, con la ruta exacta del error en details.path.

Qué hacer según el código:

Límites

Cada respuesta indica el ritmo que le queda en las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset.

Seguir su uso

Ajustes › Seguridad › Tokens de API lista sus tokens y su último uso. GET /v1/me da la cuota de llamadas del mes de la organización.

Ayuda

Escriba al soporte citando el Request-Id de la llamada en cuestión. Basta para encontrar la petición, su respuesta y su contexto.