> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# REST
> REST client ergonômico, rápido e totalmente tipado para a API da AbacatePay.
## O que é o @abacatepay/rest?
O [@abacatepay/rest](https://www.npmjs.com/package/@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**.
* 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:
```bash theme={null}
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:
```ts theme={null}
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
```ts theme={null}
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`
```ts theme={null}
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
Tipos completos para respostas, erros e configurações. Funciona perfeitamente em **Node.js**, **Bun** e ambientes modernos.
## Custom-Fetch
Você também pode configurar o seu próprio `fetch` para requisições:
```ts theme={null}
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
```ts theme={null}
const client = new REST({
retry: {
max: 5,
onRetry({ options, attempt, response }) {
console.log(`Retrying ${response.url} (${options.method})...`);
},
},
});
```
### Backoff customizado
```ts theme={null}
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:
```ts theme={null}
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)
O REST Client não impõe padrões — ele se adapta à sua arquitetura.
### REST Client vs SDKs
Camada fina, controle total, ideal para libs, CLIs e integrações avançadas. Abstrações de alto nível para integração rápida com menos código.
### Próximos Passos
Veja todos os endpoints, opções e exemplos avançados. Acesse o pacote no NPM e histórico de versões. O @abacatepay/rest é open source e mantido pela equipe AbacatePay. Contribuições são bem-vindas.