Skip to main content

​
O que é o @abacatepay/rest?

O @abacatepay/rest é um cliente REST leve, rápido e totalmente tipado para consumir a API da AbacatePay diretamente, sem abstrações pesadas. Ele foi projetado para Node.js, Bun e runtimes modernos, oferecendo controle total sobre as requisições, com retries inteligentes, backoff automático, timeouts configuráveis e tratamento de erros consistente.

Quando usar o REST Client?

  • Você quer controle total sobre endpoints e payloads
  • Está criando SDKs, CLIs ou ferramentas internas
  • Prefere uma camada fina sobre HTTP em vez de abstrações de alto nível
  • Precisa de performance e previsibilidade

​
Instalação

Use o package manager da sua preferência: 
bun add @abacatepay/rest
# ou
pnpm add @abacatepay/rest
# ou
npm install @abacatepay/rest

​
Uso Básico

Exemplo simulando um pagamento Pix via QR Code: 
import { REST } from '@abacatepay/rest';

const client = new REST({
    secret: process.env.ABACATEPAY_API_KEY!,
});

const pix = await client.post('/transparents/simulate-payment', {
    query: {
        id: 'pix_char_123456'
    },
});

console.log(pix);

​
Versionando para usar a API v1

import { REST } from '@abacatepay/rest';

const client = new REST({
    version: 1,
});

const { status, expiresAt } = await client.get('/pixQrCode/check', {
    query: {
        id,
    },
});

console.log(status, expiresAt);
Ou você pode configurar a versão em rotas específicas via version 
await client.post('/coupons/delete', {
    query: {
        id,
    },
    version: 2,
});
Sem abstrações, sem plugins, sem boilerplate, apenas REST.

​
Performance & Design

O @abacatepay/rest foi desenhado para ser:
  • Zero dependências
  • Compatível com fetch nativo
  • Rápido por padrão
  • Seguro por padrão

Tipagem forte

Tipos completos para respostas, erros e configurações.

Runtimes modernos

Funciona perfeitamente em Node.js, Bun e ambientes modernos.

​
Custom-Fetch

Você também pode configurar o seu próprio fetch para requisições: 
const client = new REST({
    async fetch(route, options) {
        // ...

        return new Response(...);
    },
});
O valor retornado deve ser sempre um objeto Response, caso o contrário, um erro será lançado.

​
Retry & Backoff

Por padrão, o REST Client faz 3 tentativas automáticas para erros retryable, como:
  • Rate limit (429)
  • Erros 5xx
  • Falhas de rede
const client = new REST({
    retry: {
        max: 5,
        onRetry({ options, attempt, response }) {
            console.log(`Retrying ${response.url} (${options.method})...`);
        },
    },
});

​
Backoff customizado

const client = new REST({
    retry: {
        max: 7,
        backoff(attempt) {
            return Math.min(10_000, 500 * 2 ** attempt);
        },
    },
});
Se nenhum backoff for definido, o client usa backoff exponencial com jitter automaticamente.

​
Rate Limit

Você também pode controlar completamente com o hook onRateLimit quando um rate-limit ocorre: 
const client = new REST({
    async onRateLimit(response) {
        ...
    },
});

​
Configurações Avançadas

Você pode customizar completamente o comportamento do client:
  • Timeout por request
  • Headers globais
  • Retry e backoff
  • Versionamento automático
  • Base URL (sandbox / production)
  • Hooks internos (request / response)

Flexível por design

O REST Client não impõe padrões — ele se adapta à sua arquitetura.

​
REST Client vs SDKs

REST Client

Camada fina, controle total, ideal para libs, CLIs e integrações avançadas.

SDKs

Abstrações de alto nível para integração rápida com menos código.

​
Próximos Passos

Documentação Completa

Veja todos os endpoints, opções e exemplos avançados.

NPM Package

Acesse o pacote no NPM e histórico de versões.

Open Source de verdade

O @abacatepay/rest é open source e mantido pela equipe AbacatePay. Contribuições são bem-vindas.