# Atlas API Documentation

> LLM-friendly documentation for the Atlas PIX payment API.

## Overview

Atlas API is a REST API for accepting PIX payments in Brazil and converting to DEPIX (tokenized BRL on Liquid Network).
Base URL: https://api.atlasdao.info/api/v1

Key capabilities:
- Create PIX payment QR codes
- Track transaction status in real-time
- Receive webhook notifications
- Manage reusable payment links
- View usage statistics

## Authentication

All endpoints (except GET /external/health) require authentication via API Key.
Include the header `X-API-Key: <your_api_key>` in every request.

API Keys have the prefix `atlas_` followed by a 64-character hex string.
Example: `atlas_943cb2cc2421eac94e7ac5e59a5a8f88f4080de4402b6381c5c4e5598260bda2`

### How to get an API Key

1. Create an account at https://painel.atlasdao.info/register
2. Enable Commerce Mode in Settings
3. Go to Settings > API (https://painel.atlasdao.info/settings) and generate your key

## Rate Limits

- 100 requests per minute per API Key
- 10,000 requests per day per API Key
- Exceeding the limit returns HTTP 429

## Error Response Format

All errors follow this structure:
```json
{
  "statusCode": 400,
  "message": "Description of what went wrong",
  "error": "Bad Request"
}
```

For validation errors, `message` may be an array of validation messages.

## Transaction Statuses

- `PENDING` - Transaction created, awaiting PIX payment
- `COMPLETED` - Payment confirmed and processed
- `FAILED` - Payment processing failed
- `EXPIRED` - QR Code expired without payment (typically 30 minutes)
- `CANCELLED` - Transaction cancelled by the user via API

## Endpoints

### GET /external/health

Verifica se a API esta online e funcionando. Este endpoint e publico e nao requer autenticacao.
**Public endpoint** - no authentication required.

**Response Example:**
```json
{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "version": "1.0.0",
  "service": "Atlas External API"
}
```

**Status Codes:**
- 200: API esta online e funcionando

---

### GET /external/profile

Retorna as informacoes do usuario autenticado pela API Key.

**Response Example:**
```json
{
  "id": "usr_abc123",
  "username": "minha_loja",
  "email": "contato@minhaloja.com",
  "commerceMode": true,
  "paymentLinksEnabled": true,
  "isAccountValidated": true,
  "createdAt": "2025-01-01T00:00:00.000Z"
}
```

**Status Codes:**
- 200: Perfil retornado com sucesso
- 401: API Key invalida ou ausente

---

### POST /external/pix/create

Cria uma nova transacao PIX com QR Code para pagamento. Opcionalmente, configure um webhook para receber notificacoes sobre o status da transacao.

**Request Body (JSON):**
- `amount` (number, required): Valor da transacao em BRL (minimo: 0.01) (e.g. `99.90`)
- `depixAddress` (string, required): Endereco da wallet DEPIX para receber os fundos (e.g. `lq1qq...`)
- `description` (string, optional): Descricao da transacao (max 200 caracteres) (e.g. `Pagamento pedido #123`)
- `taxNumber` (string, optional): CPF/CNPJ do pagador. Obrigatorio para valores >= R$ 3.000 (e.g. `123.456.789-01`)
- `merchantOrderId` (string, optional): ID do pedido no seu sistema (max 100 caracteres) (e.g. `ORD-2025-12345`)
- `metadata` (object, optional): Metadados adicionais para armazenar com a transacao (e.g. `{"customerId": "123"}`)
- `webhook` (WebhookConfig, optional): Configuracao do webhook (ver secao Webhooks) (e.g. `{ url, events, secret?, headers? }`)

**Response Example:**
```json
{
  "id": "txn_abc123def456",
  "status": "PENDING",
  "amount": 99.9,
  "description": "Pagamento pedido #123",
  "merchantOrderId": "ORD-2025-12345",
  "qrCode": "00020126580014br.gov.bcb.pix0136...",
  "qrCodeImage": "data:image/png;base64,...",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "expiresAt": "2025-01-15T11:00:00.000Z",
  "webhook": {
    "id": "wh_xyz789",
    "url": "https://meusite.com/webhook",
    "events": [
      "transaction.paid"
    ],
    "secretHint": "minh"
  }
}
```

**Status Codes:**
- 201: Transacao criada com sucesso
- 400: Dados invalidos (amount <= 0, taxNumber ausente para >= R$3000)
- 401: API Key invalida ou ausente
- 403: Permissao negada - verifique as permissoes da API Key

---

### GET /external/pix/status/:id

Consulta o status atual de uma transacao PIX pelo seu ID.

**Path Parameters:**
- `id` (string, required): ID da transacao (e.g. `txn_abc123def456`)

**Response Example:**
```json
{
  "id": "txn_abc123def456",
  "status": "COMPLETED",
  "type": "DEPOSIT",
  "amount": 99.9,
  "description": "Pagamento pedido #123",
  "processedAt": "2025-01-15T10:35:00.000Z",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:35:00.000Z",
  "merchantOrderId": "ORD-2025-12345",
  "expiresAt": "2025-01-15T11:00:00.000Z",
  "metadata": {
    "source": "EXTERNAL_API",
    "merchantOrderId": "ORD-2025-12345"
  }
}
```

**Status Codes:**
- 200: Detalhes da transacao retornados
- 401: API Key invalida ou ausente
- 404: Transacao nao encontrada

---

### GET /external/pix/transactions

Lista todas as transacoes PIX do usuario com filtros e paginacao.

**Query Parameters:**
- `status` (string, optional): Filtrar por status (PENDING, COMPLETED, FAILED, EXPIRED, CANCELLED) (e.g. `COMPLETED`)
- `type` (string, optional): Filtrar por tipo de transacao (e.g. `PIX`)
- `startDate` (string, optional): Data inicial (ISO 8601) (e.g. `2025-01-01T00:00:00Z`)
- `endDate` (string, optional): Data final (ISO 8601) (e.g. `2025-01-31T23:59:59Z`)
- `merchantOrderId` (string, optional): Filtrar por ID do pedido (e.g. `ORD-2025-12345`)
- `page` (number, optional): Numero da pagina (padrao: 1) (e.g. `1`)
- `limit` (number, optional): Itens por pagina (padrao: 20, max: 100) (e.g. `20`)

**Response Example:**
```json
{
  "data": [
    {
      "id": "txn_abc123",
      "status": "COMPLETED",
      "type": "DEPOSIT",
      "amount": 99.9,
      "description": "Pagamento pedido #123",
      "pixKey": "lq1qq...",
      "processedAt": "2025-01-15T10:35:00.000Z",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:35:00.000Z",
      "merchantOrderId": "ORD-2025-12345",
      "expiresAt": "2025-01-15T11:00:00.000Z",
      "metadata": {
        "source": "EXTERNAL_API",
        "merchantOrderId": "ORD-2025-12345"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}
```

**Status Codes:**
- 200: Lista de transacoes retornada
- 401: API Key invalida ou ausente

---

### DELETE /external/pix/cancel/:id

Cancela uma transacao PIX pendente. Somente transacoes com status PENDING podem ser canceladas.

**Path Parameters:**
- `id` (string, required): ID da transacao a cancelar (e.g. `txn_abc123def456`)

**Response Example:**
```json
{
  "id": "txn_abc123def456",
  "status": "CANCELLED",
  "message": "Transaction cancelled successfully"
}
```

**Status Codes:**
- 200: Transacao cancelada com sucesso
- 401: API Key invalida ou ausente
- 404: Transacao nao encontrada ou ja processada

---

### POST /external/payment-links

Cria um novo link de pagamento. Links podem ter valor fixo ou permitir que o cliente escolha o valor (dentro de um range opcional).

**Request Body (JSON):**
- `title` (string, required): Titulo do link (validado pelo servidor) (e.g. `Produto Exemplo`)
- `description` (string, optional): Descricao do link (exibida na resposta) (e.g. `Descricao do produto`)
- `amount` (number, optional): Valor fixo em BRL (obrigatorio se isCustomAmount = false) (e.g. `99.90`)
- `isCustomAmount` (boolean, optional): Se true, permite valor livre (padrao: false) (e.g. `true`)
- `minAmount` (number, optional): Valor minimo para links com valor livre (e.g. `10.00`)
- `maxAmount` (number, optional): Valor maximo para links com valor livre (e.g. `500.00`)
- `walletAddress` (string, required): Endereco da wallet para recebimento (ou depixAddress) (e.g. `lq1qq...`)

**Response Example:**
```json
{
  "id": "0c95a1a8-3be9-4f15-a8c5-0320ecbdc376",
  "shortCode": "8v6ZOWBH",
  "amount": 99.9,
  "isCustomAmount": false,
  "minAmount": null,
  "maxAmount": null,
  "description": "Descricao do produto",
  "isActive": true,
  "expiresAt": null,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "paymentUrl": "https://painel.atlasdao.info/pay/8v6ZOWBH"
}
```

**Status Codes:**
- 201: Link criado com sucesso
- 400: Dados invalidos (titulo ausente, amount invalido)
- 401: API Key invalida ou ausente
- 403: Links de pagamento nao habilitados para este usuario

---

### GET /external/payment-links

Lista todos os links de pagamento do usuario com filtros e paginacao.

**Query Parameters:**
- `isActive` (boolean, optional): Filtrar por status ativo/inativo (e.g. `true`)
- `page` (number, optional): Numero da pagina (padrao: 1) (e.g. `1`)
- `limit` (number, optional): Itens por pagina (padrao: 20, max: 100) (e.g. `20`)

**Response Example:**
```json
{
  "data": [
    {
      "id": "0c95a1a8-3be9-4f15-a8c5-0320ecbdc376",
      "shortCode": "8v6ZOWBH",
      "description": "Descricao do produto",
      "amount": 99.9,
      "isCustomAmount": false,
      "minAmount": null,
      "maxAmount": null,
      "totalPayments": 12,
      "totalAmount": 1198.8,
      "isActive": true,
      "expiresAt": null,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "currentUses": 12,
      "paymentUrl": "https://painel.atlasdao.info/pay/8v6ZOWBH"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}
```

**Status Codes:**
- 200: Lista de links retornada
- 401: API Key invalida ou ausente

---

### GET /external/payment-links/:id

Retorna os detalhes completos de um link de pagamento especifico.

**Path Parameters:**
- `id` (string, required): ID do link de pagamento (e.g. `0c95a1a8-3be9-4f15-a8c5-0320ecbdc376`)

**Response Example:**
```json
{
  "id": "0c95a1a8-3be9-4f15-a8c5-0320ecbdc376",
  "shortCode": "8v6ZOWBH",
  "description": "Descricao do produto",
  "amount": 99.9,
  "isCustomAmount": false,
  "minAmount": null,
  "maxAmount": null,
  "currentUses": 12,
  "totalAmount": 1198.8,
  "isActive": true,
  "expiresAt": null,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "paymentUrl": "https://painel.atlasdao.info/pay/8v6ZOWBH"
}
```

**Status Codes:**
- 200: Detalhes do link retornados
- 401: API Key invalida ou ausente
- 404: Link nao encontrado

---

### GET /external/stats/usage

Retorna estatisticas de uso da API do usuario para um periodo especificado.

**Query Parameters:**
- `days` (number, optional): Numero de dias para incluir (padrao: 30, max: 90) (e.g. `30`)

**Response Example:**
```json
{
  "period": {
    "start": "2025-01-01T00:00:00.000Z",
    "end": "2025-01-31T23:59:59.000Z",
    "days": 30
  },
  "summary": {
    "totalRequests": 1240,
    "successfulRequests": 1235,
    "errorRate": "0.40%",
    "transactionsCreated": 156,
    "paymentLinksCreated": 12
  },
  "dailyUsage": {
    "2025-01-29": 45,
    "2025-01-30": 52,
    "2025-01-31": 38
  },
  "limits": {
    "requestsPerMinute": 100,
    "requestsPerDay": 10000,
    "usageType": "MULTIPLE_CPF"
  }
}
```

**Status Codes:**
- 200: Estatisticas retornadas com sucesso
- 401: API Key invalida ou ausente

---

## Webhooks

Webhooks are configured inline when creating a PIX transaction (POST /external/pix/create), via the `webhook` field.

### Webhook Configuration Fields
- `url` (string, required): URL to receive notifications (HTTPS in production)
- `events` (string[], required): Events to subscribe to
- `secret` (string, optional): HMAC secret (min 16 chars). Auto-generated if omitted
- `headers` (object, optional): Custom headers to send with webhook

### Webhook Headers

- `Content-Type`: Tipo de conteudo do payload
- `X-Atlas-Event`: Nome do evento disparado
- `X-Atlas-Webhook-Id`: ID do webhook configurado
- `X-Atlas-Signature`: Assinatura HMAC-SHA256 para verificacao

### Webhook Events

#### transaction.created

Disparado quando uma transacao PIX e criada e o QR Code esta disponivel para pagamento.

```json
{
  "event": "transaction.created",
  "data": {
    "transactionId": "txn_abc123def456",
    "status": "PENDING",
    "amount": 99.9,
    "merchantOrderId": "ORD-2025-12345",
    "qrCode": "00020126580014br.gov.bcb.pix0136...",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "expiresAt": "2025-01-15T11:00:00.000Z"
  },
  "timestamp": "2025-01-15T10:30:01.000Z",
  "webhookId": "wh_xyz789"
}
```

#### transaction.paid

Disparado quando o pagamento PIX e confirmado. Inclui informacoes de settlement (D+0 ou D+1).

```json
{
  "event": "transaction.paid",
  "data": {
    "transactionId": "txn_abc123def456",
    "status": "COMPLETED",
    "amount": 99.9,
    "merchantOrderId": "ORD-2025-12345",
    "paidAt": "2025-01-15T10:35:00.000Z",
    "payerInfo": {
      "name": "Joao Silva",
      "taxNumber": "***456789**"
    },
    "settlement": {
      "type": "instant",
      "scheduledAt": null
    },
    "metadata": null
  },
  "timestamp": "2025-01-15T10:35:01.000Z",
  "webhookId": "wh_xyz789"
}
```

#### transaction.failed

Disparado quando o processamento de uma transacao falha.

```json
{
  "event": "transaction.failed",
  "data": {
    "transactionId": "txn_abc123def456",
    "status": "FAILED",
    "failedAt": "2025-01-15T10:40:00.000Z",
    "reason": "Transaction processing failed",
    "metadata": null
  },
  "timestamp": "2025-01-15T10:40:01.000Z",
  "webhookId": "wh_xyz789"
}
```

#### transaction.expired

Disparado quando o QR Code PIX expira sem ser pago (geralmente 30 minutos).

```json
{
  "event": "transaction.expired",
  "data": {
    "transactionId": "txn_abc123def456",
    "status": "EXPIRED",
    "expiredAt": "2025-01-15T11:00:00.000Z",
    "amount": 99.9,
    "merchantOrderId": "ORD-2025-12345"
  },
  "timestamp": "2025-01-15T11:00:01.000Z",
  "webhookId": "wh_xyz789"
}
```

#### transaction.refunded

Disparado quando uma transacao e reembolsada ao pagador.

```json
{
  "event": "transaction.refunded",
  "data": {
    "transactionId": "txn_abc123def456",
    "status": "REFUNDED",
    "refundedAt": "2025-01-16T14:00:00.000Z",
    "amount": 99.9,
    "merchantOrderId": "ORD-2025-12345"
  },
  "timestamp": "2025-01-16T14:00:01.000Z",
  "webhookId": "wh_xyz789"
}
```

### HMAC Signature Verification

The `X-Atlas-Signature` header contains `sha256=<hmac_hex>`.
Compute HMAC-SHA256 of the raw request body using your webhook secret and compare.

### Webhook Delivery Details

- Timeout: 15 seconds per delivery attempt
- Retry: 1 retry after 60 seconds on failure
- A response with HTTP status 2xx is considered successful
- Non-2xx responses are logged as failed deliveries
- Webhook URLs must use HTTPS in production
- Private/localhost URLs are blocked in production

## HTTP Status Codes

- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized (invalid/missing API Key)
- 403: Forbidden
- 404: Not Found
- 409: Conflict
- 429: Rate Limit Exceeded
- 500: Internal Server Error

## Links

- Human docs: https://painel.atlasdao.info/devs
- Status page: https://painel.atlasdao.info/status
- Create account: https://painel.atlasdao.info/register