Panorama de la API

Estado: Limitado

La API del marketplace de T-Suite es la API que usan las propias aplicaciones web de Libertum. Todavía no es un producto público con soporte: no hay una referencia OpenAPI publicada y mantenida, y las rutas y los campos pueden cambiar entre versiones. Esta página sirve para entender la forma de la API; cualquier integración debe acordarse con Libertum antes de construir sobre ella. Está prevista una referencia OpenAPI pública.

Ruta base y hosts

Todas las rutas de la API del marketplace se sirven bajo la ruta base:

/marketplace/v1

en el host de la API de T-Suite del despliegue correspondiente. El host se entrega como parte de un acuerdo de integración.

Las peticiones y respuestas son JSON sobre HTTPS, salvo la subida de archivos (multipart) y el stream de notificaciones en tiempo real (Server-Sent Events).

Grupos de rutas

Grupo	Prefijo	Autenticación
Cuenta	registro, inicio de sesión, verificación de códigos y restablecimiento de contraseña en la raíz de la ruta base	Ninguna (estas rutas crean la sesión)
Autenticadas	/auth/...	Token de acceso del usuario — véase Autenticación
Otros grupos autenticados	órdenes, dividendos y gestión de suscripciones tienen sus propios prefijos	Token de acceso del usuario
Públicas	/public/...	Ninguna — datos de solo lectura que ya son públicos, más algunos flujos protegidos por token
API para desarrolladores de stablecoins	/api/stablecoin/v1	API key del emisor

La mayoría de las rutas de producto bajo /auth/... también pasan por la puerta de onboarding, y los productos de pago comprueban además el módulo de suscripción.

Grupos de recursos

Los principales grupos de recursos, por área de producto. Es un mapa, no una referencia de endpoints.

Inversión y ofertas

Grupo de recursos	Propósito
Ofertas	Crear, configurar, desplegar y listar ofertas; documentos de la oferta; listados Coming Soon e interés
Órdenes	Órdenes de suscripción primaria y sus medios de pago (tarjeta, transferencia bancaria, USDC/USDT vía Escrow)
Acuerdos	Plantillas de acuerdos, especímenes de firma del inversionista, firma, PDFs ejecutados y registros de auditoría
Dividendos	Distribuciones de dividendos a los tenedores de tokens
Transferencias	Solicitudes de transferencia de tokens y el diario de transferencias
Mercado secundario (P2P)	Libro de órdenes entre pares para tokens listados
Redenciones	Ventanas de redención, solicitudes de redención y cuentas de pago del inversionista
Gobernanza	Propuestas y votación de inversionistas
Estados de cuenta del inversionista	Resumen del inversionista y feed combinado de transacciones
Tenencias	Las tenencias de tokens de un usuario

Cuentas y facturación

Grupo de recursos	Propósito
Perfil y seguridad	Perfil, contraseña, autenticación de dos factores y códigos de respaldo, cierre de sesión
KYC / KYB	Sesiones y estado de verificación de identidad (vía SumSub)
Suscripciones	Catálogo de planes y módulos, checkout, cambios de plan, add-ons, portal de facturación
Equipo del emisor	Invitar a miembros del equipo y gestionar roles
Facturación y pagos del emisor	Facturas del emisor, configuración de pagos, cuentas bancarias y métodos de pago guardados
Wallets vinculadas	Wallets externas que el usuario ha conectado
Restricciones por país	La lista gris y la lista negra de países de la plataforma
Soporte	Tickets de soporte y disputas

Wallets y pagos

Grupo de recursos	Propósito
Custodian Wallet	Saldos, datos de depósito, direcciones de retiro guardadas y retiros
Tesorería de gas	Saldo prepagado de gas y cobros de comisiones de red de las transacciones de custodia
T-Pay	Rampa fiat de entrada/salida vía Bridge.xyz (disponibilidad limitada)

Distribución, estructuración y otros productos

Grupo de recursos	Propósito
Distribution Hub	CRM de inversionistas, matching con IA, campañas, pipeline, comunicaciones y funciones de Libby AI
Hosting	Solicitudes de hosting entre marketplaces y el Ecosystem Directory
Structuring	Proyectos de Structuring, intake, investigación, generación de documentos, artefactos y enlaces de revisión para invitados
Trading	Cuentas de paper trading, señales y el feed Discover
Stablecoin Studio	Configuración de stablecoins, órdenes de emisión y redención, y el portal de minters
Whitelabel	Branding del tenant y configuración del dominio propio
Asset Management	Activos, portafolios, clientes, órdenes de trabajo, etiquetas, elementos de cumplimiento, reportes y migración
Notificaciones	Notificaciones en la app y el stream en tiempo real — véase Tiempo real y webhooks
Acreditación	Evidencia de acreditación del inversionista (próximamente — aún no se revisa)
Plataforma XRPL	Infraestructura XRPL (los emisores aún no pueden seleccionarla)

Las rutas públicas cubren datos que ya son visibles en páginas públicas — una vista pública de la oferta y su historial de NAV, las listas de restricciones por país, el branding del tenant, la comisión de la plataforma, el autorregistro de inversionistas del Distribution Hub, y la página de revisión para invitados de Structuring que el abogado externo abre desde un enlace compartido.

Metadatos de tokens. Los metadatos de los tokens ERC-721 se sirven en una ruta separada y permanente fuera de /marketplace/v1, porque esa URL queda escrita en los contratos de los tokens y nunca debe cambiar. Solo resuelve para ofertas ERC-721 aprobadas y desplegadas.

Formato de respuesta

Las respuestas usan un único sobre:

{
  "message": "Mensaje legible",
  "status": 200,
  "data": { },
  "error": false
}

• error es true ante cualquier fallo, y status repite el código de estado HTTP.
• data lleva el contenido en caso de éxito. En algunos fallos lleva detalles legibles por máquina — por ejemplo requiresOnboarding y missingStep de la puerta de onboarding, o reason y moduleId de una comprobación de suscripción.
• Las decisiones deben basarse en status y en los campos de data, no en el texto de message, que puede cambiar.

Excepciones: el stream en tiempo real envía Server-Sent Events, y los metadatos de tokens devuelven metadatos ERC-721 en bruto, sin el sobre.

Códigos de estado

Estado	Cuándo aparece
200 / 201	Éxito
400	La validación falló o la petición no está permitida en el estado actual
401	Token de acceso ausente, inválido, caducado o reemplazado
402	La cuenta no tiene el módulo de suscripción que exige este producto. data.reason indica el caso (por ejemplo, sin suscripción frente a una suscripción vencida que ahora es de solo lectura) y data.moduleId indica el módulo que hay que añadir
403	Sesión iniciada pero sin permiso: paso de 2FA pendiente, onboarding incompleto, rol o persona incorrectos, o cuenta bloqueada
404	No se encontró la ruta o el recurso
409	Conflicto con datos existentes, como un duplicado
429	Se alcanzó el límite de tasa
500	Error inesperado del servidor
503	Una dependencia, como el almacén de sesiones, no está disponible temporalmente — se debe reintentar con backoff

Los productos que hoy responden 402 incluyen Distribution Hub, las funciones de Libby AI, Structuring, Trading y Stablecoin Studio. Una suscripción de Structuring vencida conserva el acceso de lectura y responde 402 solo en las acciones de escritura.

Límites de tasa

Hay límites de tasa en rutas sensibles concretas — por ejemplo, la solicitud de códigos de verificación de retiros, la página pública de revisión de Structuring y la API para desarrolladores de stablecoins (300 peticiones por minuto por cliente). Al alcanzar un límite, la API responde 429; donde aplican, los límites se anuncian en las cabeceras estándar RateLimit-*. Los clientes deben esperar y reintentar en lugar de saturar una ruta.

API para desarrolladores de Stablecoin Studio

Estado: Limitado

Los emisores de Stablecoin Studio cuentan con una pequeña API para desarrolladores, de solo lectura, en /api/stablecoin/v1:

• Autenticación: una API key del emisor, creada y revocada en la página Developer de Stablecoin Studio, enviada como token Bearer o en una cabecera de API key.
• Alcance: cada key lee solo los datos de su propio emisor — tokens, órdenes de emisión, órdenes de redención y uso de la API — además de una comprobación de conectividad.
• Sin escrituras: crear órdenes de emisión y otros cambios siguen en la app de Stablecoin Studio.
• Facturación: el uso de la API se mide por emisor; la facturación del uso de la API para desarrolladores llegará próximamente.

Referencia OpenAPI

Está prevista una referencia OpenAPI pública y mantenida. Hasta que se publique, esta página es la descripción de referencia de la forma de la API, y el detalle a nivel de endpoint se solicita a Libertum como parte de un acuerdo de integración.