@polymorphism-tech/morph-spec 7.0.0 → 7.1.1

package/framework/standards/backend/integrations/asaas/asaas-api.md

@@ -1,216 +1,260 @@
-# Asaas API Integration Standard
-
-> **Scope:** universal
-> **Layer:** 2 (on keyword)
-> **Keywords:** asaas, payment, brazilian, pix, boleto, billing
-> **Load When:** asaas or brazilian payment keywords detected
-
-Brazilian payment gateway integration for PIX, Boleto, and credit card processing.
-
----
-
-## Overview
-
-Asaas is a Brazilian payment service provider offering:
-- PIX instant payments
-- Boleto bancário
-- Credit card processing
-- Subscription billing
-- Split payments
-
-**Stack:** .NET Backend
-
----
-
-## Core Principles
-
-1. **Webhook-First**: All payment state changes via webhooks
-2. **Idempotency**: Use idempotency keys for all POST requests
-3. **Security**: Validate webhook signatures, never store full card data
-4. **Brazil-Specific**: Handle CPF/CNPJ validation, Brazilian tax rules
-
----
-
-## API Configuration
-
-### Environment Variables
-
-```bash
-# .env.local
-ASAAS_API_KEY=your_api_key_here
-ASAAS_WEBHOOK_SECRET=your_webhook_secret
-ASAAS_ENVIRONMENT=sandbox # or production
-```
-
-### TypeScript Client Setup
-
-```typescript
-// lib/asaas/client.ts
-import { createClient } from '@asaas/node-sdk';
-
-export const asaasClient = createClient({
-  apiKey: process.env.ASAAS_API_KEY!,
-  environment: process.env.ASAAS_ENVIRONMENT as 'sandbox' | 'production'
-});
-```
-
----
-
-## Common Operations
-
-### Create PIX Payment
-
-```typescript
-// app/api/payments/pix/route.ts
-import { asaasClient } from '@/lib/asaas/client';
-
-export async function POST(req: Request) {
-  const { amount, customerId, description } = await req.json();
-
-  const payment = await asaasClient.payments.create({
-    customer: customerId,
-    billingType: 'PIX',
-    value: amount,
-    dueDate: new Date().toISOString().split('T')[0],
-    description,
-  });
-
-  return Response.json({
-    paymentId: payment.id,
-    pixCode: payment.pixTransaction.payload,
-    qrCode: payment.pixTransaction.qrCode.encodedImage
-  });
-}
-```
-
-### Webhook Handler
-
-```typescript
-// app/api/webhooks/asaas/route.ts
-import { headers } from 'next/headers';
-import crypto from 'crypto';
-
-export async function POST(req: Request) {
-  const body = await req.text();
-  const signature = headers().get('asaas-signature');
-
-  // Verify webhook signature
-  const expectedSignature = crypto
-    .createHmac('sha256', process.env.ASAAS_WEBHOOK_SECRET!)
-    .update(body)
-    .digest('hex');
-
-  if (signature !== expectedSignature) {
-    return new Response('Invalid signature', { status: 401 });
-  }
-
-  const event = JSON.parse(body);
-
-  // Handle payment events
-  switch (event.event) {
-    case 'PAYMENT_RECEIVED':
-      await handlePaymentReceived(event.payment);
-      break;
-    case 'PAYMENT_CONFIRMED':
-      await handlePaymentConfirmed(event.payment);
-      break;
-  }
-
-  return new Response('OK');
-}
-```
-
----
-
-## Database Schema (PostgreSQL / Neon)
-
-```sql
--- Store payment records
-create table payments (
-  id uuid primary key default gen_random_uuid(),
-  user_id uuid references auth.users(id),
-  asaas_payment_id text unique not null,
-  amount decimal(10,2) not null,
-  status text not null, -- pending, confirmed, received
-  billing_type text not null, -- PIX, BOLETO, CREDIT_CARD
-  created_at timestamptz default now(),
-  updated_at timestamptz default now()
-);
-
--- RLS policies
-alter table payments enable row level security;
-
-create policy "Users read own payments"
-  on payments for select
-  using (auth.user_id() = user_id);
-```
-
----
-
-## Best Practices
-
-### CPF/CNPJ Validation
-
-```typescript
-export function validateCPF(cpf: string): boolean {
-  cpf = cpf.replace(/[^\d]/g, '');
-  if (cpf.length !== 11) return false;
-
-  // Validation logic...
-  return true;
-}
-
-export function validateCNPJ(cnpj: string): boolean {
-  cnpj = cnpj.replace(/[^\d]/g, '');
-  if (cnpj.length !== 14) return false;
-
-  // Validation logic...
-  return true;
-}
-```
-
-### Idempotency Keys
-
-```typescript
-const idempotencyKey = `payment-${userId}-${Date.now()}`;
-
-const payment = await asaasClient.payments.create({
-  // ... payment data
-}, {
-  headers: {
-    'Idempotency-Key': idempotencyKey
-  }
-});
-```
-
----
-
-## Error Handling
-
-```typescript
-try {
-  const payment = await asaasClient.payments.create(data);
-} catch (error) {
-  if (error.code === 'invalid_cpf') {
-    return Response.json({ error: 'CPF inválido' }, { status: 400 });
-  }
-  if (error.code === 'insufficient_balance') {
-    return Response.json({ error: 'Saldo insuficiente' }, { status: 402 });
-  }
-
-  console.error('Asaas API error:', error);
-  return Response.json({ error: 'Erro no processamento' }, { status: 500 });
-}
-```
-
----
-
-## References
-
-- [Asaas API Documentation](https://docs.asaas.com/)
-- [Asaas Node SDK](https://github.com/asaas/asaas-node)
-- PIX Specification: Brazilian Central Bank
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# Asaas API Integration Standard
+
+> **Scope:** universal
+> **Layer:** 2 (on keyword)
+> **Keywords:** asaas, payment, brazilian, pix, boleto, billing
+> **Load When:** asaas or brazilian payment keywords detected
+
+**Verified against:** Asaas REST API v3 (no official Node SDK — direct REST). Last-verified: 2026-05-20.
+
+---
+
+Brazilian payment gateway integration for PIX, Boleto, and credit card processing.
+
+---
+
+## Overview
+
+Asaas is a Brazilian payment service provider offering:
+- PIX instant payments
+- Boleto bancário
+- Credit card processing
+- Subscription billing
+- Split payments
+
+**Stack:** .NET Backend
+
+---
+
+## Core Principles
+
+1. **Webhook-First**: All payment state changes via webhooks
+2. **Idempotency**: Use idempotency keys for all POST requests
+3. **Security**: Validate webhook signatures, never store full card data
+4. **Brazil-Specific**: Handle CPF/CNPJ validation, Brazilian tax rules
+
+---
+
+## API Configuration
+
+### Environment Variables
+
+```bash
+# .env.local
+ASAAS_API_KEY=your_api_key_here
+ASAAS_WEBHOOK_SECRET=your_webhook_secret
+ASAAS_ENVIRONMENT=sandbox # or production
+```
+
+### REST Client Setup
+
+Asaas has **no official Node SDK** — integrate against the documented REST API
+directly. The API key goes in the `access_token` header; the base URL switches
+between sandbox and production.
+
+```typescript
+// lib/asaas/client.ts
+const ASAAS_BASE_URL =
+  process.env.ASAAS_ENVIRONMENT === 'production'
+    ? 'https://api.asaas.com/v3'
+    : 'https://api-sandbox.asaas.com/v3';
+
+export async function asaasFetch<T>(
+  path: string,
+  init?: RequestInit,
+): Promise<T> {
+  const res = await fetch(`${ASAAS_BASE_URL}${path}`, {
+    ...init,
+    headers: {
+      'Content-Type': 'application/json',
+      access_token: process.env.ASAAS_API_KEY!,
+      ...init?.headers,
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`Asaas ${res.status}: ${await res.text()}`);
+  }
+  return res.json() as Promise<T>;
+}
+```
+
+---
+
+## Common Operations
+
+### Create PIX Payment
+
+```typescript
+// app/api/payments/pix/route.ts
+import { asaasFetch } from '@/lib/asaas/client';
+
+export async function POST(req: Request) {
+  const { amount, customerId, description } = await req.json();
+
+  // POST /v3/payments — billingType PIX
+  const payment = await asaasFetch<{ id: string }>('/payments', {
+    method: 'POST',
+    body: JSON.stringify({
+      customer: customerId,
+      billingType: 'PIX',
+      value: amount,
+      dueDate: new Date().toISOString().split('T')[0],
+      description,
+    }),
+  });
+
+  // GET /v3/payments/{id}/pixQrCode — PIX copy-paste payload + QR image
+  const pix = await asaasFetch<{ payload: string; encodedImage: string }>(
+    `/payments/${payment.id}/pixQrCode`,
+  );
+
+  return Response.json({
+    paymentId: payment.id,
+    pixCode: pix.payload,
+    qrCode: pix.encodedImage,
+  });
+}
+```
+
+### Webhook Handler
+
+Asaas does not HMAC-sign webhooks. Instead, every webhook request carries the
+`authToken` you configured for the webhook in the `asaas-access-token` header —
+compare it against your stored secret. The `authToken` is mandatory: a `POST
+/v3/webhooks` without one makes Asaas auto-generate a high-security token
+(32–255 chars, shown once in the response).
+
+```typescript
+// app/api/webhooks/asaas/route.ts
+import { headers } from 'next/headers';
+
+export async function POST(req: Request) {
+  const body = await req.text();
+
+  // Asaas sends the webhook's authToken in the asaas-access-token header
+  const token = headers().get('asaas-access-token');
+  if (token !== process.env.ASAAS_WEBHOOK_SECRET) {
+    return new Response('Invalid token', { status: 401 });
+  }
+
+  const event = JSON.parse(body);
+
+  // Handle payment events
+  switch (event.event) {
+    case 'PAYMENT_RECEIVED':
+      await handlePaymentReceived(event.payment);
+      break;
+    case 'PAYMENT_CONFIRMED':
+      await handlePaymentConfirmed(event.payment);
+      break;
+  }
+
+  return new Response('OK');
+}
+```
+
+---
+
+## Database Schema (PostgreSQL / Neon)
+
+```sql
+-- Store payment records
+create table payments (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid references auth.users(id),
+  asaas_payment_id text unique not null,
+  amount decimal(10,2) not null,
+  status text not null, -- pending, confirmed, received
+  billing_type text not null, -- PIX, BOLETO, CREDIT_CARD
+  created_at timestamptz default now(),
+  updated_at timestamptz default now()
+);
+
+-- RLS policies
+alter table payments enable row level security;
+
+create policy "Users read own payments"
+  on payments for select
+  using (auth.user_id() = user_id);
+```
+
+---
+
+## Best Practices
+
+### CPF/CNPJ Validation
+
+```typescript
+export function validateCPF(cpf: string): boolean {
+  cpf = cpf.replace(/[^\d]/g, '');
+  if (cpf.length !== 11) return false;
+
+  // Validation logic...
+  return true;
+}
+
+export function validateCNPJ(cnpj: string): boolean {
+  cnpj = cnpj.replace(/[^\d]/g, '');
+  if (cnpj.length !== 14) return false;
+
+  // Validation logic...
+  return true;
+}
+```
+
+### Idempotency Keys
+
+Pass a stable idempotency key in the request header so a retried POST does not
+create a duplicate charge:
+
+```typescript
+await asaasFetch('/payments', {
+  method: 'POST',
+  headers: { 'Idempotency-Key': `payment-${userId}-${requestId}` },
+  body: JSON.stringify({ /* ... payment data ... */ }),
+});
+```
+
+---
+
+## Error Handling
+
+Asaas returns failures as HTTP 400 with a JSON body shaped `{ errors: [{ code,
+description }] }`. `asaasFetch` throws on non-OK responses — catch and inspect
+the `errors[]` array:
+
+```typescript
+type AsaasError = { errors: { code: string; description: string }[] };
+
+try {
+  await asaasFetch('/payments', { method: 'POST', body: JSON.stringify(data) });
+} catch (error) {
+  // asaasFetch throws `Asaas <status>: <raw body>` — parse the body
+  const body = (error as Error).message.replace(/^Asaas \d+: /, '');
+  let parsed: AsaasError | null = null;
+  try { parsed = JSON.parse(body) as AsaasError; } catch { /* non-JSON */ }
+
+  const code = parsed?.errors?.[0]?.code;
+  if (code === 'invalid_cpfCnpj') {
+    return Response.json({ error: 'CPF/CNPJ inválido' }, { status: 400 });
+  }
+
+  console.error('Asaas API error:', body);
+  return Response.json({ error: 'Erro no processamento' }, { status: 500 });
+}
+```
+
+---
+
+## References
+
+- [Asaas API Documentation](https://docs.asaas.com/)
+- [Asaas Webhooks](https://docs.asaas.com/docs/about-webhooks)
+- PIX Specification: Brazilian Central Bank
+
+> Asaas publishes **no official Node SDK** — integrate against the REST API
+> directly. Community wrappers exist but are unofficial and vary in maintenance.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*