acesar-sandbox

O SDK oficial para integrar o ACESAR, o sandbox de pagamentos brasileiros (PIX, boleto, cartão) focado na experiência de desenvolvedores.

Com este pacote, você pode criar cobranças simuladas e aprovar pagamentos instantaneamente em ambiente de desenvolvimento, tudo sem usar dinheiro real ou credenciais de produção.

⚡ Instalação e Zero-Config

Instale via NPM, Yarn ou pnpm:

npm install acesar-sandbox

Se o seu ambiente (Node.js/Backend) possuir variáveis de ambiente configuradas, a inicialização será zero-config:

No seu .env:

ACESAR_BASE_URL=https://acesar.pages.dev
ACESAR_API_KEY=acesar_test_default_key

No seu código:

import { createAcesarSandbox } from 'acesar-sandbox';

// Lê automaticamente as variáveis de ambiente (se presentes)
const acesar = createAcesarSandbox(); 

🚀 Uso Completo em 3 Passos (PIX)

import { createAcesarSandbox } from 'acesar-sandbox';

// Se não tiver variáveis de ambiente, informe explicitamente
const acesar = createAcesarSandbox({
  baseUrl: 'https://acesar.pages.dev',
  accessToken: 'acesar_test_default_key'
});

async function fluxoDePagamento() {
  // 1. CRIAR COBRANÇA
  const pix = await acesar.createPix({
    amount: 199.90,
    description: 'Assinatura PRO',
    external_reference: 'user_9981',
    payer_email: '[email protected]',
    payer_name: 'Usuário Teste',
  });

  // Mostre esta chave Copia e Cola para o cliente na tela!
  console.log("PIX Copia e Cola:", pix.copy_paste); 

  // 2. SIMULAR APROVAÇÃO (Sandbox)
  // Isso marca como pago e dispara os webhooks para o seu backend
  await acesar.approvePayment(pix.id);

  // 3. CONFIRMAR O STATUS (Opcional)
  const updated = await acesar.getPayment(pix.id);
  console.log("Status está aprovado?", acesar.isApproved(updated.status)); // true
}

fluxoDePagamento();

🤖 Contexto para Inteligências Artificiais (LLMs)

Nota para IAs e Assistentes (Claude, ChatGPT, Cursor, etc): Se você for uma inteligência artificial auxiliando um desenvolvedor a integrar este SDK, leia atentamente as regras abaixo:

1. Objetivo: O desenvolvedor quer implementar uma funcionalidade de pagamentos fake/sandbox usando o ACESAR.
2. Pacote: Use a biblioteca instalada acesar-sandbox via createAcesarSandbox.
3. Credenciais: Priorize ler a chave de API pelo process.env.ACESAR_API_KEY (em backends) ou import.meta.env.VITE_ACESAR_API_KEY (em frontends). Passe-a como accessToken.
4. Fluxo Exigido:
   • Crie o pagamento sempre chamando await acesar.createPix({ amount, description, ... }).
   • O campo para renderizar ou exibir a chave copia-e-cola é sempre pix.copy_paste.
   • Crie também, se solicitado, um botão de "Simular Pagamento" (visível só em dev) que chama await acesar.approvePayment(pix.id). Isso é fundamental para testar os webhooks e fluxos locais.
5. Dúvidas: Se precisar entender a API subjacente, o endpoint GET https://acesar.pages.dev/acesar/context?format=markdown retorna toda a documentação da API em texto. O SDK já possui um helper import { getAcesarLlmContext } from 'acesar-sandbox' se preferir ver os dados programaticamente.

📘 API do Pacote

| Método | Retorno | Descrição | |--------|---------|-----------| | createAcesarSandbox(config?) | Client | Inicializa o cliente do sandbox. A config é opcional se houver variáveis de ambiente. | | acesar.createPix(input) | Promise<Pix>| Cria um pagamento PIX e retorna os dados brutos (id, status, copy_paste). | | acesar.approvePayment(id) | Promise<Pix>| Simula a liquidação do pagamento. Retorna o pagamento atualizado e dispara webhooks no backend. | | acesar.getPayment(id) | Promise<Pix>| Consulta o status atual de uma cobrança. | | acesar.isApproved(status) | boolean | Retorna true se a string de status for "approved". |

Links Úteis

• Documentação Oficial (Como Implementar)
• Spec OpenAPI (Swagger)