> ## 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 sirve como una herramienta esencial para construir integraciones financieras con facilidad y confianza. Proporciona una interfaz completamente tipada y amigable para desarrolladores que envuelve la plataforma de servicios financieros de Midaz, permitiéndote concentrarte en tu lógica de negocio en lugar del código. Diseñado para claridad y escalabilidad, el SDK te permite trabajar con Organizaciones, Ledgers, Cuentas, Transacciones y más, ya sea que estés creando un flujo de trabajo simple o gestionando operaciones complejas. En su núcleo, el SDK está construido sobre una arquitectura modular en capas que prioriza el rendimiento, la extensibilidad y una excelente experiencia del desarrollador. ### ¿Por qué usar el SDK de Midaz para TypeScript? * **Seguridad de tipos por diseño**: Construido con soporte completo de TypeScript y definiciones de tipos precisas. * **Patrón de constructor**: Interfaces fluidas y legibles para ayudarte a construir objetos complejos con facilidad. * **Manejo robusto de errores**: Estrategias inteligentes de recuperación y señales de error claras, para que mantengas el control. * **Observabilidad incluida**: Rastreo, métricas y registros, listos desde el primer momento. * **Arquitectura en capas**: Separación limpia entre cliente, entidades, API y modelos. Organizado, predecible, escalable. * **Reintentos automáticos**: Maneja contratiempos transitorios con políticas de reintento configurables. * **Controles de concurrencia**: Herramientas integradas para ejecutar tareas en paralelo, sin perder el control del rendimiento. * **Rápido con caché**: Caché en memoria para aumentar el rendimiento donde cuenta. * **Validación estricta**: Detecta entrada inválida temprano con mensajes de error claros y accionables. ## Comenzando *** ### Prerrequisito * El SDK de Midaz para TypeScript **requiere** TypeScript **v5.8 o posterior**. ### Instalación del SDK Para comenzar a usar el **SDK de Midaz para TypeScript**, **debes** instalar las dependencias usando el siguiente comando: ```bash npm theme={null} npm install @lerianstudio/midaz-sdk ``` ```bash yarn theme={null} yarn add @lerianstudio/midaz-sdk ``` Una vez instalado, sigue los ejemplos en la sección [*Guía de Inicio Rápido*](#guía-de-inicio-rápido) para aprender cómo usar el **SDK de Midaz para TypeScript**. ## Autenticación *** El **SDK de Midaz para TypeScript** se autentica a través del **Access Manager** de Lerian (OAuth). Para un stack local que corre 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 integración con proveedores de identidad externos usando 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 el manejo de tokens por ti, como adquisición, almacenamiento en caché y renovación, por lo que no tienes que preocuparte por gestionar tokens manualmente. #### Desarrollo local (sin autenticación) Para un stack local de Midaz que corre con la autenticación deshabilitada, construye un cliente sin 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 *** En las siguientes secciones, encontrarás ejemplos de código prácticos para ayudarte a entender cómo usar el **SDK de Midaz para TypeScript**. ### Crear un cliente Este es el primer, y posiblemente más importante, 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 La mejor manera de crear activos es con el **Patrón de Constructor** usando `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, agregarás los campos obligatorios `name` y `assetCode` al constructor `const assetInput = createAssetBuilder('US Dollar', 'USD')`, luego agregarás cualquier propiedad adicional con los métodos `with*`. ### Crear una Cuenta La forma más fácil de crear cuentas es con el **Patrón de Constructor** usando `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, agregarás los campos obligatorios `name` y `assetCode` al constructor `const accountInput = createAccountBuilder('Savings Account', 'USD')`, luego agregarás cualquier propiedad adicional con los métodos `with*`. ### Crear una Transacción La forma más fácil de crear cuentas es con el **Patrón de Constructor** usando `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, agregarás todas las propiedades con los métodos `with*`. ### Recuperación de errores Usa 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 proporcionar una experiencia de desarrollador limpia, modular y escalable. Está organizado en tres capas clave, como se muestra en la *Figura 1*, cada una sirviendo un propósito distinto. * **Interfaz del cliente**: Este es el punto de entrada principal para los usuarios del SDK. Gestiona configuraciones como claves API y entornos, inicializa servicios de manera perezosa y expone toda la funcionalidad disponible de manera unificada y descubrible. * **Capa de servicios de entidades**: Esta capa contiene servicios específicos de dominio (por ejemplo, Cuentas, Activos y Transacciones) y ofrece métodos consistentes para operaciones como crear, obtener, actualizar, eliminar y listar. Además, se incluyen operaciones especializadas basadas en las necesidades específicas de cada entidad. * **Capa de servicios centrales**: Estas utilidades fundamentales son utilizadas por todos los servicios de entidades. 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** emplea un patrón de diseño de constructor para ayudarte a ensamblar objetos avanzados de manera directa, segura y adaptable. En lugar de predefinir un conjunto de entradas, proporciona una interfaz fluida, paso a paso y encadenable que te guía a través de todo el proceso. **Funciones de constructor en el SDK:** * Te asisten informándote de los parámetros por adelantado. * Te permiten modificar campos opcionales usando métodos `.with*()` y encadenarlos. * Ayudan a evitar estados inválidos a través de una estructura guiada. * Ocultan la complejidad interna, lo que conduce a una 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 se concentra en aspectos distintos del dominio financiero, como cuentas, activos o transacciones. Estos servicios proporcionan un método confiable para crear, recuperar, actualizar y eliminar datos mientras permiten interacciones significativas con cada tipo de entidad. Además, ofrecen características especializadas diseñadas para tu caso de uso particular, permitiéndote manejar datos financieros con mayor confianza y eficiencia. | 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. | Puedes acceder a cada uno de estos servicios a través del cliente SDK. Siguen una estructura consistente, facilitando la construcción y el mantenimiento de características financieras. ¿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 un conjunto de módulos de utilidad para optimizar operaciones comunes, ya sea que estés optimizando el rendimiento, manejando errores, gestionando configuraciones o mejorando la observabilidad. Estas herramientas están diseñadas para trabajar sin problemas con el resto del SDK y te ayudan a construir aplicaciones financieras robustas 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, se lanza un error estructurado. Este error incluye campos clave para ayudarte a entender y resolver el problema: * `code`: Un identificador corto y consistente para el tipo de error. * `message`: Una descripción legible por humanos. * `details`: (Opcional) Contexto adicional o metadatos. * `status`: El código de estado HTTP, cuando esté disponible. Así es como podrías manejar un error: ```typescript TypeScript theme={null} try { await client.transactions.create(transaction); } catch (err) { console.error(`Error (${err.code}): ${err.message}`); // Opcionalmente: inspeccione err.details o err.status } ``` ### 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 dos veces la autenticación** cuando enfrentes `unauthorized` o `forbidden`. * **Reintenta** en problemas transitorios como `internal_error` o `service_unavailable`. * **Usa `details`** para mostrar información de depuración útil en registros de desarrollo. El SDK está construido para mantener los errores predecibles y accionables, para que puedas enfocarte en construir, no en depurar. **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 mantener las cosas fluidas, automatizadas y listas 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 usando versionado semántico. * Genera registros de cambios para total transparencia. ## ¿Quieres contribuir? *** Si estás pensando en 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 todo lo que necesitas saber para comenzar. ## Licencia *** Este proyecto está licenciado bajo Elastic License 2.0. Para más detalles, consulta la página de [Licencia](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/LICENSE).