Primeiros passos
Passo 1 – Instale o Go
Antes de usar o SDK, você deve instalar o Go na sua máquina.Acesse o site oficial do Go.
Passo 2 - Crie ou use um projeto Go existente
Crie um projeto Go: Para criar um projeto Go, use o seguinte comando:go.mod na raiz. Se não, execute o seguinte comando para criar um:
Passo 3 – Adicione o Midaz SDK
Dentro do diretório do seu projeto, execute o seguinte comando para baixar o Midaz SDK e adicioná-lo aos seus arquivosgo.mod e go.sum:
Passo 4 – Importe o SDK
Crie ou abra um arquivomain.go e adicione o seguinte conteúdo:
- O client do Midaz para chamar APIs.
- Modelos de dados integrados (como CreateOrganizationInput).
- Suporte a autenticação via plugin com Access Manager.
- Um sistema de configuração flexível.
Passo 5 - Execute o projeto
Execute o seguinte comando:Arquitetura do SDK
O Midaz SDK para Go foi projetado para clareza e flexibilidade. Sua arquitetura em camadas permite que você trabalhe com confiança, seja configurando contas ou processando milhares de transações.
Design em camadas
| Camada | O que ela faz |
|---|---|
| Client | O ponto de entrada principal que conecta tudo. |
| Entities | Acesso de alto nível a cada serviço do Midaz (Organizations, Ledgers, Accounts, etc.). |
| Models | As estruturas de dados principais que espelham a lógica de domínio do Midaz. |
| Utility Packages | Helpers modulares para config, observabilidade, validação, concorrência e mais. |
Entities
A camadaEntities serve como ponto de acesso a todos os serviços do Midaz, fornecendo interfaces simples e amigáveis. Cada interface lida com um recurso específico e cuida dos detalhes por você. Tudo se conecta de forma fluida via client.Entity, seu hub central para comandos do SDK.
Serviços disponíveis
| Serviço | O que faz |
|---|---|
OrganizationsService | Gerencia organizações. |
LedgersService | Cria e recupera ledgers. |
AssetsService | Define e gerencia assets. |
AssetRatesService | Configura e busca taxas de câmbio de assets. |
AccountsService | Gerencia contas e verifica saldos. |
PortfoliosService | Agrupa contas em Portfólios. |
SegmentsService | Categoriza contas usando segments. |
TransactionsService | Cria e pesquisa transações financeiras. |
OperationsService | Detalha as operações atômicas de uma transação. |
BalancesService | Obtém saldos de contas em tempo real. |
Models
OsModels no SDK refletem como o Midaz pensa sobre finanças, cada um fortemente ligado a conceitos de negócio do mundo real. Você os usará em serviços e operações, desde o onboarding de contas até o registro de eventos financeiros complexos.
Tipos de modelos comuns
| Modelo | O que representa |
|---|---|
Organization | Uma entidade de negócio que possui ledgers e contas. |
Ledger | Uma coleção de contas e transações. |
Asset | Uma unidade de valor (moeda, token, etc.) que pode ser armazenada ou movida. |
Account | Representa uma conta para rastreamento de assets e saldos. |
Portfolio | Uma coleção de contas para agrupamento e gerenciamento. |
Segment | Uma unidade de categorização para organização mais granular. |
Transaction | Um evento financeiro com operações (débitos e créditos). |
Operation | Um lançamento contábil individual dentro de uma transação. |
Balance | O estado atual dos holdings de uma conta. |
Pacotes utilitários
Na pastapkg do SDK, você encontrará diversos pacotes utilitários que abordam desafios comuns de desenvolvimento, desde tratamento de configuração até lógica de retry.
Pacotes incluídos
| Pacote | O que resolve |
|---|---|
config | Tratamento centralizado de config, overrides de env e URLs de serviço customizadas. |
concurrent | Ferramentas para batching, rate-limiting e worker pools. |
observability | Tracing, métricas e logs para manter sua integração visível e debugável. |
pagination | Respostas paginadas. |
validation | Validação de input com mensagens de erro claras e estruturadas. |
errors | Tipos de erro ricos, incluindo detalhes a nível de campo e classificação de erros. |
format | Utilitários para formatação de dados no padrão Midaz (datas, horários, etc.). |
retry | Lógica de retry com backoff exponencial. |
performance | Helpers para acelerar operações em lote ou tarefas de alto throughput. |
Access Manager
O Access Manager oferece uma forma segura e flexível de lidar com autenticação através de provedores de identidade externos. Em vez de codificar tokens diretamente na sua aplicação, basta conectar seu serviço de autenticação e deixar o SDK cuidar do resto.
Por que usar
- Seguro: Sem tokens codificados diretamente.
- Flexível: Funciona com qualquer provedor de identidade que suporte client credentials.
- Centralizado: Gerencie configurações de autenticação em um só lugar.
- Automático: O refresh de token é totalmente gerenciado pelo SDK.
Configuração
Você pode configurar o Access Manager de duas formas:- Via código
- Via variáveis de ambiente
Opção 1: Configure via código
Opção 2: Configure via variáveis de ambiente
Altere as seguintes variáveis no arquivo.env:
O que o SDK faz por você
Uma vez que a autenticação baseada em plugin esteja habilitada, o SDK assume o controle:- Solicita um token do seu serviço de autenticação usando as client credentials.
- Autentica todas as chamadas de API usando o token.
- Renova automaticamente o token quando ele expira.
Variáveis de ambiente
Você também pode configurar o SDK usando variáveis de ambiente; sem necessidade de codificar nada diretamente.
| Variável | Descrição |
|---|---|
MIDAZ_AUTH_TOKEN | Token de autenticação (usado quando nenhum plugin está configurado). |
MIDAZ_ENVIRONMENT | Ambiente alvo (local, development, production). |
MIDAZ_ONBOARDING_URL | Sobrescreve a URL base do serviço de onboarding. |
MIDAZ_TRANSACTION_URL | Sobrescreve a URL base do serviço de transações. |
MIDAZ_DEBUG | Habilita logs de debug (true ou false). |
MIDAZ_MAX_RETRIES | Define o número máximo de tentativas de retry. |
Recursos avançados
Leve sua integração ao próximo nível com suporte integrado para paginação, concorrência e observabilidade.
Paginação
Trabalhe com resultados paginados de forma fácil. O SDK oferece uma interface no estilo iterador para que você possa focar na lógica, não na matemática de paginação. Sem necessidade de gerenciar cursores manualmente, basta iterar e pronto.Utilitários de concorrência
Precisa acelerar as coisas? O SDK vem com helpers poderosos para executar tarefas em paralelo ou em lotes. Esses helpers são ideais para jobs de alto throughput como sincronização de contas ou processamento de transações em massa.Execute em paralelo com WorkerPool
Processe em lotes com Batch
Observabilidade
Obtenha visibilidade completa do que seu código está fazendo, sem nenhuma configuração extra. Habilite tracing, métricas e logs estruturados em uma única linha. Seja debugando ou otimizando desempenho, a observabilidade dá a você a vantagem.Tratamento de erros
O Midaz Go SDK oferece um sistema robusto de tratamento de erros para ajudar você a identificar, classificar e responder a erros de API de forma eficaz. Ele define um conjunto de tipos de erro como
ValidationError, AuthenticationError, ResourceNotFoundError e outros, permitindo categorização precisa de problemas.
Cada erro inclui dados estruturados, incluindo o tipo de erro, código, mensagem, status HTTP, recurso associado e um ID de requisição para depuração ou fins de suporte.
Para simplificar o tratamento de erros, o SDK fornece funções auxiliares que verificam tipos de erro específicos e códigos de status HTTP. Isso permite respostas personalizadas para cenários comuns como input inválido, rate limiting ou recursos não encontrados.
Para falhas transitórias, o SDK suporta mecanismos de retry integrados que lidam com erros de rede, rate limits e erros de servidor com políticas de retry configuráveis. Essas podem ser definidas programaticamente ou via variáveis de ambiente.
Mecanismo de retry
O Midaz Go SDK ajuda você a construir integrações resilientes tratando erros transitórios automaticamente. Se uma requisição falhar por causa de um problema temporário, como problemas de rede ou rate limit, o SDK pode tentar novamente a operação para você, sem que sua aplicação precise fazer isso. Por padrão, o SDK faz retry em:- Problemas temporários de rede.
- Respostas de rate-limiting (com backoff inteligente).
- Erros do lado do servidor (HTTP 5xx).
- Respostas de API explicitamente marcadas como retentáveis.
- Em ambos os exemplos, o SDK tentará até 3 vezes, esperando pelo menos 500ms e no máximo 5s entre as tentativas.
Configure via opções do client
Use esta abordagem para definir programaticamente quantas vezes tentar novamente e quanto tempo esperar entre as tentativas:Configure via variáveis de ambiente
Use esta abordagem para gerenciar o comportamento de retry usando variáveis de ambiente (no arquivo.env):
Explore as APIs
Para mais informações sobre as APIs, consulte os seguintes links

