SDK Go

Use o módulo github.com/raimshq/raims-go no backend da integração. O SDK oferece serviços por recurso, parâmetros e respostas tipados, paginação por cursor e autenticação de webhooks.

Instalar o pacote

O SDK requer Go 1.26.5 ou superior. No projeto que contém o go.mod:

go get github.com/raimshq/raims-go@latest

O Go resolve a versão estável mais recente do módulo e registra a dependência na aplicação. Mantenha go.mod e go.sum junto do projeto.

Configurar o cliente

Obtenha uma chave em Chaves de API e guarde-a no cofre ou em uma variável de ambiente protegida da aplicação. Mantenha a credencial no backend, fora do navegador, de aplicações distribuídas aos seus clientes e dos logs.

Empresa, ambiente e permissões são determinados pela chave validada na API. Sandbox e Produção usam https://api.raims.com.

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    raims "github.com/raimshq/raims-go"
)

func main() {
    client, err := raims.NewClient(os.Getenv("RAIMS_API_KEY"),
        raims.WithMaxNetworkRetries(0),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer client.CloseIdleConnections()

    page, err := client.Customers.List(context.Background(), &raims.ListCustomersParams{
        PageSize: raims.Set[int64](20),
    })
    if err != nil {
        log.Fatal(err)
    }
    for _, customer := range page.List {
        fmt.Println(customer.ID)
    }
}

Reutilize o cliente entre requisições e goroutines. context.Context permite cancelar chamadas e limitar sua duração. Encerre conexões ociosas ao finalizar o uso. Os próximos trechos consideram client configurado e um contexto ctx da aplicação.

Criar um cliente e uma cobrança

customerTaxID é o CPF ou CNPJ válido do cliente autorizado. customerIdempotencyKey e chargeIdempotencyKey são chaves distintas criadas e persistidas antes das requisições. chargeDueDate é um int64 com o vencimento escolhido e persistido, em segundos Unix UTC. O trecho abaixo pertence a uma função que retorna error.

customer, err := client.Customers.Create(ctx, &raims.CreateCustomerParams{
    TaxID: raims.Set(customerTaxID),
}, raims.WithIdempotencyKey(customerIdempotencyKey))
if err != nil {
    return err
}

charge, err := client.Charges.Create(ctx, &raims.CreateChargeParams{
    CustomerID:  raims.Set(customer.ID),
    AmountCents: raims.Set[int64](15000),
    DueDate:     raims.Set(chargeDueDate),
    Title:       raims.Set("Pedido 1234"),
}, raims.WithIdempotencyKey(chargeIdempotencyKey))
if err != nil {
    return err
}
fmt.Println(charge.LastResponse.StatusCode, charge.LastResponse.RequestID)

Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro é atualizado e mantém seu identificador. 15000 representa R$ 150,00. Preserve a chave e todos os parâmetros, inclusive o vencimento, ao recuperar a mesma intenção após perder uma resposta. Consulte Criar cobrança.

Optional[T] preserva a diferença entre omitir um campo, enviar um valor com Set e enviar null com Null[T](). Consulte o contrato do campo antes de limpar um valor.

Paginação e resultados pendentes

List busca uma página, disponível em page.List. NextPage(ctx) e PreviousPage(ctx) preservam filtros e retornam nil quando não há continuação. ListAll avança conforme o consumo; interromper o loop impede novas buscas. processCustomer representa o tratamento da aplicação.

for customer, err := range client.Customers.ListAll(ctx, nil).All() {
    if err != nil {
        return err
    }
    processCustomer(customer.ID)
}

Copie os cursores recebidos e mantenha os filtros; não envie after e before juntos. Consulte Listagem e paginação.

Uma resposta HTTP 202 indica resultado pendente. Ela não confirma pagamento nem conclusão financeira e não inicia consultas automáticas. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar o efeito na aplicação.

Idempotência e erros

Use errors.As para identificar *raims.APIError e decida pelo StatusCode e Code. Response.RequestID identifica a tentativa quando há resposta. ConnectionError indica falha de transporte e pode deixar uma escrita inconclusiva. WithMaxNetworkRetries configura retries somente de GET; o padrão é zero.

O SDK envia a chave de idempotência somente quando a aplicação a informa em um endpoint que aceita Idempotency-Key. Ele não gera chaves nem repete escritas automaticamente. Um timeout não prova que a escrita foi recusada.

Decida pelo status HTTP e pelo código estruturado; error.message é um diagnóstico humano que pode mudar. Não registre respostas completas, credenciais, documentos pessoais ou links temporários. Veja Idempotência e o guia de erros do SDK.

Usar o Sandbox

Use uma chave Sandbox para as simulações em client.Simulations.Charges e client.Simulations.Refunds. Uma chave de Produção não se transforma em Sandbox por usar esses serviços. Confira as condições na referência de Simulações.

Requisições que solicitam e-mail ou entregas de webhook podem alcançar destinos externos mesmo em Sandbox. Use somente destinos autorizados para a integração.

Receber webhooks

rawBody contém os bytes recebidos e headers contém os headers HTTP originais. O helper retorna o evento autenticado ou um erro; não processe o corpo se a autenticação falhar.

import (
    "encoding/json"
    "net/http"
    "time"

    raims "github.com/raimshq/raims-go"
)

func authenticateDelivery(rawBody []byte, headers http.Header, webhookSecret string) (map[string]json.RawMessage, error) {
    return raims.ConstructWebhookEvent(rawBody, headers, webhookSecret,
        raims.DefaultWebhookTolerance, time.Now())
}

Use o secret_key retornado ao criar ou rotacionar o webhook, diferente da chave Bearer da API. Leia o corpo antes do parser JSON e preserve seus bytes: não reserialize o conteúdo antes de autenticar.

Depois da autenticação, confira tipo e ambiente, deduplique pelo id do evento e grave o trabalho de forma durável antes de responder com sucesso. O header webhook-id identifica a entrega, não o evento. Consulte Receber eventos.

Atualizar o SDK

Execute novamente go get github.com/raimshq/raims-go@latest no projeto. Revise as releases e os arquivos go.mod e go.sum, e teste os fluxos usados pela aplicação antes de implantar a atualização.

A versão do SDK é independente da versão HTTP /v1 da API. Os guias completos e a referência de métodos estão no repositório do SDK.