AbacatePay API Types

O @abacatepay/types fornece tipagens oficiais e helpers modernos para trabalhar com a API da AbacatePay de forma segura, previsível e alinhada à documentação oficial.

O pacote é TypeScript-first e serve como base para integrações diretas via fetch, SDKs internos, CLIs e validações em aplicações backend.

Instalação

Use o package manager da sua preferência:

bun add @abacatepay/types
# ou
pnpm add @abacatepay/types
# ou
npm install @abacatepay/types

Versionamento dos Tipos

Antes de tudo, você deve especificar a versão da API que deseja usar, adicionando /v* na importação:

import { APICustomer } from '@abacatepay/types/v2';

import { version, API_BASE_URL, API_VERSION } from '@abacatepay/types';

Como a AbacatePay API Types documenta

• Prefixo API* Representa estruturas gerais da API (Objetos retornados, modelos internos etc.).

• Prefixo Webhook* Representa payloads recebidos pelos eventos de webhook. Documentação: https://docs.abacatepay.com/pages/webhooks

• Prefixo REST<HTTPMethod>* Tipos usados em requisições diretas à API.

  • Sufixo Body → corpo enviado na requisição Ex.: RESTPostCreateNewChargeBody

  • Sufixo QueryParams → parâmetros de query Ex.: RESTGetCheckQRCodePixStatusQueryParams

  • Sufixo Data → dados retornados pela API Ex.: RESTGetListCouponsData

• O pacote NÃO adiciona tipos além do que existe na documentação oficial. Cada tipo reflete exatamente o que está documentado aqui: https://docs.abacatepay.com/pages/introduction

• Campos marcados com @unstable São campos que não têm definição formal na documentação, mas cujo tipo foi inferido com base nos exemplos oficiais. (Ex.: WebhookWithdrawDoneEvent.billing.kind)

import {
    Routes,
    type APICoupon,
    type RESTPostCreateCouponBody,
} from '@abacatepay/types/v2';
import { REST } from '@abacatepay/rest';

const client = new REST({ secret });

async function createCoupon(body: RESTPostCreateCouponBody) {
    const data = await client.post<APICoupon>(Routes.coupons.create, { body });

    return data;
}

import { WebhookEvent } from '@abacatepay/typebox/v2';
import { WebhookEventType } from '@abacatepay/types/v2';

const app = new Elysia()
	.post('/webhooks/abacatepay', ({ body: { event, data } }) => {
			switch (event) {
				case WebhookEventType.BillingPaid:
					...
				case WebhookEventType.PayoutDone:
					...
				case WebhookEventType.PayoutFailed:
					...
			}
	}, {
		body: WebhookEvent,
);

Nota, você pode fazer isso de uma maneira mais simples com @abacatepay/adapters.

Feito com 🥑 pela equipe AbacatePay Open source, de verdade.