STRUCTAConecta Structa con tus otros sistemas
Consulta los registros del negocio con una API de lectura, recibe eventos firmados sin consultar continuamente y permite acciones concretas en cuentas conectadas. Aquí encontrarás lo que existe hoy, cómo funciona y sus límites.
El propietario activa el módulo Open API. Sus claves, endpoints de webhooks y cuentas conectadas se gestionan desde ese módulo.
Ocho recursos, solo GET
La versión actual usa el prefijo /api/v1/. Solo implementa GET: POST, PUT, PATCH y DELETE devuelven 405. Esta API no permite escribir en Structa. Devuelve los registros del negocio al que pertenece la clave emitida por su propietario.
| Endpoint | Parámetros | Módulo necesario |
|---|---|---|
GET /api/v1/bookings Envía ambas fechas o ninguna. Con intervalo, orden ascendente; sin él, las más recientes primero. | ?from=YYYY-MM-DD&to=YYYY-MM-DD | Reservas |
GET /api/v1/clients Busca por nombre, correo y teléfono sin distinguir mayúsculas. Ordena por nombre. | ?search= | Clientes |
GET /api/v1/services El catálogo de servicios disponibles para reservar. | — | Reservas |
GET /api/v1/menu Platos y bebidas con sus precios. | — | Menú |
GET /api/v1/tables Las mesas del local y su estado actual. | — | Mesas |
GET /api/v1/orders Cada pedido incluye sus artículos en el campo items. | ?day=YYYY-MM-DD | Pedidos |
GET /api/v1/payments Incluye los pagos anulados, identificados como tales. Exclúyelos al calcular totales. | ?day=YYYY-MM-DD | Pagos y TPV |
GET /api/v1/time-entries Un turno abierto tiene clock_out igual a null. | ?from=YYYY-MM-DD&to=YYYY-MM-DD | Fichaje |
curl -H "Authorization: Bearer sk_live_..." \
"https://app.structainc.com/api/v1/bookings?from=2026-09-01&to=2026-09-30"Formato de las respuestas
- Las respuestas correctas usan { data: [...], page: { limit, offset, total } }. El valor predeterminado de limit es 50 y el máximo 200. offset indica el desplazamiento por filas; no hay cursor.
- ?day, ?from y ?to son fechas locales del negocio. Se resuelven según su zona horaria y la hora de cierre del día: con cierre a las 04:00, una venta a la 01:30 corresponde al día anterior.
- Los campos *_cents contienen centavos enteros. Las marcas de tiempo usan ISO 8601 en UTC.
- Los errores usan { error, code }. Los códigos son BAD_REQUEST, INVALID_KEY, MODULE_DISABLED, NOT_FOUND, RATE_LIMITED, SERVER_ERROR y UNAVAILABLE. Basa la lógica del cliente en code.
- El límite es de 120 solicitudes por minuto y clave, además de un límite por dirección IP. Al superarlo se devuelve 429 con Retry-After en segundos.
Una clave por negocio, visible una sola vez
Es un token Bearer emitido por el propietario y limitado a su negocio. No es una cuenta de usuario ni una sesión de acceso.
Crear una clave
El propietario abre Open API y crea una clave con una etiqueta. Empieza por sk_live_ y contiene 64 caracteres hexadecimales. Se muestra una sola vez y Structa conserva únicamente su hash SHA-256. El personal con acceso al módulo puede ver la etiqueta, los primeros doce caracteres, la fecha de creación y el último uso, pero no el secreto. La emisión está restringida al propietario también en la base de datos.
Qué datos permite leer
Solo los de un negocio y sus módulos activos. Cada solicitud comprueba primero Open API y después el módulo del recurso. Si cualquiera está desactivado, devuelve 403 MODULE_DISABLED sin especificar cuál. No hay un parámetro para ampliar el acceso a otro negocio.
Revocar una clave
La lista ofrece una confirmación en dos pasos. La revocación es permanente: la siguiente solicitud devuelve 401 y, para recuperar acceso, debes crear otra clave. La fecha de último uso ayuda a identificar las que siguen activas.
Desactivar Open API detiene todas las claves del negocio y la salida de los eventos que todavía están en cola.
Ocho tipos de eventos
Configura una URL y los temas que quieres recibir. El evento se registra cuando ocurre y la cola se procesa cada minuto. Solo el propietario puede añadir, editar o eliminar un endpoint.
| Tema | Cuándo se emite | Contenido del evento |
|---|---|---|
| booking.created | Se crea una reserva | Identificador, hora de inicio, servicio y estado |
| booking.canceled | La reserva pasa a estado canceled | Identificador, hora de inicio y estado |
| client.created | Se añade un cliente | Identificador y nombre; no incluye teléfono ni correo |
| order.closed | Un pedido pasa a estado closed | Identificador y fecha de cierre |
| payment.recorded | Se registra un pago | Identificador, importe y propina en centavos, método y pedido asociado |
| payment.refunded | Aumenta el total reembolsado de un pago | Identificador, importe y TOTAL reembolsado; no la diferencia del último reembolso parcial |
| request.created | Se abre una solicitud | Identificador, prioridad y estado |
| delivery.shipped | Una entrega pasa a estado shipped | Identificador, seguimiento, código del transportista e identificador del pedido en el proveedor de envíos |
{
"id": "…", // identificador del evento
"topic": "booking.created",
"subject_id": "…", // reserva relacionada
"occurred_at": "2026-09-12T09:12:00.000Z",
"delivery_id": "…", // estable entre reintentos; úsalo para deduplicar
"attempt": 1,
"data": { "id": "…", "starts_at": "…", "service": "…", "status": "confirmed" }
}Los eventos incluyen identificadores y algunos campos, no registros completos. Para obtener más datos, consulta la API con tu clave. Cada tema necesita su módulo activo tanto al crear el evento como al entregarlo; desactivar el módulo detiene también los reintentos pendientes.
Cada entrega lleva una firma
Comprueba la firma antes de procesar el cuerpo. Las tres cabeceras que acompañan la entrega permiten validarla e identificarla.
- Structa-Signature: t=<segundos unix>,v1=<hmac-sha256 hexadecimal>. Structa-Topic y Structa-Delivery repiten el tema y el identificador de entrega para enrutar sin analizar el cuerpo.
- v1 es el HMAC-SHA256 de `${t}.${rawBody}` con el secreto del endpoint. Usa los bytes originales, antes de JSON.parse. Comprueba que la marca de tiempo esté dentro de unos pocos minutos, tanto hacia atrás como hacia delante, y compara en tiempo constante.
- El secreto empieza por whsec_ y contiene 64 caracteres hexadecimales. Se muestra una sola vez al crear o rotar el endpoint. Structa guarda una copia cifrada y no puede volver a mostrártelo; si lo pierdes, debes rotarlo.
- El botón de prueba envía un POST real y muestra el código de respuesta. Lo firma con una clave desechable, no con tu secreto, y lo indica en el cuerpo. Comprueba la conectividad y el formato, pero no valida tu verificación de firmas.
- Solo se acepta HTTPS y no se siguen redirecciones. Se rechazan direcciones literales de loopback, enlace local y rangos privados. La comprobación no resuelve DNS: un nombre que apunte a una dirección privada puede pasar. Solo el propietario puede configurar o probar el endpoint; la respuesta de error muestra una categoría general.
// Structa-Signature: t=<segundos unix>,v1=<hmac-sha256 hexadecimal>
const { t, v1 = "" } = Object.fromEntries(
header.split(",").map((p) => {
const i = p.indexOf("=");
return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
}),
);
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.${raw}`) // cuerpo ORIGINAL, antes de JSON.parse
.digest("hex");
const ok =
/^\d{1,10}$/.test(t ?? "") && // solo dígitos, para evitar una cadena firmada ambigua
Math.abs(Date.now() / 1000 - Number(t)) < 300 &&
expected.length === v1.length && // timingSafeEqual lanza una excepción si las longitudes difieren
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));Consulta el resultado de cada intento
La cola se procesa cada minuto. El endpoint muestra resultados de entregas reales; si todavía no se ha enviado nada, lo indica.
- La entrega es al menos una vez, no exactamente una. Un 2xx cuenta como éxito; otras respuestas se reintentan. Deduplica con delivery_id, estable para cada combinación de evento y endpoint.
- Hay once intentos en total. El intervalo empieza en un minuto, se duplica y llega hasta seis horas: aproximadamente catorce horas y media entre el primer intento y el último.
- Un 4xx también se reintenta, porque puede deberse a una incidencia temporal, como un despliegue.
- Cada intento registra código de respuesta, error y duración. El endpoint muestra el último resultado y el número de fallos consecutivos.
- Veinte fallos consecutivos desactivan el endpoint y guardan el motivo. Reactivarlo manualmente reinicia el contador.
- Desactivar un endpoint pausa su cola. Al reactivarlo se reanudan las entregas pendientes; las que llevan más de veinticuatro horas sin entregarse se dan por fallidas, con el motivo registrado.
- Cada entrega se reserva antes del envío para evitar que dos ejecuciones simultáneas la procesen a la vez. Una reserva abandonada por una ejecución interrumpida termina caducando.
- El POST tiene un tiempo límite de diez segundos. Superarlo cuenta como un intento fallido.
Tu cuenta y un permiso que puedes retirar
Busca una aplicación en el catálogo del proveedor, inicia sesión y autoriza la conexión. El permiso se asocia al negocio. No se conecta ninguna cuenta automáticamente.
Conectar o desconectar
Solo puede hacerlo el propietario, comprobado en el servidor incluso para consultar la lista. Para conectar, el negocio debe estar abierto y Open API activo. Para desconectar no hace falta ninguno de esos requisitos: cerrar el negocio o desactivar el módulo no impide retirar el acceso.
Dónde están las credenciales
Pipedream conserva el inicio de sesión y los tokens actualizados; figura como subencargado en el acuerdo de tratamiento de datos. Structa no recibe esas credenciales. La lista se consulta al proveedor cuando hace falta. Desconectar elimina allí el acceso guardado; eliminar el negocio elimina sus conexiones. También puedes retirar el permiso desde la aplicación de origen.
La conexión pertenece al negocio
Sigue asociada a la empresa aunque se marche la persona que la creó. Un empleado que trabaje en dos negocios no puede trasladar las conexiones de uno al otro.
Lectura del buzón del recepcionista
Puedes asignar un buzón Gmail al Recepcionista IA para leerlo sin reenviar los mensajes. Una búsqueda del proveedor limita lo que se procesa; por defecto incluye la bandeja de entrada y excluye Promociones y Social. No se admite una búsqueda vacía. Los mensajes incorporados se convierten en hilos visibles para quienes tengan acceso al módulo. Esta configuración necesita Recepcionista IA, no Open API.
La disponibilidad de aplicaciones depende del catálogo del proveedor. Comprueba la acción concreta que necesitas; conectar una cuenta no significa que todas sus funciones estén integradas.
Una propuesta y una confirmación humana
El asistente puede ejecutar acciones disponibles en el catálogo del proveedor, como añadir una fila, publicar un mensaje o crear una factura. Revisa la propuesta antes de confirmarla: corregir un cambio puede requerir entrar en la otra aplicación.
- Primero consulta los nombres y campos de entrada de la acción en el catálogo. La propuesta debe ajustarse a esos datos; revisa los valores antes de autorizarla.
- Cada tarjeta propone una sola acción e indica qué se hará y en qué aplicación. La ejecución requiere confirmación.
- El servidor firma la propuesta para ese negocio y esos argumentos exactos. Cambiar un campo invalida la firma. La propuesta caduca a los quince minutos.
- No se ejecutan lotes ni reintentos automáticos. Repetir una acción puede duplicar su efecto, por ejemplo, crear dos filas en vez de una.
- Cada ejecución registra aplicación, acción, resumen y parámetros en la auditoría del negocio antes de comunicar el resultado, tanto si tuvo éxito como si falló.
- Si el proveedor rechaza la operación, se muestra su error en lugar de presentarla como completada.
- Solo pueden usarla el propietario o un responsable, con Asistente IA y Open API activos. No se ofrece a empleados sin permisos de gestión.
- Cada ejecución consume 40 créditos aunque el proveedor la rechace, porque la llamada se realiza igualmente.
Antes de diseñar tu integración
Ten en cuenta estas condiciones de la API, los webhooks y las acciones conectadas.
- No hay API de escritura. En v1, POST, PUT, PATCH y DELETE devuelven 405. Los cambios en Structa se hacen desde el producto o mediante acciones del asistente con confirmación.
- Cada clave pertenece a un negocio. No hay un programa de socios, instalación de aplicaciones de terceros ni OAuth para terceros. Está pensada para integraciones con los datos del negocio que emite la clave.
- La paginación usa limit y offset, con un máximo de 200 filas. No hay cursor ni flujo continuo de registros.
- Los eventos incluyen identificadores y algunos valores, no registros completos. Usa la API de lectura para consultar más detalles.
- Pueden llegar entregas repetidas. Deduplica con delivery_id antes de ejecutar una operación que no deba repetirse.
- No hay entorno de pruebas ni clave de prueba. El botón de prueba realiza un POST real con un secreto desechable.
- No hay SDK ni cliente generado. La interfaz usa HTTP y JSON; el ejemplo muestra cómo verificar la firma con una biblioteca criptográfica.
- La comprobación de direcciones privadas analiza la URL literal y no resuelve DNS.
- El propietario debe conectar cada cuenta, y una persona debe confirmar cada acción propuesta.
Requisitos para empezar
- Open API activo para usar claves, endpoints, conexiones y solicitudes /api/v1/.
- El propietario para crear claves y endpoints. Ese permiso no se delega mediante un rol.
- El módulo de cada recurso también activo: Reservas para reservas y servicios, Pedidos para pedidos, Pagos para pagos, según la tabla.
- Una URL HTTPS que responda en menos de diez segundos para recibir webhooks.
- Almacenamiento seguro en el servidor para la clave y el secreto de firma. Nunca los incluyas en código del navegador ni en un repositorio.
- El propietario debe autorizar la cuenta conectada desde el catálogo.
- Para el buzón, Recepcionista IA activo y una búsqueda que limite los mensajes que pueden leerse.
Disponible hoy
- Ocho endpoints de lectura bajo /api/v1/; los otros métodos devuelven 405.
- Claves visibles una sola vez, limitadas a un negocio y con revocación permanente.
- Ocho temas de webhooks con firma HMAC-SHA256 y secreto por endpoint.
- Registro del código de respuesta, error y duración de cada intento.
- Hasta once intentos en unas catorce horas y media; veinte fallos consecutivos desactivan el endpoint con el motivo registrado.
- Desactivar un endpoint pausa la cola sin descartar las entregas pendientes que todavía no hayan caducado.
- Conexiones autorizadas por el propietario, sin entregar sus credenciales a Structa.
- Acciones individuales en cuentas conectadas, confirmadas por un responsable y registradas en la auditoría.
- Exportación de tus datos y eliminación permanente a solicitud.
Lo que necesita saber tu equipo técnico
¿Hay API de escritura?
No. v1 es de solo lectura y los métodos distintos de GET devuelven 405. Los cambios se realizan desde Structa o mediante el asistente, detrás de una tarjeta de confirmación.
¿Puedo crear una aplicación que otros negocios instalen?
No existe un programa de socios, directorio de aplicaciones ni OAuth para terceros. Puedes crear una integración para un negocio concreto con una clave emitida por su propietario, por ejemplo como equipo interno o agencia.
¿Tenéis un catálogo propio de integraciones?
La API y los ocho temas de webhooks sirven como base general. Para otras acciones se usa el catálogo de un proveedor: el propietario conecta una cuenta y una persona confirma la acción. Comprueba la función que necesitas; no todas las aplicaciones tienen una integración completa.
¿Cómo verifico que una entrega procede de Structa?
Calcula HMAC-SHA256 de `${t}.${rawBody}` con el secreto del endpoint. t viene de Structa-Signature; rawBody son los bytes antes de analizarlos. Comprueba la marca de tiempo, compara en tiempo constante y rechaza cualquier entrega que no pase la validación. El ejemplo está más arriba.
¿Qué ocurre si mi endpoint deja de responder durante un día?
Se realizan hasta once intentos durante unas catorce horas y media. Después se registra el fallo. Las entregas pendientes de más de veinticuatro horas caducan. Veinte fallos consecutivos desactivan el endpoint; reactivarlo reinicia el contador y reanuda lo que siga pendiente y vigente.
¿Qué pasa si desactivo un módulo?
Su recurso devuelve 403 MODULE_DISABLED y sus eventos dejan de emitirse y entregarse. Desactivar Open API detiene todas las claves y entregas pendientes del negocio.
¿Qué debo activar?
En Hub, abre Inicio → Espacio de trabajo → Gestionar módulos y activa Open API junto con los módulos de los recursos necesarios. Todos están incluidos en Free. Las acciones de IA en cuentas conectadas consumen créditos del saldo compartido del negocio.
¿Dónde encuentro la referencia?
Esta página resume la interfaz y sus límites. Dentro del módulo Open API también encontrarás los endpoints, los temas de eventos y un ejemplo curl junto a tus claves.
¿Quieres conocer el producto que hay detrás de la API? Explora todas las herramientas de Structa