API Types (Golang) - AbacatePay

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.

​O que é o abacatepay/go-types?

Quando usar API Types em Go?

​Instalação

​Versionamento dos Tipos