Pular para o conteúdo principal
O simplifica a conexão entre sua aplicação e os sistemas financeiros da Lerian. Seja desenvolvendo Ledgers, gerenciando Portfólios ou processando Transactions, este SDK oferece abstrações claras e uma base confiável para suas necessidades de desenvolvimento.

Primeiros passos


Passo 1 – Instale o Go

Antes de usar o SDK, você deve instalar o Go na sua máquina.
2
Baixe o instalador para o seu sistema operacional (Windows, macOS ou Linux).

Passo 2 - Crie ou use um projeto Go existente

Crie um projeto Go: Para criar um projeto Go, use o seguinte comando:
mkdir my-midaz-app
cd my-midaz-app
go mod init my-midaz-app
Use um projeto Go existente: Se você está trabalhando em um projeto existente, certifique-se de que há um arquivo go.mod na raiz. Se não, execute o seguinte comando para criar um:
go mod init your-module-name

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 arquivos go.mod e go.sum:
go get github.com/LerianStudio/midaz-sdk-golang
Usando VS Code ou GoLand? Sua IDE pode executar go get automaticamente quando você importa um novo pacote.

Passo 4 – Importe o SDK

Crie ou abra um arquivo main.go e adicione o seguinte conteúdo:
Lembre-se de alterar os valores na seção // Configure plugin access manager do código com suas próprias credenciais antes de executá-lo.
package main

import (
	"context"
	"fmt"
	"log"

	client "github.com/LerianStudio/midaz-sdk-golang"
	"github.com/LerianStudio/midaz-sdk-golang/models"
	auth "github.com/LerianStudio/midaz-sdk-golang/pkg/access-manager"
	"github.com/LerianStudio/midaz-sdk-golang/pkg/config"
)

func main() {
	// Configure plugin access manager
	AccessManager := auth.AccessManager{
		Enabled:      true,
		Address:      "https://your-auth-service.com",
		ClientID:     "your-client-id",
		ClientSecret: "your-client-secret",
	}

	// Create a configuration with plugin access manager
	cfg, err := config.NewConfig(
		config.WithAccessManager(AccessManager),
	)
	if err != nil {
		log.Fatalf("Failed to create config: %v", err)
	}

	// Create a client
	c, err := client.New(
		client.WithConfig(cfg),
		client.WithEnvironment(config.EnvironmentProduction),
		client.UseAllAPIs(),
	)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Create an organization
	ctx := context.Background()
	org, err := c.Entity.Organizations.CreateOrganization(
		ctx,
		&models.CreateOrganizationInput{
			LegalName:       "Example Corporation",
			LegalDocument:   "123456789",
			DoingBusinessAs: "Example Inc.",
			Address: models.Address{
				Line1:   "123 Main St",
				City:    "New York",
				State:   "NY",
				ZipCode: "10001",
				Country: "US",
			},
		},
	)
	if err != nil {
		log.Fatalf("Failed to create organization: %v", err)
	}

	fmt.Printf("Organization created: %s\n", org.ID)
}
Isso dá acesso a:
  • 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.
Quer saber mais sobre o Access Manager? Confira a seção Access Manager para detalhes.

Passo 5 - Execute o projeto

Execute o seguinte comando:
go run main.go
Quer se aprofundar? Confira a página de Exemplos do Midaz Go SDK para trechos de código práticos que ajudam você a começar.

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

CamadaO que ela faz
ClientO ponto de entrada principal que conecta tudo.
EntitiesAcesso de alto nível a cada serviço do Midaz (Organizations, Ledgers, Accounts, etc.).
ModelsAs estruturas de dados principais que espelham a lógica de domínio do Midaz.
Utility PackagesHelpers modulares para config, observabilidade, validação, concorrência e mais.
Quer se aprofundar? Confira a página de Arquitetura do Midaz Go SDK para mais informações.

Entities

A camada Entities 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çoO que faz
OrganizationsServiceGerencia organizações.
LedgersServiceCria e recupera ledgers.
AssetsServiceDefine e gerencia assets.
AssetRatesServiceConfigura e busca taxas de câmbio de assets.
AccountsServiceGerencia contas e verifica saldos.
PortfoliosServiceAgrupa contas em Portfólios.
SegmentsServiceCategoriza contas usando segments.
TransactionsServiceCria e pesquisa transações financeiras.
OperationsServiceDetalha as operações atômicas de uma transação.
BalancesServiceObtém saldos de contas em tempo real.

Models

Os Models 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

ModeloO que representa
OrganizationUma entidade de negócio que possui ledgers e contas.
LedgerUma coleção de contas e transações.
AssetUma unidade de valor (moeda, token, etc.) que pode ser armazenada ou movida.
AccountRepresenta uma conta para rastreamento de assets e saldos.
PortfolioUma coleção de contas para agrupamento e gerenciamento.
SegmentUma unidade de categorização para organização mais granular.
TransactionUm evento financeiro com operações (débitos e créditos).
OperationUm lançamento contábil individual dentro de uma transação.
BalanceO estado atual dos holdings de uma conta.

Pacotes utilitários

Na pasta pkg 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

PacoteO que resolve
configTratamento centralizado de config, overrides de env e URLs de serviço customizadas.
concurrentFerramentas para batching, rate-limiting e worker pools.
observabilityTracing, métricas e logs para manter sua integração visível e debugável.
paginationRespostas paginadas.
validationValidação de input com mensagens de erro claras e estruturadas.
errorsTipos de erro ricos, incluindo detalhes a nível de campo e classificação de erros.
formatUtilitários para formatação de dados no padrão Midaz (datas, horários, etc.).
retryLógica de retry com backoff exponencial.
performanceHelpers 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
Lembre-se de alterar os valores na seção // Set up plugin-based authentication do código com suas próprias credenciais antes de executá-lo.

Opção 1: Configure via código

// Import the access manager package
import (
    auth "github.com/LerianStudio/midaz-sdk-golang/pkg/access-manager"
    "github.com/LerianStudio/midaz-sdk-golang/pkg/config"
)

// Set up plugin-based authentication
AccessManager := auth.AccessManager{
    Enabled:      true,
    Address:      "https://your-auth-service.com",
    ClientID:     "your-client-id",
    ClientSecret: "your-client-secret",
}

// Pass it to the SDK configuration
cfg, err := config.NewConfig(
    config.WithAccessManager(AccessManager),
)
if err != nil {
    log.Fatalf("Failed to create config: %v", err)
}

client, err := client.New(
    client.WithConfig(cfg),
    client.UseAllAPIs(),
)

Opção 2: Configure via variáveis de ambiente

Altere as seguintes variáveis no arquivo .env:
PLUGIN_AUTH_ENABLED=true
PLUGIN_AUTH_ADDRESS=https://your-auth-service.com
MIDAZ_CLIENT_ID=your-client-id
MIDAZ_CLIENT_SECRET=your-client-secret
Em seguida, carregue-as na sua aplicação:
AccessManager := auth.AccessManager{
    Enabled:      os.Getenv("PLUGIN_AUTH_ENABLED") == "true",
    Address:      os.Getenv("PLUGIN_AUTH_ADDRESS"),
    ClientID:     os.Getenv("MIDAZ_CLIENT_ID"),
    ClientSecret: os.Getenv("MIDAZ_CLIENT_SECRET"),
}

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ávelDescrição
MIDAZ_AUTH_TOKENToken de autenticação (usado quando nenhum plugin está configurado).
MIDAZ_ENVIRONMENTAmbiente alvo (local, development, production).
MIDAZ_ONBOARDING_URLSobrescreve a URL base do serviço de onboarding.
MIDAZ_TRANSACTION_URLSobrescreve a URL base do serviço de transações.
MIDAZ_DEBUGHabilita logs de debug (true ou false).
MIDAZ_MAX_RETRIESDefine o número máximo de tentativas de retry.
Quer se aprofundar? Confira a página de Variáveis de Ambiente no Midaz Go SDK para mais informações.

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.
// Create a paginator for accounts
paginator := client.Entity.Accounts.GetAccountPaginator(ctx, "org-id", "ledger-id", &models.ListOptions{
	Limit: 10,
})

// Iterate through all pages
for paginator.HasNext() {
	accounts, err := paginator.Next()
	if err != nil {
		// Handle error
	}

	for _, account := range accounts.Items {
		// Process each account
	}
}
Quer se aprofundar? Confira a página de Paginação no Midaz Go SDK para mais informações.

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

// Process accounts in parallel
results := concurrent.WorkerPool(
	ctx,
	accountIDs,
	func(ctx context.Context, accountID string) (*models.Account, error) {
		// Fetch account details
		return client.Entity.Accounts.GetAccount(ctx, "org-id", "ledger-id", accountID)
	},
	concurrent.WithWorkers(5), // Use 5 workers
)

Processe em lotes com Batch

// Process items in batches
batchResults := concurrent.Batch(
	ctx,
	transactionIDs,
	10, // Process 10 items per batch
	func(ctx context.Context, batch []string) ([]string, error) {
		// Process the batch and return results
		return processedIDs, nil
	},
	concurrent.WithWorkers(3), // Process 3 batches concurrently
)

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.
// Create a client with observability enabled
client, err := client.New(
	client.WithPluginAccessManager("your-auth-token"),
	client.WithObservability(true, true, true), // Enable tracing, metrics, and logging
	client.UseAllAPIs(),
)
Você também pode rastrear blocos específicos de lógica:
// Trace an operation
err = client.Trace("create-organization", func(ctx context.Context) error {
	_, err := client.Entity.Organizations.CreateOrganization(ctx, input)
	return err
})

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.
Quer se aprofundar? Confira a página de Tratamento de Erros no Midaz Go SDK para mais informações.

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.
Existem duas formas de configurar os parâmetros de retry:
  • 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:
client, err := client.New(
    client.WithRetries(3, 500*time.Millisecond, 5*time.Second),
    // Other options...
)

Configure via variáveis de ambiente

Use esta abordagem para gerenciar o comportamento de retry usando variáveis de ambiente (no arquivo .env):
# Retry configuration
MIDAZ_MAX_RETRIES=3               # Maximum retry attempts for failed requests (default: 3)
MIDAZ_ENABLE_RETRIES=true         # Enable retry mechanism (default: true)
MIDAZ_RETRY_WAIT_MIN=500ms        # Minimum wait time between retries in ms (default: 1000ms)
MIDAZ_RETRY_WAIT_MAX=50000ms      # Maximum wait time between retries in ms (default: 30000ms)

Explore as APIs


Para mais informações sobre as APIs, consulte os seguintes links