Pular para o conteúdo principal
O SDK do Midaz para Go é o cliente Go para as APIs do ledger e do Tracer do Midaz. Ele oferece acesso tipado a cada serviço (Organizations, Ledgers, Accounts, Transactions e mais) com uma única superfície para autenticação, paginação, erros, novas tentativas, logging e observabilidade.

Primeiros passos


Passo 1 – Instalar o Go

Instale o Go antes de usar o SDK. O SDK declara Go 1.26 no go.mod. A API pública dele usa iter.Seq2 e log/slog.
2
Baixe o instalador para o seu sistema operacional (Windows, macOS ou Linux).

Passo 2 – Criar ou usar um projeto Go existente

Criar um projeto Go: Para criar um projeto Go, use o comando a seguir:
Usar um projeto Go existente: Se você já está trabalhando em um projeto existente, confirme que há um arquivo go.mod na raiz. Caso não haja, execute o comando a seguir para criar um:

Passo 3 – Adicionar o SDK do Midaz

Dentro do diretório do seu projeto, execute o comando a seguir para adicionar o SDK aos arquivos go.mod e go.sum:
O caminho do módulo exige o sufixo /v6. Se você omitir esse sufixo, o Go resolve uma versão v1 antiga. Importe github.com/LerianStudio/midaz-sdk-golang/v6.
No VS Code ou no GoLand, sua IDE pode executar go get automaticamente quando você importa um pacote novo.

Passo 4 – Importar o SDK

Crie ou abra um arquivo main.go e adicione o conteúdo a seguir. O exemplo cria um cliente para a sua stack local do Midaz com autenticação anônima, lista organizações e, em seguida, cria uma nova.
O exemplo abaixo é para uma stack local do Midaz com autenticação desabilitada. Se você ainda não tem uma rodando, veja Primeiros passos com o Midaz para subir uma antes de executar o snippet.
Isso oferece acesso a:
  • O cliente do Midaz para chamar cada serviço da API.
  • Modelos de dados prontos (como CreateOrganizationInput).
  • Autenticação via Access Manager (produção) ou Anônimo (desenvolvimento local).
  • Um sistema de configuração tipado que falha no momento da construção.
Para a configuração completa, veja a seção Autenticação.

Passo 5 – Executar o projeto

Execute o comando a seguir:

Arquitetura do SDK


Design em camadas

Services

O Midaz atende duas versões da API do ledger: /v1, que está descontinuada, e /v2. O SDK agrupa os serviços do ledger pela versão que os atende. Desenvolva sobre c.V2. Um recurso que uma versão não atende gera erro de compilação, não um 404.
Transactions tem um contrato diferente em cada versão. Na /v1, você cria uma transação por um de quatro endpoints de criação com um body send aninhado. Na /v2, c.V2.Transactions cria transações com um body plano por meio de CreateDirect, CreateHold, CreateBlock e CreateUnblock. Ele retorna models.TransactionV2.
Uma resposta 201 significa que o Midaz aplicou a transação aos saldos.

Models

Cada tipo de modelo representa um conceito de negócio. Você os usa em cada chamada de serviço. Os tipos de modelo mais comuns são reexportados no pacote midaz. midaz.Account e models.Account são o mesmo tipo, então a maior parte do código precisa de apenas um import.

Tipos de modelo comuns

Para um tipo que não é reexportado, como models.TransactionV2, importe github.com/LerianStudio/midaz-sdk-golang/v6/models diretamente. Os aliases de midaz preservam a identidade do tipo, então os dois caminhos de import funcionam juntos.

Utility packages

A pasta pkg do SDK guarda pacotes utilitários. Os pacotes Core atendem preocupações que valem para todo o SDK. Os pacotes Helper oferecem utilitários específicos de domínio ou de baixo nível.

Core packages

Helper packages

Autenticação


O SDK exige exatamente uma fonte de autenticação no momento da construção. Se você chamar midaz.New(...) sem nenhuma das duas, ele retorna um erro de configuração tipado. Você tem duas opções:
  • midaz.WithAccessManager(...): OAuth pelo Lerian Access Manager. Use em qualquer stack que não seja local.
  • midaz.WithAnonymous(): sem autenticação. Use apenas em uma stack local do Midaz com autenticação desabilitada.
Se você aplicar as duas opções, vale a última.

Produção: Access Manager

Coloque suas credenciais do Access Manager em midaz.WithAccessManager. O SDK solicita um token ao seu Access Manager, anexa esse token a cada chamada de API e o renova quando ele expira.
Substitua os valores no bloco // Configure Access Manager pelas suas próprias credenciais antes de executar.

Desenvolvimento local: Anônimo

Para uma stack local do Midaz com autenticação desabilitada, desative a autenticação explicitamente:

Configurar via variáveis de ambiente

Você também pode apontar o SDK para o seu Access Manager com variáveis de ambiente. Exporte-as no seu shell ou no seu gerenciador de processos:
config.FromEnvironment() lê o ambiente de processo, não um arquivo .env. Se você mantém variáveis em um arquivo .env durante o desenvolvimento, carregue-as com uma biblioteca como godotenv antes de chamar config.NewConfig(config.FromEnvironment()).
Depois, habilite o carregamento por ambiente no momento da configuração:
O carregamento por ambiente é explícito. Coloque config.FromEnvironment() na cadeia de opções. Sem ele, o SDK não lê variáveis de ambiente durante a construção.
Para o passo a passo completo de autenticação, veja o guia de autenticação no repositório do SDK.

Escopo de tenant


O escopo do tenant vem do Access Manager / das claims do JWT usadas para obter o token. O SDK não tem configuração de tenant e não envia um header de tenant. Para executar chamadas em um escopo de tenant diferente, use um conjunto separado de credenciais do Access Manager, ou construa um segundo cliente com seu próprio contexto de token.

Listagem e iteração


A maioria dos endpoints de listagem vem em três métodos. Escolha o que corresponde ao seu caso de uso.

Opções de listagem tipadas

Cada método de listagem recebe uma struct de opções tipada. A struct incorpora uma de duas structs base, de acordo com a forma como o endpoint pagina: Alguns endpoints também expõem uma sub-struct Filters tipada. Se você definir um campo do formato errado (por exemplo, Page em um endpoint por cursor), o código não compila.
A listagem de transações não filtra por Status, AssetCode, Reference, SourceAccount, DestinationAccount ou Route. Se você definir um desses filtros em List, o SDK recusa a chamada com um erro. Count aceita Status e Route.

Iterar por cada item com All

O formato mais simples é um loop range sobre cada item em cada página. O SDK busca as páginas internamente.

Iterar envelopes de página com Pages

Quando você precisa de metadados no nível de página (para checkpointing, processamento em lote ou parar no meio de uma página), itere sobre Pages. Cada entrada é um *models.ListResponse[T] com o seu bloco Pagination.
Veja o guia de paginação no repositório do SDK para o tratamento de NextCursor e a tabela de decisão entre página e cursor.

Tratamento de erros


A camada de serviços do SDK retorna erros como *pkg/errors.Error com campos estruturados: Você pode ramificar com predicados tipados, ler campos com errors.As ou usar o método Retryable() para guiar a política de novas tentativas.

Ramificar com predicados tipados

O SDK tem um conjunto de predicados Is*, para que você identifique erros sem ler detalhes internos:

Guiar decisões de novas tentativas com Retryable()

O método Error.Retryable() deriva de Category. Use-o em vez da sua própria classificação.

Envolver erros brutos de transporte

Se você chama código HTTP de nível mais baixo fora do SDK e quer o mesmo formato de erro estruturado, use ClassifyTransportError:

Validação local: FieldErrors

A validação local de entrada retorna *pkg/validation.FieldErrors, uma coleção de erros por campo que o SDK encontra antes de qualquer chamada HTTP. Use errors.As para lê-los.
Para o mapa completo de categorias, cada código e os limites de novas tentativas, veja o guia de tratamento de erros no repositório do SDK.

Novas tentativas


A política padrão faz 3 novas tentativas com backoff exponencial e 25% de jitter. Ela tenta de novo em erros de transporte e nos status 408, 425, 429, 500, 502, 503 e 504. O SDK tenta de novo POST, PUT, PATCH e DELETE apenas quando a requisição tem um header X-Idempotency.
Use midaz.WithCustomRetryPolicy para o seu próprio predicado de novas tentativas. Para desligar as novas tentativas, use midaz.WithoutRetries().

Logging


*slog.Logger é a superfície de logger do SDK. Conecte-o com midaz.WithLogger(...). O SDK é silencioso por padrão: ele usa slog.DiscardHandler até você habilitar. Você decide o handler, o nível e o destino.
charmbracelet/log, zap e zerolog se integram por meio de slog.Handler.
O guia de logging tem receitas de adaptadores para bibliotecas de logging comuns.

Observabilidade


Um provedor de observabilidade oferece spans, métricas e logs correlacionados ao OpenTelemetry por um único ponto de conexão. Passe um provedor que você constrói, ou passe opções que o SDK monta para você.

Conectar um provedor

Ou passar opções inline

O SDK emite um span HTTP por requisição de saída com propagação W3C traceparent. Os registros de log de negócio carregam apenas IDs seguros: sem payloads, nomes, endereços ou headers de autenticação. Você também pode envolver um bloco de lógica de negócio em um span com Client.Trace:
WithObservabilityOptions e WithObservabilityProvider substituem o provedor instalado. Eles não mesclam. Para começar de uma base, coloque observability.WithDevelopmentDefaults ou observability.WithProductionDefaults primeiro na cadeia de opções.
Veja o exemplo 10-observability-otel no repositório do SDK para atributos de span, nomes de métricas e configuração de exporters.

Idempotência


A idempotência automática está ligada por padrão. O SDK envia um header X-Idempotency: <uuid> em cada requisição HTTP não segura (POST, PUT, PATCH, DELETE). Assim, uma nova tentativa depois de uma falha transitória não cria um recurso duas vezes. Você pode substituir a chave gerada por chamada quando precisa de uma chave estável própria. Isso é comum em etapas de saga, linhas de outbox ou envios de UI.

Definir uma chave estável por requisição

Suprimir a idempotência para uma chamada

Para chamadas administrativas raras, suprima o header por requisição:
Sem o header, o SDK não tenta de novo essa requisição não segura.

Desabilitar globalmente

Para desligar a idempotência automática em todos os lugares, desligue-a no nível do cliente:
Você também pode definir MIDAZ_IDEMPOTENCY=false quando usa config.FromEnvironment().

Variáveis de ambiente


O SDK lê estas variáveis apenas quando config.FromEnvironment() está na sua cadeia de opções de configuração. Para a matriz completa de opções de midaz, pkg/config e pkg/sdkctx, veja o guia de configuração no repositório do SDK.

Exemplos de projetos


O SDK tem um conjunto numerado de tutoriais focados (exemplos 01–10), além de exemplos avançados e de referência. Cada exemplo numerado ensina um conceito. Navegue por eles no diretório de exemplos no GitHub.
O repositório também inclui exemplos de referência: concurrency, configuration, context, tracing, tracing-server, pkg-validation-demo, mass-demo-generator e workflow-with-entities.

Explore as APIs


Para mais informações sobre as APIs, consulte os links a seguir:

Mapeamento de API externa

Mapeamento de API interna

Documentação do Godoc