> ## 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 do Midaz para TypeScript > Crie integrações financeiras tipadas com o SDK do Midaz para TypeScript: padrão builder, novas tentativas automáticas, observabilidade e validação estrita. O SDK do Midaz para TypeScript ajuda você a criar integrações financeiras. Ele oferece uma interface tipada e fácil de usar para a plataforma de serviços financeiros do Midaz. O SDK funciona com Organizações, Ledgers, Contas, Transações e muito mais. Use-o para um workflow simples ou para operações complexas. ### Por que usar o SDK do Midaz para TypeScript? * **Segurança de tipos por design**: suporte completo a TypeScript com definições de tipo precisas. * **Padrão builder**: interfaces fluentes e legíveis para construir objetos complexos. * **Tratamento de erros**: estratégias de recuperação e sinais de erro claros. * **Observabilidade incluída**: tracing, métricas e logs, prontos para uso. * **Arquitetura em camadas**: separação clara entre client, entities, API e models. * **Novas tentativas automáticas**: políticas de nova tentativa configuráveis para falhas transitórias. * **Controles de concorrência**: ferramentas integradas para executar tarefas em paralelo com throughput controlado. * **Rápido com cache**: cache em memória para melhor desempenho. * **Validação estrita**: detecte entradas inválidas cedo, com mensagens de erro claras. ## Primeiros passos *** ### Pré-requisito * O SDK do Midaz para TypeScript **requer** TypeScript **v5.8 ou posterior**. ### Instalando o SDK Instale o **SDK do Midaz para TypeScript** com um dos comandos a seguir: ```bash npm theme={null} npm install @lerianstudio/midaz-sdk ``` ```bash yarn theme={null} yarn add @lerianstudio/midaz-sdk ``` Depois de instalá-lo, siga o [*Guia de início rápido*](#quick-start-guide) para aprender a usar o SDK. ## Autenticação *** O **SDK do Midaz para TypeScript** se autentica pelo **Access Manager** da Lerian (OAuth). Para uma stack local com autenticação desabilitada, você pode criar um client sem ele. Você nunca chama uma factory `createClient`. Construa uma configuração com `createClientConfigWithAccessManager()` (ou `createClientConfigBuilder()` para uma stack local sem autenticação) e passe-a para `new MidazClient(config)`. #### Autenticação com o Access Manager Para integrar com provedores de identidade externos via 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') ); ``` O Access Manager cuida dos tokens para você: aquisição, cache e renovação. Você não gerencia tokens manualmente. #### Desenvolvimento local (sem autenticação) Para uma stack local do Midaz com autenticação desabilitada, crie um client sem o Access Manager: ```typescript TypeScript theme={null} import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk'; const client = new MidazClient( createClientConfigBuilder().withEnvironment('development') ); ``` Oferecemos um [plugin do Access Manager](/pt/platform/access-manager) que você pode usar. Se quiser saber mais, [fale conosco](https://lerian.studio/contact).

Guia de início rápido

*** As seções a seguir trazem exemplos práticos de código do **SDK do Midaz para TypeScript**. ### Criar um client O client é seu ponto de entrada principal para o SDK. Ele cuida da autenticação e dá acesso a todos os serviços de entidade. **Exemplo:** ```typescript TypeScript theme={null} import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk'; const client = new MidazClient( createClientConfigBuilder().withEnvironment('sandbox') // Options: 'development', 'sandbox', 'production' ); ``` ### Criar um Ativo Crie ativos com o padrão builder e `createAssetBuilder`. **Exemplo:** ```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); ``` Neste código, você adiciona os campos obrigatórios `name` e `assetCode` ao builder `const assetInput = createAssetBuilder('US Dollar', 'USD')`. Depois, adicione quaisquer outras propriedades com métodos `with*`. ### Criar uma Conta Crie contas com o padrão builder e `createAccountBuilder`. **Exemplo:** ```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); ``` Neste código, você adiciona os campos obrigatórios `name` e `assetCode` ao builder `const accountInput = createAccountBuilder('Savings Account', 'USD')`. Depois, adicione quaisquer outras propriedades com métodos `with*`. ### Criar uma Transação Crie transações com o padrão builder e `createTransactionBuilder`. **Exemplo:** ```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(); ``` Neste código, você adiciona todas as propriedades com métodos `with*`. ### Recuperação de erros Use recuperação de erros aprimorada para operações 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, } ); ``` ### Limpar recursos ```typescript TypeScript theme={null} client.close(); ``` ### Usando o Access Manager para autenticação ```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(); ``` ## Arquitetura do SDK *** O SDK do Midaz usa uma arquitetura de serviços em múltiplas camadas. Ela tem três camadas, mostradas na *Figura 1*. Cada camada tem um propósito distinto. * **Interface do client**: este é o ponto de entrada principal para os usuários do SDK. Ela gerencia a configuração, como API keys e ambientes. Ela inicializa os serviços de forma lazy e expõe toda a funcionalidade do SDK. * **Camada de serviços de entidade**: esta camada reúne serviços específicos de domínio, como Contas, Ativos e Transações. Cada serviço oferece métodos consistentes: criar, obter, atualizar, excluir e listar. Cada serviço também adiciona operações especializadas para sua entidade. * **Camada de serviços principais**: todos os serviços de entidade usam esses utilitários fundamentais. Eles cuidam de requisições HTTP, validação de entrada, processamento de erros, observabilidade, configuração e cache. Arquitetura em camadas do SDK do Midaz para TypeScript, com a interface do client sobre a camada de serviços de entidade sobre a camada compartilhada de serviços principais A arquitetura do SDK enfatiza: * **Consistência** por meio de padrões compartilhados entre os serviços. * **Escalabilidade** via injeção de dependência e factories de serviço. * **Confiabilidade** por meio de tratamento de erros aprimorado e respostas tipadas. * **Testabilidade** com suporte para mocking, testes de integração e testes de contrato. Para mais informações sobre a arquitetura, veja as páginas a seguir: * [Visão geral da arquitetura do SDK do Midaz](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/overview.md). * [Arquitetura da interface do client](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/client-interface.md). * [Arquitetura da camada de serviços](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/service-layer.md). ## Padrão builder *** O **SDK do Midaz para TypeScript** usa um padrão builder para ajudar você a montar objetos complexos de forma segura e adaptável. Em vez de um conjunto fixo de entradas, ele oferece uma interface passo a passo, fluente e encadeável. **Funções builder no SDK:** * Informam os parâmetros com antecedência. * Permitem definir campos opcionais com métodos `.with*()` e encadeá-los. * Evitam estados inválidos por meio de uma estrutura guiada. * Ocultam a complexidade interna para melhorar a legibilidade. ### Exemplo ```typescript TypeScript theme={null} const assetInput = createAssetBuilder('USD Currency', 'USD') .withType('currency') .withMetadata({ precision: 2 }) .build(); ``` Você pode então passar esse `assetInput` para o método create correspondente no SDK. Para mais informações, veja a página [Padrão Builder no SDK do Midaz](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/core-concepts/builder-pattern.md). ## Trabalhando com entidades *** Cada serviço de entidade cobre uma parte distinta do domínio financeiro, como contas, ativos ou transações. Esses serviços criam, recuperam, atualizam e excluem dados de cada tipo de entidade. Eles também oferecem funcionalidades especializadas para cada caso de uso. | Entidade | Descrição | | :-------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | | [**Organizações**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/organizations.md) | Gerencia unidades de negócio e dados organizacionais. | | [**Ledgers**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/ledgers.md) | Estrutura e gerencia registros financeiros. | | [**Ativos**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/assets.md) | Trabalha com ativos como moedas, commodities e outras unidades de valor. | | [**Contas**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/accounts.md) | Cria, recupera, atualiza e exclui contas dentro de um Ledger. | | [**Segmentos**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/segments.md) | Organiza portfólios para análise e relatórios. | | [**Portfólios**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/portfolios.md) | Agrupa contas e ativos em coleções financeiras significativas. | | [**Saldos**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/balances.md) | Recupera e calcula saldos de ativos para contas. | | [**Cotações de Ativos**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/asset-rates.md) | Lida com taxas de câmbio entre diferentes tipos de ativos. | | [**Transações**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/transactions.md) | Cria e gerencia transações que movimentam ativos entre contas. | | [**Operações**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/operations.md) | Gerencia débitos e créditos atômicos que compõem uma transação. | Você acessa cada serviço pelo client do SDK. Eles seguem uma estrutura consistente, o que facilita construir e manter funcionalidades financeiras. Para mais informações, veja as [páginas de entidades](https://github.com/LerianStudio/midaz-sdk-typescript/tree/main/docs/entities). ## Usando utilitários *** O SDK oferece módulos utilitários para operações comuns: desempenho, tratamento de erros, configuração e observabilidade. | Utilitário | Descrição | | :-------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | | [**Auxiliares de Conta**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/account-helpers.md) | Simplifica lógica e transformações comuns relacionadas a contas. | | [**Cache**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/cache.md) | Habilita cache leve para melhor desempenho em runtime. | | [**Concorrência**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/concurrency.md) | Ajuda a coordenar e limitar tarefas concorrentes de forma segura e eficiente. | | [**Configuração**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/config.md) | Configuração e acesso centralizados. | | [**Dados**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/data.md) | Ajuda com formatação de dados e tarefas de paginação. | | [**Tratamento de Erros**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/error-handling.md) | Oferece estratégias de recuperação e mecanismos de processamento de erros. | | [**Client HTTP**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/http-client.md) | Oferece uma interface HTTP de baixo nível para chamadas diretas à API. | | [**Rede**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/network.md) | Adiciona recursos de rede de alto nível, como novas tentativas e backoff. | | [**Observabilidade**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/observability.md) | Captura traces, métricas e logs para apoiar o monitoramento e a depuração. | | [**Paginação**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/pagination.md) | Lida com respostas paginadas usando auxiliares previsíveis e consistentes. | | [**Validação**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/validation.md) | Valida dados de entrada e saída para ajudar a manter a integridade dos dados. | Para mais informações, veja as [páginas de utilitários](https://github.com/LerianStudio/midaz-sdk-typescript/tree/main/docs/utilities). ## Tratamento de erros *** O **SDK do Midaz para TypeScript** ajuda você a tratar erros de forma clara e consistente. Quando ocorre um erro durante uma operação do SDK, o SDK lança um erro estruturado. O erro inclui campos importantes: * `code`: um identificador curto e consistente para o tipo de erro. * `message`: uma descrição legível para humanos. * `statusCode`: o código de status HTTP, quando disponível. Trate um erro assim: ```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 erro comuns | Código | Descrição | Status HTTP | | :-------------------- | :------------------------------------------------------------------- | :---------- | | `invalid_input` | Sua requisição está sem dados obrigatórios ou tem valores inválidos. | `400` | | `unauthorized` | A autenticação falhou ou as credenciais estão ausentes. | `401` | | `forbidden` | Você não tem permissão para realizar esta ação. | `403` | | `not_found` | O recurso que você está tentando acessar não existe. | `404` | | `conflict` | A operação conflita com um recurso existente. | `409` | | `internal_error` | Algo deu errado do nosso lado. | `500` | | `service_unavailable` | Indisponibilidade temporária, tente novamente mais tarde. | `503` | ### Boas práticas * **Valide a entrada** antes de chamar métodos do SDK, para evitar `invalid_input`. * **Verifique sua autenticação** quando receber `unauthorized` ou `forbidden`. * **Tente novamente** em problemas transitórios como `internal_error` ou `service_unavailable`. * **Use `statusCode` e `message`** para mostrar informações de depuração nos logs de desenvolvimento. Para mais informações, veja as páginas a seguir: * [Tratamento de erros no SDK do Midaz](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/core-concepts/error-handling.md). * [Arquitetura de tratamento de erros](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/error-handling.md). * [Tratamento de erros (Utilitários)](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/error-handling.md). ## Pipeline de CI/CD *** Usamos o GitHub Actions para builds automatizados e prontos para produção: * Executa testes em várias versões do Node.js. * Aplica qualidade de código com ESLint e Prettier. * Mantém as dependências atualizadas com o Dependabot. * Cuida dos releases automaticamente com versionamento semântico. * Gera changelogs. ## Quer contribuir? *** Para contribuir com o SDK do Midaz para TypeScript, comece pelo nosso [guia de contribuição no GitHub](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/CONTRIBUTING.md). ## Licença *** Este projeto está licenciado sob a Apache License 2.0. Para detalhes, veja a página [Licença](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/LICENSE).