> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # SDK de Midaz para TypeScript > Construye integraciones financieras tipadas con el SDK de Midaz para TypeScript — builder pattern, reintentos automáticos, observabilidad y validación estricta. El SDK de Midaz para TypeScript te ayuda a construir integraciones financieras. Te da una interfaz tipada y amigable para desarrolladores sobre la plataforma de servicios financieros de Midaz. Te concentras en tu lógica de negocio, no en el código de transporte. El SDK trabaja con Organizaciones, Ledgers, Cuentas, Transacciones y más. Úsalo para un flujo de trabajo simple o para operaciones complejas. Una arquitectura modular en capas soporta el rendimiento, la extensibilidad y la experiencia del desarrollador. ### ¿Por qué usar el SDK de Midaz para TypeScript? * **Seguridad de tipos por diseño**: Soporte completo de TypeScript con definiciones de tipos precisas. * **Patrón de constructor**: Interfaces fluidas y legibles para construir objetos complejos. * **Manejo robusto de errores**: Estrategias de recuperación y señales de error claras. * **Observabilidad incluida**: Rastreo, métricas y registros, listos para usar. * **Arquitectura en capas**: Separación limpia entre cliente, entidades, API y modelos. * **Reintentos automáticos**: Políticas de reintento configurables para fallos transitorios. * **Controles de concurrencia**: Herramientas integradas para ejecutar tareas en paralelo con control del rendimiento. * **Rápido con caché**: Caché en memoria para mejor rendimiento. * **Validación estricta**: Detecta entrada inválida temprano con mensajes de error claros. ## Comenzando *** ### Prerrequisito * El SDK de Midaz para TypeScript **requiere** TypeScript **v5.8 o posterior**. ### Instalación del SDK Instala el **SDK de Midaz para TypeScript** con uno de los siguientes comandos: ```bash npm theme={null} npm install @lerianstudio/midaz-sdk ``` ```bash yarn theme={null} yarn add @lerianstudio/midaz-sdk ``` Después de instalarlo, sigue la [*Guía de Inicio Rápido*](#guía-de-inicio-rápido) para aprender a usar el SDK. ## Autenticación *** El **SDK de Midaz para TypeScript** se autentica a través del **Access Manager** de Lerian (OAuth). Para un stack local con la autenticación deshabilitada, puedes construir un cliente sin él. Nunca llamas a una función `createClient` — construye una configuración con `createClientConfigWithAccessManager()` (o `createClientConfigBuilder()` para un stack local sin autenticación) y pásala a `new MidazClient(config)`. #### Autenticación con Access Manager Para integrar con proveedores de identidad externos mediante OAuth: ```typescript TypeScript theme={null} import { createClientConfigWithAccessManager, MidazClient } from '@lerianstudio/midaz-sdk'; const client = new MidazClient( createClientConfigWithAccessManager({ address: 'https://auth.example.com', clientId: 'tu-client-id', clientSecret: 'tu-client-secret', }).withEnvironment('sandbox') ); ``` El Access Manager maneja los tokens por ti: adquisición, almacenamiento en caché y renovación. No gestionas tokens manualmente. #### Desarrollo local (sin autenticación) Para un stack local de Midaz con la autenticación deshabilitada, construye un cliente sin el Access Manager: ```typescript TypeScript theme={null} import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk'; const client = new MidazClient( createClientConfigBuilder().withEnvironment('development') ); ``` Ofrecemos un [plugin de Access Manager](/es/platform/access-manager/access-manager) que puedes usar. Si deseas saber más al respecto, [contáctanos](https://lerian.studio/contact). ## Guía de inicio rápido *** Las siguientes secciones te dan ejemplos de código prácticos para el **SDK de Midaz para TypeScript**. ### Crear un cliente Este es el primer paso. El cliente es tu punto de entrada principal al SDK. Maneja la autenticación y te da acceso a todos los servicios de entidades. **Ejemplo:** ```typescript TypeScript theme={null} import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk'; const client = new MidazClient( createClientConfigBuilder().withEnvironment('sandbox') // Options: 'development', 'sandbox', 'production' ); ``` ### Crear un Activo Crea activos con el patrón de constructor y `createAssetBuilder`. **Ejemplo:** ```typescript TypeScript theme={null} import { createAssetBuilder } from '@lerianstudio/midaz-sdk'; const assetInput = createAssetBuilder('US Dollar', 'USD') .withType('currency') .withMetadata({ precision: 2, symbol: '$' }) .build(); const asset = await client.entities.assets.createAsset('org_123', 'ledger_456', assetInput); ``` En este código, agregas los campos obligatorios `name` y `assetCode` al constructor `const assetInput = createAssetBuilder('US Dollar', 'USD')`. Luego agregas cualquier otra propiedad con los métodos `with*`. ### Crear una Cuenta Crea cuentas con el patrón de constructor y `createAccountBuilder`. **Ejemplo:** ```typescript TypeScript theme={null} import { createAccountBuilder } from '@lerianstudio/midaz-sdk'; const accountInput = createAccountBuilder('Savings Account', 'USD') .withType('savings') .withAlias('personal-savings') .build(); const account = await client.entities.accounts.createAccount('org_123', 'ledger_456', accountInput); ``` En este código, agregas los campos obligatorios `name` y `assetCode` al constructor `const accountInput = createAccountBuilder('Savings Account', 'USD')`. Luego agregas cualquier otra propiedad con los métodos `with*`. ### Crear una Transacción Crea transacciones con el patrón de constructor y `createTransactionBuilder`. **Ejemplo:** ```typescript TypeScript expandable theme={null} import { createTransactionBuilder } from '@lerianstudio/midaz-sdk'; const transactionInput = createTransactionBuilder() .withCode('payment_001') .withOperations([ { accountId: 'source_account_id', assetCode: 'USD', amount: 100 * 100, // $100.00 type: 'debit', }, { accountId: 'destination_account_id', assetCode: 'USD', amount: 100 * 100, // $100.00 type: 'credit', }, ]) .withMetadata({ purpose: 'Pago mensual' }) .build(); ``` En este código, agregas todas las propiedades con los métodos `with*`. ### Recuperación de errores Usa la recuperación de errores mejorada para operaciones críticas. ```typescript TypeScript theme={null} import { withEnhancedRecovery } from '@lerianstudio/midaz-sdk/util/error'; const result = await withEnhancedRecovery( () => client.entities.transactions.createTransaction('org_123', 'ledger_456', transactionInput), { maxRetries: 3, enableSmartRecovery: true, } ); ``` ### Limpiar recursos ```typescript TypeScript theme={null} client.close(); ``` ### Usar Access Manager para autenticación ```typescript TypeScript expandable theme={null} import { createClientConfigWithAccessManager, MidazClient } from '@lerianstudio/midaz-sdk'; // Inicializa el cliente con autenticación de Access Manager const client = new MidazClient( createClientConfigWithAccessManager({ address: 'https://auth.example.com', // Dirección del proveedor de identidad clientId: 'your-client-id', // ID del cliente OAuth clientSecret: 'your-client-secret', // Secreto del cliente OAuth tokenEndpoint: '/oauth/token', // Opcional, por defecto '/oauth/token' refreshThresholdSeconds: 300, // Opcional, por defecto 300 (5 minutos) }) .withEnvironment('sandbox') .withApiVersion('v1') ); // El SDK gestionará automáticamente la obtención y renovación del token // Ahora puedes usar el cliente con normalidad const organizations = await client.entities.organizations.listOrganizations(); // Para configuraciones específicas por entorno con Access Manager const sandboxClient = new MidazClient( createSandboxConfigWithAccessManager({ address: 'https://auth.example.com', clientId: 'your-client-id', clientSecret: 'your-client-secret', }) ); // Libera los recursos cuando termines client.close(); ``` ## Arquitectura del SDK *** El SDK de Midaz usa una arquitectura de servicios de múltiples capas para una experiencia de desarrollador limpia, modular y escalable. Tiene tres capas, mostradas en la *Figura 1*. Cada capa sirve un propósito distinto. * **Interfaz del cliente**: Este es el punto de entrada principal para los usuarios del SDK. Gestiona la configuración como claves API y entornos. Inicializa servicios de manera perezosa y expone toda la funcionalidad del SDK. * **Capa de servicios de entidades**: Esta capa contiene servicios específicos de dominio, como Cuentas, Activos y Transacciones. Cada servicio ofrece métodos consistentes: crear, obtener, actualizar, eliminar y listar. Cada servicio también agrega operaciones especializadas para su entidad. * **Capa de servicios centrales**: Todos los servicios de entidades usan estas utilidades fundamentales. Manejan solicitudes HTTP, validación de entrada, procesamiento de errores, observabilidad, configuración y almacenamiento en caché. Arquitectura en capas del SDK de Midaz para TypeScript, con la interfaz de cliente sobre la capa de servicios de entidad y esta sobre la capa de servicios centrales compartidos La arquitectura del SDK enfatiza: * **Consistencia** a través de patrones compartidos en todos los servicios. * **Escalabilidad** mediante inyección de dependencias y fábricas de servicios. * **Confiabilidad** a través de manejo mejorado de errores y respuestas tipadas. * **Facilidad de prueba** con soporte para pruebas de simulación, integración y contrato. ¿Quieres profundizar más? Consulta las siguientes páginas para más información sobre la Arquitectura: * [Resumen de la arquitectura del SDK de Midaz](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/overview.md). * [Arquitectura de la interfaz del cliente](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/client-interface.md). * [Arquitectura de la capa de servicio](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/service-layer.md). ## Patrón de constructor *** El **SDK de Midaz para TypeScript** usa un patrón de constructor para ayudarte a ensamblar objetos complejos de manera segura y adaptable. En lugar de un conjunto fijo de entradas, te da una interfaz fluida, paso a paso y encadenable. **Funciones de constructor en el SDK:** * Te informan los parámetros por adelantado. * Te permiten definir campos opcionales con los métodos `.with*()` y encadenarlos. * Evitan estados inválidos a través de una estructura guiada. * Ocultan la complejidad interna para mejor legibilidad. ### Ejemplo Aquí hay un ejemplo rápido: ```typescript TypeScript theme={null} const assetInput = createAssetBuilder('USD Currency', 'USD') .withType('currency') .withMetadata({ precision: 2 }) .build(); ``` Luego puedes pasar este `assetInput` al método de creación correspondiente en el SDK. ¿Quieres profundizar más? Consulta la página [Patrón de Constructor en el SDK de Midaz](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/core-concepts/builder-pattern.md) para más información. ## Trabajando con entidades *** Cada servicio de entidad cubre una parte distinta del dominio financiero, como cuentas, activos o transacciones. Estos servicios crean, recuperan, actualizan y eliminan datos para cada tipo de entidad. También ofrecen características especializadas para cada caso de uso, para que manejes datos financieros con confianza. | Entidad | Descripción | | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | [**Organizaciones**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/organizations.md) | Gestionar unidades de negocio y datos organizacionales. | | [**Ledgers**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/ledgers.md) | Estructurar y gestionar registros financieros. | | [**Activos**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/assets.md) | Trabajar con activos como monedas, commodities y otras unidades de valor. | | [**Cuentas**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/accounts.md) | Crear, recuperar, actualizar y eliminar cuentas dentro de un Libro Contable. | | [**Segmentos**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/segments.md) | Organizar portafolios para análisis e informes. | | [**Portafolios**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/portfolios.md) | Agrupar cuentas y activos en colecciones financieras significativas. | | [**Saldos**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/balances.md) | Recuperar y calcular saldos de activos para cuentas. | | [**Tasas de Activos**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/asset-rates.md) | Manejar tasas de cambio entre diferentes tipos de activos. | | [**Transacciones**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/transactions.md) | Crear y gestionar transacciones que mueven activos entre cuentas. | | [**Operaciones**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/operations.md) | Gestionar débitos y créditos atómicos que conforman una transacción. | Accedes a cada servicio a través del cliente SDK. Siguen una estructura consistente, para que construyas y mantengas características financieras más fácilmente. ¿Quieres profundizar más? Consulta las [páginas de Entidades](https://github.com/LerianStudio/midaz-sdk-typescript/tree/main/docs/entities) para más información. ## Uso de utilidades *** El SDK proporciona módulos de utilidad para operaciones comunes: rendimiento, manejo de errores, configuración y observabilidad. Estas herramientas trabajan con el resto del SDK y te ayudan a construir aplicaciones financieras con menos esfuerzo. | Utilidad | Descripción | | :-------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- | | [**Ayudantes de Cuenta**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/account-helpers.md) | Simplifica la lógica y transformaciones comunes relacionadas con cuentas. | | [**Caché**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/cache.md) | Habilita almacenamiento en caché ligero para un mejor rendimiento en tiempo de ejecución. | | [**Concurrencia**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/concurrency.md) | Ayuda a coordinar y limitar tareas concurrentes de manera segura y eficiente. | | [**Configuración**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/config.md) | Configuración y acceso centralizados. | | [**Datos**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/data.md) | Asiste con formateo de datos y tareas de paginación. | | [**Manejo de Errores**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/error-handling.md) | Ofrece estrategias de recuperación y mecanismos de procesamiento de errores. | | [**Cliente HTTP**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/http-client.md) | Proporciona una interfaz HTTP de bajo nivel para llamadas API directas. | | [**Red**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/network.md) | Agrega características de red de alto nivel como reintentos y retroceso. | | [**Observabilidad**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/observability.md) | Captura trazas, métricas y registros para soportar monitoreo y depuración. | | [**Paginación**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/pagination.md) | Maneja respuestas paginadas con ayudantes predecibles y consistentes. | | [**Validación**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/validation.md) | Valida datos de entrada y salida para ayudar a mantener la integridad de datos. | ¿Quieres profundizar más? Consulta las [páginas de Utilidades](https://github.com/LerianStudio/midaz-sdk-typescript/tree/main/docs/utilities) para más información. ## Manejo de errores *** El **SDK de Midaz para TypeScript** te ayuda a manejar errores de manera clara y consistente. Cuando ocurre un error durante una operación del SDK, el SDK lanza un error estructurado. El error incluye campos clave: * `code`: Un identificador corto y consistente para el tipo de error. * `message`: Una descripción legible por humanos. * `statusCode`: El código de estado HTTP, cuando esté disponible. Maneja un error así: ```typescript TypeScript theme={null} try { await client.transactions.create(transaction); } catch (err) { console.error(`Error (${err.code}): ${err.message}`); // Opcionalmente: inspecciona err.statusCode } ``` ### Códigos de error comunes | Código | Descripción | Estado HTTP | | :-------------------- | :------------------------------------------------------------- | :---------- | | `invalid_input` | Tu solicitud falta datos requeridos o tiene valores inválidos. | `400` | | `unauthorized` | La autenticación falló o faltan credenciales. | `401` | | `forbidden` | No tienes permiso para realizar esta acción. | `403` | | `not_found` | El recurso al que intentas acceder no existe. | `404` | | `conflict` | La operación entra en conflicto con un recurso existente. | `409` | | `internal_error` | Algo salió mal de nuestro lado. | `500` | | `service_unavailable` | Interrupción temporal—intenta de nuevo más tarde. | `503` | ### Mejores prácticas * **Valida la entrada** antes de llamar a los métodos del SDK, para evitar `invalid_input`. * **Verifica tu autenticación** cuando obtengas `unauthorized` o `forbidden`. * **Reintenta** en problemas transitorios como `internal_error` o `service_unavailable`. * **Usa `statusCode` y `message`** para mostrar información de depuración en los registros de desarrollo. El SDK mantiene los errores predecibles y accionables. **Consejo** ¿Quieres profundizar más? Consulta las siguientes páginas para más información: * [Manejo de errores en el SDK de Midaz](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/core-concepts/error-handling.md). * [Arquitectura de manejo de errores](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/error-handling.md). * [Manejo de errores (Utilidades)](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/error-handling.md). ## Pipeline de CI/CD *** Usamos GitHub Actions para builds automatizados y listos para producción: * Ejecuta pruebas en múltiples versiones de Node.js. * Hace cumplir la calidad del código con ESLint y Prettier. * Mantiene las dependencias actualizadas con Dependabot. * Maneja versiones automáticamente con versionado semántico. * Genera registros de cambios. ## ¿Quieres contribuir? *** Para contribuir al SDK de Midaz para TypeScript, comienza con nuestra [guía de contribución en GitHub](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/CONTRIBUTING.md). Cubre lo que necesitas para comenzar. ## Licencia *** Este proyecto está licenciado bajo la Apache License 2.0. Para más detalles, consulta la página de [Licencia](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/LICENSE).