Skip to main content

​
O que é o abacatepay/go-types?

O pacote abacatepay-go/types fornece structs oficiais e helpers modernos para trabalhar com a API da AbacatePay em Go, de forma segura, previsível e fiel à documentação oficial. Ele serve como base para integrações diretas usando net/http, clientes HTTP próprios, CLIs, serviços backend e validações de payloads.
O pacote não adiciona campos além do que existe na documentação oficial.
Cada struct reflete fielmente a API pública da AbacatePay.

Quando usar API Types em Go?

  • Você quer contratos fortes com structs tipadas
  • Usa net/http ou um client HTTP próprio
  • Precisa de compatibilidade explícita entre versões da API
  • Quer tipar webhooks, rotas e payloads sem SDKs opinativos

​
Instalação

Use o go get normalmente: 
go get github.com/AbacatePay/go-types@latest

​
Versionamento dos Tipos

Os tipos são versionados por package, refletindo a versão da API: 
import "github.com/AbacatePay/go-types/v2"

Por que versionar por package?

Isso evita breaking changes silenciosos e permite múltiplas versões da API coexistirem no mesmo projeto.

​
Convenções de Nomenclatura

Os tipos seguem convenções claras e previsíveis: Prefixo API*
  • Estruturas gerais da API
  • Objetos retornados
  • Modelos públicos
// https://docs.abacatepay.com/pages/store/reference#estrutura
type APIStoreBalance struct {
	// Balance available for withdrawal in cents.
	Available uint64 `json:"available"`

	// Balance pending confirmation in cents.
	Pending uint64 `json:"pending"`

	// Balance blocked in disputes in cents.
	// The blocked balance represents amounts that are in dispute or under review. These amounts are not available for withdrawal until the situation is resolved.
	Blocked uint64 `json:"blocked"`
}
Prefixo REST<HTTPMethod>* Tipos usados em requisições diretas à API:
  • Body → corpo enviado na requisição
    • Ex.: RESTPostCreateNewChargeBody
  • QueryParams → parâmetros de query
    • Ex.: RESTGetCheckQRCodePixStatusQueryParams
  • Data → dados retornados
    • Ex.: RESTGetListCouponsData
Prefixo Webhook*
  • Payloads de eventos de webhook

​
Campos @unstable

Campos marcados como @unstable:
  • Ainda não possuem definição formal na documentação
  • Foram inferidos a partir de exemplos oficiais
  • Podem mudar sem aviso prévio
Eles são documentados diretamente nos comentários Go: 
// @unstable
BillingKind string `json:"kind"`

​
Quickstart

​
Criar um cupom

package main

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

	types "github.com/AbacatePay/go-types/v2"
)

func CreateCoupon(body types.RESTPostCreateCouponBody) (*types.RESTPostCreateCouponData, error) {
	url := types.APIBaseURL + types.RouteCreateCoupon

	payload, _ := json.Marshal(body)

	req, _ := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(payload))

	req.Header.Set("Authorization", "...")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)

	if err != nil {
		return nil, err
	}

	defer resp.Body.Close()

	var data types.RESTPostCreateCouponData

	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		return nil, err
	}

	return data, nil
}
  • Todas as structs e types contêm o seu respectivo json tag com o seu nome e propriedades, então você pode usar json.Marshal sem medo.

​
Integração com o Ecossistema

REST Client (Go)

Cliente HTTP oficial em Go que consome esses contratos diretamente.

SDKs & Ferramentas

SDKs, CLIs e ferramentas que reutilizam os mesmos tipos versionados.

Open Source, de verdade

O abacatepay/go-types é open source e mantido pela equipe AbacatePay. Structs estáveis, versionadas e 100% alinhadas à documentação oficial da API.