> ## 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 > Crea integraciones financieras tipadas con el SDK de Midaz para TypeScript: patrón builder, reintentos automáticos, observabilidad y validación estricta. El SDK de Midaz para TypeScript te ayuda a crear integraciones financieras. Te da una interfaz tipada, clara para desarrolladores, sobre la plataforma de servicios financieros de Midaz. El SDK funciona con Organizaciones, Ledgers, Cuentas y Transacciones, entre otras entidades. Úsalo para un workflow simple o para operaciones complejas. ### ¿Por qué usar el SDK de Midaz para TypeScript? * **Tipado seguro por diseño**: compatibilidad total con TypeScript y definiciones de tipos precisas. * **Patrón builder**: interfaces fluidas y legibles para construir objetos complejos. * **Manejo de errores**: estrategias de recuperación y señales de error claras. * **Observabilidad incluida**: trazas, métricas y logs listos para usar. * **Arquitectura por capas**: separación clara entre el cliente, las entidades, la API y los modelos. * **Reintentos automáticos**: políticas de reintento configurables para fallas transitorias. * **Controles de concurrencia**: herramientas integradas para ejecutar tareas en paralelo con un rendimiento controlado. * **Rápido gracias al cache**: cache en memoria para un mejor rendimiento. * **Validación estricta**: detecta datos de entrada inválidos desde el principio, con mensajes de error claros. ## Primeros pasos *** ### Prerrequisito * El SDK de Midaz para TypeScript **requiere** TypeScript **v5.8 o posterior**. ### Instalar el 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*](#quick-start-guide) 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 crear un cliente sin ella. Nunca llamas a una fábrica `createClient`. Crea 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 integrarte 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: 'your-client-id', clientSecret: 'your-client-secret', }).withEnvironment('sandbox') ); ``` El Access Manager gestiona los tokens por ti: adquisición, cache y renovación. No administras tokens de forma manual. #### Desarrollo local (sin autenticación) Para un stack local de Midaz con la autenticación deshabilitada, crea 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) que puedes usar. Si quieres saber más, [contáctanos](https://lerian.studio/contact).

Guía de inicio rápido

*** Las siguientes secciones dan ejemplos de código prácticos para el **SDK de Midaz para TypeScript**. ### Crear un cliente El cliente es tu punto de entrada principal al SDK. Gestiona 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 assets con el patrón builder 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 builder `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 builder 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 builder `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 builder 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: 'Monthly payment' }) .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, } ); ``` ### Liberar recursos ```typescript TypeScript theme={null} client.close(); ``` ### Usar Access Manager para la autenticación ```typescript TypeScript expandable theme={null} import { createClientConfigWithAccessManager, MidazClient } from '@lerianstudio/midaz-sdk'; // Initialize the client with Access Manager authentication const client = new MidazClient( createClientConfigWithAccessManager({ address: 'https://auth.example.com', // Identity provider address clientId: 'your-client-id', // OAuth client ID clientSecret: 'your-client-secret', // OAuth client secret tokenEndpoint: '/oauth/token', // Optional, defaults to '/oauth/token' refreshThresholdSeconds: 300, // Optional, defaults to 300 (5 minutes) }) .withEnvironment('sandbox') .withApiVersion('v1') ); // The SDK will automatically handle token acquisition and renewal // You can now use the client as normal const organizations = await client.entities.organizations.listOrganizations(); // For environment-specific configurations with Access Manager const sandboxClient = new MidazClient( createSandboxConfigWithAccessManager({ address: 'https://auth.example.com', clientId: 'your-client-id', clientSecret: 'your-client-secret', }) ); // Clean up resources when done client.close(); ``` ## Arquitectura del SDK *** El SDK de Midaz usa una arquitectura de servicios en varias capas. Tiene tres capas, que se muestran en la *Figura 1*. Cada capa cumple un propósito distinto. * **Interfaz de cliente**: es el punto de entrada principal para los usuarios del SDK. Gestiona la configuración, como las claves de API y los entornos. Inicializa los servicios de forma diferida y expone toda la funcionalidad del SDK. * **Capa de servicios de entidades**: esta capa contiene los servicios específicos del 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 core**: todos los servicios de entidades usan estas utilidades fundamentales. Gestionan las solicitudes HTTP, la validación de entradas, el procesamiento de errores, la observabilidad, la configuración y el cache. Arquitectura por capas del SDK de Midaz para TypeScript, con la interfaz de cliente sobre la capa de servicios de entidades sobre la capa compartida de servicios core La arquitectura del SDK hace énfasis en: * **Consistencia** mediante patrones compartidos entre los servicios. * **Escalabilidad** a través de la inyección de dependencias y las fábricas de servicios. * **Confiabilidad** mediante un manejo de errores mejorado y respuestas tipadas. * **Capacidad de prueba**: admite mocking, pruebas de integración y pruebas de contrato. Para más información sobre la arquitectura, consulta las siguientes páginas: * [Descripción general de la arquitectura del SDK de Midaz](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/overview.md). * [Arquitectura de la interfaz de cliente](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/client-interface.md). * [Arquitectura de la capa de servicios](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/service-layer.md). ## Patrón builder *** El **SDK de Midaz para TypeScript** usa un patrón builder para ayudarte a ensamblar objetos complejos de forma segura y adaptable. En lugar de un conjunto fijo de entradas, te da una interfaz fluida, encadenable y paso a paso. **Funciones builder en el SDK:** * Te indican los parámetros de antemano. * Te permiten configurar campos opcionales con los métodos `.with*()` y encadenarlos. * Evitan estados inválidos mediante una estructura guiada. * Ocultan la complejidad interna para una mejor legibilidad. ### Ejemplo ```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. Para más información, consulta la página [Patrón builder en el SDK de Midaz](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/core-concepts/builder-pattern.md). ## Trabajar 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 funciones especializadas para cada caso de uso. | Entidad | Descripción | | :----------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | | [**Organizations**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/organizations.md) | Gestiona unidades de negocio y datos organizacionales. | | [**Ledgers**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/ledgers.md) | Estructura y gestiona los registros financieros. | | [**Assets**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/assets.md) | Trabaja con activos, como monedas, materias primas y otras unidades de valor. | | [**Accounts**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/accounts.md) | Crea, recupera, actualiza y elimina cuentas dentro de un Ledger. | | [**Segments**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/segments.md) | Organiza portafolios para análisis e informes. | | [**Portfolios**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/portfolios.md) | Agrupa cuentas y activos en colecciones financieras significativas. | | [**Balances**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/balances.md) | Recupera y calcula los saldos de activos para las cuentas. | | [**Asset Rates**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/asset-rates.md) | Gestiona las tasas de cambio entre distintos tipos de activos. | | [**Transactions**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/transactions.md) | Crea y gestiona transacciones que mueven activos entre cuentas. | | [**Operations**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/operations.md) | Gestiona los débitos y créditos atómicos que conforman una transacción. | Accedes a cada servicio a través del cliente del SDK. Siguen una estructura consistente, así que puedes construir y mantener funciones financieras con mayor facilidad. Para más información, consulta las [páginas de Entidades](https://github.com/LerianStudio/midaz-sdk-typescript/tree/main/docs/entities). ## Usar utilidades *** El SDK ofrece módulos de utilidades para operaciones comunes: rendimiento, manejo de errores, configuración y observabilidad. | Utilidad | Descripción | | :---------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | | [**Account Helpers**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/account-helpers.md) | Simplifica la lógica y las transformaciones comunes relacionadas con cuentas. | | [**Cache**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/cache.md) | Habilita un cache liviano para un mejor rendimiento en tiempo de ejecución. | | [**Concurrency**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/concurrency.md) | Ayuda a coordinar y limitar tareas concurrentes de forma segura y eficiente. | | [**Config**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/config.md) | Configuración y acceso centralizados. | | [**Data**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/data.md) | Ayuda con el formateo de datos y las tareas de paginación. | | [**Error Handling**](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. | | [**HTTP Client**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/http-client.md) | Ofrece una interfaz HTTP de bajo nivel para llamadas directas a la API. | | [**Network**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/network.md) | Agrega funciones de red de alto nivel, como reintentos y backoff. | | [**Observability**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/observability.md) | Captura trazas, métricas y logs para el monitoreo y la depuración. | | [**Pagination**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/pagination.md) | Gestiona respuestas paginadas con ayudantes predecibles y consistentes. | | [**Validation**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/validation.md) | Valida los datos de entrada y salida para ayudar a mantener la integridad de los datos. | Para más información, consulta las [páginas de Utilidades](https://github.com/LerianStudio/midaz-sdk-typescript/tree/main/docs/utilities). ## Manejo de errores *** El **SDK de Midaz para TypeScript** te ayuda a manejar errores de forma 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 breve y consistente para el tipo de error. * `message`: una descripción legible para las personas. * `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}`); // Optionally: inspect err.statusCode } ``` ### Códigos de error comunes | Código | Descripción | Estado HTTP | | :-------------------- | :------------------------------------------------------------------- | :---------- | | `invalid_input` | Tu solicitud carece de datos obligatorios o tiene valores inválidos. | `400` | | `unauthorized` | La autenticación falló o faltan credenciales. | `401` | | `forbidden` | No tienes permiso para hacer 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: vuelve a intentarlo más tarde. | `503` | ### Mejores prácticas * **Valida los datos de entrada** antes de llamar a los métodos del SDK, para evitar `invalid_input`. * **Revisa tu autenticación** cuando obtengas `unauthorized` o `forbidden`. * **Reintenta** ante problemas transitorios como `internal_error` o `service_unavailable`. * **Usa `statusCode` y `message`** para mostrar información de depuración en los logs de desarrollo. Para más información, consulta las siguientes páginas: * [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 varias versiones de Node.js. * Aplica estándares de calidad de código con ESLint y Prettier. * Mantiene las dependencias actualizadas con Dependabot. * Gestiona los lanzamientos automáticamente con versionado semántico. * Genera registros de cambios. ## ¿Quieres contribuir? *** Para contribuir al SDK de Midaz para TypeScript, empieza con nuestra [guía de contribución en GitHub](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/CONTRIBUTING.md). ## Licencia *** Este proyecto está bajo la licencia Apache License 2.0. Para más detalles, consulta la página de [Licencia](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/LICENSE).