← globalsuite.pro Global Suite · API contable

Alcance y seguridad de la API contable

En desarrollo Se habilita a pedido, hotel por hotel Solo lectura

Este documento se lee antes de pedir el acceso. Explica qué datos del hotel puede leer el sistema contable que se conecta, qué no puede leer nunca, qué medidas de seguridad aplicamos nosotros y cuáles le pedimos a quien se conecta.

Está escrito para el área técnica que hace la integración, con los nombres técnicos reales. Debajo de cada término hay una explicación en lenguaje llano, para que el dueño del hotel y el contador también lo entiendan.

Última actualización: octubre de 2026

1Qué es y en qué estado está

La API contable permite que el sistema contable del hotel o de su estudio contable lea los datos contables del hotel en Global Suite, sin cargarlos a mano. Es de solo lectura: no puede cargar, cambiar ni borrar nada.

En desarrollo Se habilita a pedido, hotel por hotel

Hoy está en desarrollo y en prueba en nuestro hotel de demostración. Cuando se habilite, cada hotel la pide y Global Suite revisa y aprueba cada solicitud.

API REST de solo lectura

Su sistema pide datos por internet a direcciones fijas y recibe la respuesta. Solo puede leer.

Endpoints: método y ruta (GET /asientos)

Cada dirección entrega un tipo de dato. Todas usan el método GET, que solo consulta.

JSON en UTF-8

El formato de texto estándar en que llegan los datos; lo lee cualquier sistema contable moderno.

OpenAPI 3.1

Una descripción completa de la API que leen las máquinas: el programador arma el conector sin adivinar campos.

Importes como texto decimal ("1234.50")

Así no se pierde ningún centavo en la conversión. Todo va en la moneda del hotel.

Fechas ISO 8601 (2026-10-27)

El formato internacional de fechas: año, mes y día, sin confusiones entre países.

Paginación con el encabezado Link (RFC 8288)

Las listas largas llegan por páginas, y cada respuesta dice dónde está la siguiente.

Días cerrados y días provisorios

Por defecto solo se entregan los días que el hotel ya cerró en el Back Office, con las cifras congeladas. Los días sin cerrar, solo si se piden, marcados como provisorios.

Cada número sale de la misma función que usan las pantallas del Back Office y su exportación. Si un dato de la API no coincide con la pantalla, es un error y lo corregimos.

2Qué puede leer su sistema

Cada clave lleva uno o más alcances (scopes). Un alcance es el permiso para leer un tipo de dato: la clave solo lee lo que el hotel le marcó al crearla, y cada endpoint exige el suyo.

Alcance y endpoints	Qué datos	Campos de ejemplo
Plan de cuentas`plan_cuentas · GET /plan-de-cuentas`	Qué datosEl plan de cuentas del hotel (la plantilla USALI del país o el plan propio), para relacionarlo con el de su sistema.	Campos de ejemplo`codigo, nombre, tipo, departamento, papel`
Asientos del día`asientos · GET /asientos · GET /asientos/{fecha} · webhook asiento.dia_cerrado`	Qué datosUn asiento por día en partida doble, con las mismas líneas que la exportación del Back Office, incluida la conciliación bancaria.	Campos de ejemplo`numero, fecha, estado, lineas[].cuenta, debe, haber, codigo, ajuste_de, balancea`
Ingresos e informe USALI`ingresos · GET /ingresos · GET /informe-usali`	Qué datosLos ingresos de cada día por departamento USALI, con IVA, ocupación, ADR y RevPAR; y el estado de resultados USALI del mes, con el año anterior y los acumulados.	Campos de ejemplo`departamentos[].codigo, total, iva, ocupacion_pct, adr, revpar`
Cobros`cobros · GET /cobros`	Qué datosLos cobros de cada día por forma de pago y por destino: aplicados a cuentas de huéspedes o señas de llegadas futuras.	Campos de ejemplo`por_forma_de_pago[], aplicados_a_cuentas, senas_de_llegadas_futuras, total`
Comprobantes`comprobantes · GET /comprobantes`	Qué datosLos comprobantes fiscales emitidos (facturas electrónicas del SRI o de ARCA) y recibidos (compras a proveedores, con saldo y vencimiento).	Campos de ejemplo`tipo, numero, autorizacion, fecha, contraparte, identificacion, base, iva, total, saldo, vence`
Retenciones`retenciones · GET /retenciones`	Qué datosLas retenciones de IVA y renta (Ecuador): las que los clientes le hicieron al hotel y, si el hotel es agente de retención, las que hizo a sus proveedores.	Campos de ejemplo`numero, autorizacion, identificacion, iva_retenido, renta_retenida, total`
Cuentas por cobrar`cuentas_cobrar · GET /cuentas-por-cobrar`	Qué datosLo que deben agencias y empresas, reserva por reserva, con vencimiento y antigüedad. De los huéspedes particulares que deben, solo la reserva y el saldo.	Campos de ejemplo`clientes[].nombre, por_antiguedad, limite_credito, documentos[].reserva, saldo`
Cuentas por pagar`cuentas_pagar · GET /cuentas-por-pagar`	Qué datosEl saldo por proveedor y la lista de vencimientos.	Campos de ejemplo`proveedores[].proveedor, saldo, vencido, vencimientos[].vence`

Principio de mínimo privilegio

Conviene dar a cada clave solo los alcances que el sistema realmente usa. Si una clave se filtra, expone menos.

GET /hotel, sin alcance

Sirve para probar la clave: devuelve el hotel, su moneda, el último día cerrado y los alcances que tiene la clave.

3Qué no puede leer ni hacer

No escribe, no cambia y no borra

Todos los endpoints son GET y cada lectura corre en una transacción READ ONLY: aunque alguien lo intentara, la base de datos rechaza cualquier escritura.

No ve otros hoteles (tenant isolation)

El hotel sale de la clave y ningún endpoint recibe un número de hotel. No hay forma de pedir los datos de otro.

No ve datos de tarjetas

Los datos de las tarjetas nunca están en nuestros servidores: los procesa la pasarela de pagos, que cumple PCI DSS.

No ve contraseñas

Ni las del personal ni ninguna otra. De las claves de la propia API guardamos solo una huella irreversible.

No ve datos de contacto de los huéspedes

Ni correos, ni teléfonos, ni direcciones, ni documentos de viaje.

Huéspedes que deben: solo la reserva y el saldo

Sin el nombre. Alcanza para conciliar la cuenta por cobrar.

Nunca el día de hoy ni días futuros

Solo días pasados y, por defecto, solo los que el hotel ya cerró.

No ve la operación del hotel

Ni el planning, ni las reservas futuras, ni las tarifas, ni la ficha del huésped: solo los datos contables de la sección anterior.

4Datos personales que sí salen, y por qué

Aplicamos minimización de datos: la API entrega solo los datos personales que la contabilidad necesita por ley, y ninguno más.

Contraparte e identificación fiscal en comprobantes y retenciones

Nombre o razón social y RUC, CUIT o documento de quien emite o recibe cada comprobante. Son obligatorios en los libros de IVA y en las declaraciones. Si una factura se emitió a nombre de un huésped, su nombre e identificación fiscal salen en ese comprobante, como en cualquier libro de ventas.

Nombre de agencias, empresas y proveedores

En cuentas por cobrar y por pagar, para saber a quién se le cobra y a quién se le paga.

Responsable y encargado del tratamiento

El hotel es el responsable de los datos. Quien se conecta los trata por cuenta del hotel y solo para su contabilidad, como encargado del tratamiento, según la LOPDP de Ecuador y la Ley 25.326 de Argentina.

Audit log sin datos personales

El registro de cada pedido guarda quién pidió qué y cuándo, pero no guarda datos personales ni el contenido de las respuestas.

5Cómo se obtiene el acceso

El acceso no es automático: lo pide el hotel y lo aprueba Global Suite. Así sabemos siempre quién lee los datos de cada hotel y para qué.

Solicitud

El superadmin del hotel la pide en Back Office → Configuración → API contable. Indica quién va a usar la API, con qué sistema y para qué, los contactos técnico y de seguridad, y acepta los compromisos de seguridad y las condiciones de uso.

Revisión

Global Suite revisa la solicitud y, si hace falta, pide más datos.

Aprobación

La solicitud se aprueba o se rechaza con su motivo. El hotel recibe un correo en los dos casos.

Claves

Con el acceso aprobado, el superadmin crea las claves: una por sistema, con sus alcances, su vencimiento, IP permitidas si las quiere y un webhook opcional. Puede revocarlas cuando quiera.

Suspensión

Global Suite puede suspender el acceso de un hotel. Todas sus claves dejan de funcionar en el pedido siguiente, hasta que se reactive.

6Nuestras medidas de seguridad

Claves y autenticación

Bearer token en el encabezado Authorization

La clave viaja siempre dentro del pedido, nunca en la dirección, para que no quede en historiales ni en registros de servidores intermedios.

Secreto aleatorio de 256 bits

Cada clave tiene una parte secreta generada al azar, imposible de adivinar.

Hash Argon2id; la clave se muestra una sola vez

Guardamos solo una huella irreversible de la clave, con el algoritmo que recomienda OWASP. Si se pierde, no se recupera: se revoca y se crea otra.

Scopes con mínimo privilegio

Cada clave lee solo los tipos de datos que se le dieron.

Vencimiento obligatorio y revocación inmediata

Toda clave vence, de 30 días a 2 años. Si se revoca, deja de servir en el pedido siguiente.

IP allowlist por clave (IPv4/IPv6, CIDR)

Opcional: hasta 20 direcciones o redes públicas desde las que se acepta la clave. Desde cualquier otra se rechaza, aunque la clave sea válida.

Par de llaves opcional: HTTP Message Signatures (RFC 9421) con Ed25519 o ECDSA P-256

Para los programadores, en lugar de la clave secreta: su sistema guarda la llave privada y nos da solo la pública. Firma cada pedido, así que ningún secreto viaja ni queda guardado de nuestro lado.

Firma con created, nonce de un solo uso y Content-Digest (RFC 9530)

Cada pedido firmado vale una sola vez y por 5 minutos, y la firma cubre el método, la dirección completa y, si lo hay, el contenido. Si alguien lo copia o lo cambia en el camino, se rechaza.

Datos y conexión

Tenant isolation

Cada clave pertenece a un solo hotel, y en cada pedido el hotel sale de la clave.

Transacción READ ONLY

Cada lectura se hace con la base de datos en modo solo lectura.

TLS 1.2+ y HSTS

La conexión va siempre cifrada. Las versiones viejas del cifrado se rechazan y el sitio exige entrar siempre por HTTPS.

Cache-Control: no-store

Cada respuesta les indica a los intermediarios que no guarden copia de los datos.

Errores RFC 9457 (application/problem+json)

Los errores llegan en un formato estándar, sin detalles internos del sistema.

Audit log de cada pedido

Queda registrado qué clave pidió qué, cuándo, desde qué IP y con qué resultado. El hotel lo ve en su pantalla.

Límites

Rate limiting: 60 req/min por clave

Un límite de pedidos por minuto. Los encabezados RateLimit-* informan cuántos quedan; al pasarse, la respuesta es HTTP 429 con Retry-After, que dice cuántos segundos esperar.

Bloqueo por claves inválidas

Una IP que prueba 20 claves inválidas en 10 minutos queda bloqueada 10 minutos. Frena a quien intente adivinar claves.

Paginación y rangos máximos

Hasta 100 registros por página; hasta 31 días por pedido de asientos, ingresos y cobros, y hasta 366 días de comprobantes y retenciones.

Webhooks

Standard Webhooks (HMAC-SHA256)

El aviso de día cerrado llega firmado, con los encabezados webhook-id, webhook-timestamp y webhook-signature. Su sistema comprueba que lo mandamos nosotros y que no es una repetición. El aviso no lleva importes.

Protección SSRF

Solo aceptamos direcciones https públicas en el puerto 443, sin usuario ni contraseña y sin seguir redirecciones. Una dirección que apunta a una red interna se rechaza.

OWASP API Security Top 10

La API se construyó siguiendo la lista OWASP API Security Top 10 (edición 2023), la referencia internacional de los riesgos más comunes de las API. Estos son los que cubre y cómo.

Riesgo	Cómo lo cubrimos	En lenguaje llano
API1 · BOLA`Broken Object Level Authorization`	Cómo lo cubrimosEl hotel sale de la clave; ningún endpoint recibe un identificador de hotel.	En lenguaje llanoNadie puede ver datos ajenos cambiando un número en el pedido.
API2 · Autenticación`Broken Authentication`	Cómo lo cubrimosClaves de 256 bits con hash Argon2id, o par de llaves con firma RFC 9421 (Ed25519) y nonce de un solo uso; vencimiento, revocación y bloqueo por intentos fallidos.	En lenguaje llanoLas claves no se pueden adivinar ni robar de nuestra base.
API3 · Exposición de propiedades`Broken Object Property Level Authorization`	Cómo lo cubrimosCada respuesta tiene un esquema cerrado con solo los campos necesarios.	En lenguaje llanoNo se cuela ningún dato de más.
API4 · Consumo de recursos`Unrestricted Resource Consumption`	Cómo lo cubrimosRate limiting, paginación y rangos máximos por pedido.	En lenguaje llanoNadie puede saturar el sistema con pedidos.
API5 · Autorización por función`Broken Function Level Authorization`	Cómo lo cubrimosCada endpoint exige su alcance, y todos son de solo lectura.	En lenguaje llanoUna clave no puede hacer más de lo que se le permitió.
API7 · SSRF`Server Side Request Forgery`	Cómo lo cubrimosLa dirección del webhook se valida: https, puerto 443, solo IP públicas y sin redirecciones.	En lenguaje llanoNadie puede usar los avisos para llegar a nuestra red interna.
API8 · Configuración`Security Misconfiguration`	Cómo lo cubrimosTLS 1.2+, HSTS, Cache-Control: no-store y errores sin detalles internos.	En lenguaje llanoEl servidor no deja puertas abiertas por descuido.
API9 · Inventario`Improper Inventory Management`	Cómo lo cubrimosUna sola versión publicada (v1), descrita completa en OpenAPI.	En lenguaje llanoNo hay direcciones viejas u olvidadas abiertas.

Nuestro equipo Purple Team, con certificación en ciberseguridad ISC2 CC

El mismo equipo que cuida toda la plataforma revisa la API, desde el lado del ataque y desde el de la defensa.

Pagos con tarjeta en pasarelas PCI DSS

Las tarjetas se procesan en pasarelas certificadas y nunca pasan por la API contable.

7Requisitos para quien se conecta

La seguridad es compartida: de nada sirve cuidar los datos de este lado si del otro quedan expuestos. Por eso, al pedir el acceso, quien se conecta acepta estos compromisos. Todos son obligatorios.

Compromisos obligatorios

La clave, solo del lado del servidor

En un gestor de secretos o una variable de entorno. Nunca en una página web, una app de celular, una planilla, un correo ni un repositorio de código.

Solo HTTPS, con TLS 1.2 o superior

Ninguna conexión sin cifrar.

Verificar la firma de los webhooks

Si usa avisos: dirección https con certificado válido, y la firma de cada aviso se comprueba antes de procesarlo.

Datos cifrados y personal con MFA

Lo que lee se guarda cifrado y solo lo ve personal autorizado, que entra con autenticación en dos pasos.

Aviso de incidentes en 72 horas

Si la clave se filtra o hay un incidente de seguridad, nos avisa dentro de las 72 horas y revoca la clave.

Uso solo para la contabilidad del hotel

No vende ni cede los datos. Actúa como encargado del tratamiento, según la LOPDP de Ecuador y la Ley 25.326 de Argentina.

Respetar los límites (HTTP 429 + Retry-After)

Ante un 429, espera los segundos que indica Retry-After antes de reintentar.

Datos que se informan en la solicitud

Quién la usa y para qué

Estudio contable o empresa, con RUC o CUIT si tiene; sistema contable y uso previsto.

Contacto técnico y contacto de seguridad

Correo y teléfono de quien hace la integración y de quien responde ante un incidente.

País donde se guardan los datos

Dónde quedan alojados los datos que lee su sistema.

Plazo de conservación

Cuánto tiempo conserva esos datos.

IP fijas de salida (opcional)

Si su sistema sale siempre desde las mismas IP, se cargan en la allowlist de la clave.

Condiciones de uso

Se aceptan al pedir el acceso; la versión y la fecha aceptadas quedan registradas.

8Incidentes y contacto de seguridad

Si cree que una clave quedó expuesta, o encontró un problema de seguridad en la API, actúe en este orden.

Revoque la clave

El superadmin del hotel la revoca en Back Office → Configuración → API contable. Deja de servir en el pedido siguiente; después se crea otra.

Avísenos

Cuéntenos qué pasó, cuándo, qué clave (solo el prefijo, nunca la clave completa) y qué datos pudieron quedar expuestos.

Si encontró una falla

Avísenos en privado antes de hacerla pública, así la corregimos sin poner en riesgo a los hoteles.

Contacto de seguridad

contacto@globalsuite.pro

Asunto del correo

Seguridad: API contable

Escribir al contacto de seguridad

9Versiones y cambios

Versión en la ruta: /v1

Toda la API vive bajo la versión 1. Una versión nueva tendría su propia ruta y convivirían un tiempo.

Cambios compatibles, sin aviso previo

Sumar endpoints, campos o valores nuevos no rompe ninguna integración. Su sistema tiene que ignorar los campos que no conoce.

Cambios incompatibles: 6 meses de aviso

Antes de quitar o cambiar un campo, un endpoint o una versión, avisamos al contacto técnico de cada acceso con al menos 6 meses de anticipación, y lo publicamos en esta página.

Excepción: seguridad

Si una falla de seguridad obliga a cambiar algo antes, lo hacemos de inmediato y avisamos el mismo día.

10Documentación técnica

Disponible al habilitarse

La documentación completa, con cada endpoint, cada campo y ejemplos, estará disponible en estas direcciones cuando la API se habilite. Incluye un ejemplo de verificación de la firma de los webhooks.

Documentación interactiva

https://app.globalsuite.pro/accesos/api/contable/v1/docs

Especificación OpenAPI 3.1 (JSON)

https://app.globalsuite.pro/accesos/api/contable/v1/openapi.json

Dirección base (base URL)

https://app.globalsuite.pro/accesos/api/contable/v1

Códigos de error

401 Unauthorized

Falta la clave, no es válida, venció o se revocó.

403 Forbidden

La clave no tiene el alcance de ese endpoint, o el pedido viene de una IP que no está en la allowlist.

404 Not Found

La API no está habilitada para el hotel, o el día pedido todavía no está cerrado.

422 Unprocessable Content

Parámetros inválidos, por ejemplo una fecha mal escrita o un rango demasiado largo.

429 Too Many Requests

Se pasó el límite de pedidos: espere los segundos de Retry-After.