SDK Go

O SDK oficial em Go encapsula autenticação, renovação de token, política de retry/circuit breaker e serialização, para que você chame a API do Parcele+ sem lidar diretamente com HTTP.

Código-fonte no GitHub

Repositório público — código, exemplos (samples/) e histórico de versões.

Compatibilidade

Runtime	Versões aceitas
Go	1.18 ou superior

Zero dependências externas — usa só a standard library (net/http, encoding/json, crypto/hmac). Um *Client é seguro para uso concorrente por múltiplas goroutines.

Instalação

go get github.com/Twila-Digital/twila-parcelemais-go-sdk

Configuração

import parcelemais "github.com/Twila-Digital/twila-parcelemais-go-sdk"

client, err := parcelemais.NewClient(parcelemais.ClientOptions{
    ClientID:     "<seu-client-id>",
    ClientSecret: "<seu-client-secret>",
    Environment:  parcelemais.EnvironmentStaging,
})
if err != nil {
    log.Fatal(err)
}

*Client deve ser reaproveitado como singleton na sua aplicação — ele mantém o cache do token de acesso e o estado do circuit breaker.

Uso

parcelas, err := client.Simulations.SimulateInstallments(ctx, parcelemais.SimulateInstallmentsRequest{
    RequestedAmount: 1500.0,
})
if err != nil {
    log.Fatal(err)
}

for _, parcela := range parcelas {
    fmt.Printf("%dx de %.2f (total %.2f)\n", parcela.Term, parcela.InstallmentAmount, parcela.TotalAmount)
}

O client expõe uma struct por recurso:

Cliente	Métodos
`client.Orders`	`Create`, `Get`, `List`, `StartCdcSale`, `ImportInvoice`
`client.Simulations`	`SimulateInstallments`, `SimulateValues`
`client.Customers`	`Get`, `List`
`client.Webhooks`	`Create`, `List`, `Update`, `Delete`

Orders.List(...) e Customers.List(...) retornam um *PagedResult[T] (generics) — sem auto-paginação, você controla explicitamente o avanço de página.

Tratamento de erros

Em Go, erros são valores de retorno, não exceções. O SDK define uma hierarquia de erros tipados verificável via errors.As: *ConfigurationError, *AuthenticationError, *TimeoutError, *WebhookSignatureError, e *APIError (com *ValidationError e *RateLimitError embutindo *APIError) para os demais erros de API.

var apiErr *parcelemais.APIError
order, err := client.Orders.Get(ctx, orderID)
if errors.As(err, &apiErr) {
    fmt.Printf("%d %s: %s\n", apiErr.StatusCode, apiErr.ErrorCode(), apiErr)
}

Validando assinatura de webhooks

evento, err := parcelemais.ParseWebhookEvent(rawBody, signatureHeader, signingSecret)

Exemplos completos

O repositório inclui samples prontos para rodar em samples/:

CLI

sample-cli — script sem framework.

HTTP

sample-http — *Client como singleton num servidor HTTP padrão.

Visão geral

Oficiais

Código-fonte no GitHub

Compatibilidade

Instalação

Configuração

Uso

Tratamento de erros

Validando assinatura de webhooks

Exemplos completos

CLI

HTTP

Código-fonte no GitHub

​Compatibilidade

​Instalação

​Configuração

​Uso

​Tratamento de erros

​Validando assinatura de webhooks

​Exemplos completos

CLI

HTTP

Compatibilidade

Instalação

Configuração

Uso

Tratamento de erros

Validando assinatura de webhooks

Exemplos completos