API de datos

Empezar

Introducción

Tu sistema en Blank101 tiene tres puertas, y cada una hace una sola cosa:

Todas las rutas cuelgan de esta URL base:

https://blank101.app/api/v1

Casos típicos: mostrar tu catálogo o tus propiedades disponibles en tu página web, recibir pedidos o prospectos desde otra herramienta, sincronizar con Zapier, o alimentar un reporte en otro sistema.

Empezar

Inicio rápido

curl "https://blank101.app/api/v1/views/catalogo_web/records?limit=5" \
  -H "Authorization: Bearer $BLANK101_KEY"

Empezar

Autenticación

Cada petición lleva la llave en el encabezado Authorization. Las llaves del API empiezan con b101d_; las del agente (b101_) no sirven aquí, ni al revés.

Authorization: Bearer b101d_tu_llave

• Guárdala en el servidor (variables de entorno, el almacén de secretos de Zapier). Nunca en un repositorio.
• Una llave de solo lectura sobre una vista pública de tu catálogo puede vivir en tu web; una que escribe, nunca en código que ve el navegador.
• Si se filtra, revócala en Ajustes → API: deja de funcionar al instante. Crea otra y reemplázala.
• Una llave por integración: así sabes quién hizo qué (el historial de cada registro dice “API · nombre de la llave”).

Empezar

Alcance por vista

Una llave no abre tablas: abre vistas. La vista decide exactamente qué sale. Si tu vista “Catálogo web” muestra nombre, precio y foto y solo los productos activos, eso es lo único que la llave alcanza, aunque la tabla tenga costo, proveedor y notas internas.

• Solo se leen y escriben los campos visibles de la vista. Las fórmulas y los archivos son de solo lectura.
• Los filtros de la vista siempre aplican. Un registro que no los cumple no existe para la llave (404), también al actualizar.
• Si tu agente cambia la vista (agrega un campo, cambia un filtro), el API lo refleja al publicar. Si la vista se quita, la llave pierde ese acceso.
• Borrar no existe en v1. Un sistema externo con un error no puede vaciar tu información. Desde la app, los registros van a la papelera.

Endpoints

Endpoints

Las vistas se identifican por su clave (por ejemplo catalogo_web), que aparece en Ajustes → API junto a su nombre. Los registros, por su id.

curl "https://blank101.app/api/v1/views" \
  -H "Authorization: Bearer $BLANK101_KEY"

{
  "space": "Abarrotes Don Luis",
  "key": "Página web",
  "views": [
    {
      "key": "catalogo_web",
      "name": "Catálogo web",
      "type": "cards",
      "table": "productos",
      "access": "read",
      "fields": [ … ]
    }
  ]
}

curl "https://blank101.app/api/v1/views/catalogo_web" \
  -H "Authorization: Bearer $BLANK101_KEY"

{
  "key": "catalogo_web",
  "name": "Catálogo web",
  "type": "cards",
  "table": "productos",
  "access": "read",
  "fields": [
    { "key": "nombre", "name": "Nombre", "type": "text",
      "required": true, "writable": true },
    { "key": "precio", "name": "Precio", "type": "money",
      "required": true, "writable": true, "currency": "MXN" },
    { "key": "categoria", "name": "Categoría", "type": "select",
      "required": false, "writable": true, "multiple": false,
      "options": [ { "value": "abarrotes", "label": "Abarrotes" } ] },
    { "key": "foto", "name": "Foto", "type": "file",
      "required": false, "writable": false }
  ]
}

curl "https://blank101.app/api/v1/views/catalogo_web/records?categoria=abarrotes&precio[lte]=100&sort=-precio&limit=20" \
  -H "Authorization: Bearer $BLANK101_KEY"

{
  "data": [
    {
      "id": "6f1c2a0e-8d4b-4c1e-9a77-2f0b5e1d9c33",
      "created_at": "2026-10-02T17:21:09.412Z",
      "updated_at": "2026-10-04T15:02:51.120Z",
      "fields": {
        "nombre": "Café de olla 500 g",
        "precio": 95,
        "categoria": "abarrotes",
        "foto": [ { "name": "cafe.jpg", "type": "image/jpeg", "size": 184220 } ]
      }
    }
  ],
  "next_cursor": "bzoyMA"
}

curl "https://blank101.app/api/v1/views/catalogo_web/records/6f1c2a0e-8d4b-4c1e-9a77-2f0b5e1d9c33" \
  -H "Authorization: Bearer $BLANK101_KEY"

{
  "id": "6f1c2a0e-8d4b-4c1e-9a77-2f0b5e1d9c33",
  "created_at": "2026-10-02T17:21:09.412Z",
  "updated_at": "2026-10-04T15:02:51.120Z",
  "fields": { "nombre": "Café de olla 500 g", "precio": 95, … }
}

curl -X POST "https://blank101.app/api/v1/views/pedidos_web/records" \
  -H "Authorization: Bearer $BLANK101_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"cliente":"María López","telefono":"+52 686 123 4567","total":450,"entrega":"2026-10-08"}}'

HTTP/1.1 201 Created

{
  "id": "a3d0c9b2-41f7-4b6e-8a2c-7f5e3b1d0e98",
  "created_at": "2026-10-05T18:40:12.004Z",
  "updated_at": "2026-10-05T18:40:12.004Z",
  "fields": {
    "cliente": "María López",
    "telefono": "+52 686 123 4567",
    "total": 450,
    "entrega": "2026-10-08",
    "estado": "nuevo"
  }
}

curl -X PATCH "https://blank101.app/api/v1/views/pedidos_web/records/a3d0c9b2-41f7-4b6e-8a2c-7f5e3b1d0e98" \
  -H "Authorization: Bearer $BLANK101_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"estado":"entregado"}}'

{
  "id": "a3d0c9b2-41f7-4b6e-8a2c-7f5e3b1d0e98",
  "updated_at": "2026-10-06T10:12:44.871Z",
  "fields": { …, "estado": "entregado" }
}

Referencia

Filtros, orden y páginas

Tus filtros se suman a los de la vista, nunca los reemplazan, y solo aplican a campos visibles. Varios filtros = todos deben cumplirse.

Fechas relativas. En campos de fecha puedes usar today, tomorrow, yesterday, this_week, last_7_days, next_7_days, this_month, last_month, next_month, this_year, past, future o un mes 2026-10. Se calculan en la zona horaria de tu espacio: entrega=today son las entregas de hoy.

Páginas. Pide hasta 100 registros por vez y sigue el next_cursor hasta que sea null. El cursor es opaco: no lo construyas a mano.

let cursor = null;
const todos = [];
do {
  const url = new URL("https://blank101.app/api/v1/views/catalogo_web/records");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.BLANK101_KEY}` } });
  const page = await res.json();
  todos.push(...page.data);
  cursor = page.next_cursor;
} while (cursor);

Referencia

Tipos de campo

Cómo viaja cada tipo en JSON, al leer y al escribir.

Referencia

Errores

Los errores responden con un código HTTP y un cuerpo que explica qué pasó en español llano.

{
  "error": {
    "code": "invalid_fields",
    "message": "Hay campos con errores.",
    "fields": {
      "telefono": "Escribe un teléfono válido.",
      "estado": "Elige una opción válida."
    }
  }
}

Referencia

Límites

Referencia

Seguridad

• La garantía vive en la base de datos. Qué vista, qué campos y qué registros alcanza una llave lo decide la base, no el código de la página: aunque hubiera un error en la capa web, la base no entrega de más.
• Las llaves se guardan cifradas (solo su huella sha256). Ni nosotros podemos mostrártela otra vez.
• Nada sale sin que lo decidas. Solo el dueño crea llaves y elige vistas. Tu agente de IA nunca ve ni crea llaves.
• Rastro completo. Cada registro creado o cambiado por el API queda en su historial con el nombre de la llave.
• Sin borrar y sin estructura. El peor caso de una llave filtrada con escritura es que alguien cree o edite registros de esas vistas; lo ves en el historial y la revocas en un clic.

Referencia

Zapier, Make y n8n

Hoy puedes conectar cualquier herramienta que haga peticiones HTTP: el módulo HTTP de Make, el nodo HTTP Request de n8n o Webhooks by Zapier. Usa la URL base, el encabezado Authorization y los ejemplos de esta página.

Referencia

Cambios