APIXdocs

Documentação para IAs

Todo o contrato da API em um único texto, pronto para colar no ChatGPT, Claude, Cursor ou Copilot e gerar a integração.

Como usar

Copie o texto abaixo e cole no seu assistente junto do que você quer fazer, por exemplo: "implemente a cobrança PIX no meu Node.js usando esta API". Ele traz endpoints, exemplos, regras de valor e o fluxo de webhook.

Documento

Markdown

# APIX - API de Pagamentos: Documentação para Integração com IA

> Cole este documento no seu LLM (GPT, Claude, Cursor, Windsurf) para implementar a integração
> corretamente. Inclui todos os endpoints, webhooks, exemplos cURL e regras críticas.

---

## 1. VISÃO GERAL DO SISTEMA

- **Base URL:** `https://api.apix.tec.br`
- A integração é **server-to-server**: você cria a cobrança pela API e recebe o resultado por webhook.
- Os termos "payment", "transaction" e "transação" referem-se à mesma entidade.
- Pagamentos são **assíncronos** — a aprovação NÃO acontece na resposta do POST.
- Após criar o pagamento, consulte o status via **polling** ou receba via **webhook**.
- Todos os valores monetários estão em **centavos** (inteiro). Ex: R$ 99,90 = `9990`.

---

## 2. AUTENTICAÇÃO

### Rotas Públicas (sem autenticação)
```
GET  https://api.apix.tec.br/api/v1/payments/:id/status
```

### Rotas com API Key
```
POST https://api.apix.tec.br/api/v1/direct-payments
```

Header obrigatório:
```http
X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

> ⚠️ Nunca exponha a API Key em código client-side (browser/app mobile).
> Use sempre em ambiente server-side.

### Alternativa: chave assinada (par de chaves secp256k1)

Mais segura que o `X-API-Key`: o vendedor gera o par, cadastra só a chave pública no dashboard
(Integrações & APIs → Nova chave → Par de chaves) e assina cada requisição com a chave privada.
Mesmo protocolo da MagenPay. Vale para todas as rotas com API Key. **Não envie `X-API-Key` junto** (400).

```bash
openssl ecparam -name secp256k1 -genkey -noout -out priv.pem   # privada: fica só no servidor
openssl ec -in priv.pem -pubout -out pub.pem                     # pública: cadastrar no dashboard
```

Headers obrigatórios:
```http
X-Public-Key-ID: apix_pk_xxxxxxxxxxxxxxxxxxxxxxxx
X-Timestamp: 2026-09-16T12:00:00.000Z        # ISO 8601 com fuso; até 5 min de diferença do servidor
X-Nonce: <16 a 128 caracteres [A-Za-z0-9._~+/=-], único por requisição>
X-Signature: <ECDSA secp256k1 + SHA-256, DER em base64>
```

**String assinada:** `JSON.stringify({ method, path, query, body, timestamp, nonce })` — sem espaços e
NESTA ordem de chaves. `method` em maiúsculas; `path` antes do `?`; `query` depois do `?` (`""` se não houver);
`body` = string exata enviada (`""` se não houver); `timestamp` e `nonce` = valores literais dos headers.

**Regras críticas:**
1. Envie o body **exatamente** como assinado — o servidor não reserializa. Serialize uma vez e reuse a string.
2. Nonce novo a cada requisição (repetido → 401 "Nonce já utilizado"), inclusive em retentativas.
3. Outras linguagens precisam gerar os mesmos bytes do `JSON.stringify`: PHP `json_encode` com
   `JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE`; Python `json.dumps(obj, separators=(",", ":"), ensure_ascii=False)`;
   Go `json.Encoder` com `SetEscapeHTML(false)` e sem o `\n` final.
4. O IP de origem precisa estar na lista cadastrada na chave (403 fora dela). A comparação é exata:
   se o servidor sai por IPv6, cadastre o endereço IPv6 (pode cadastrar IPv4 e IPv6 na mesma chave).

**Vetor de teste:** `POST /api/v1/direct-payments`, `X-Timestamp: 2026-09-16T12:00:00.000Z`,
`X-Nonce: b7Qm4rT9xK2pLw8vZs3nYa` e body
`{"amount":990,"description":"Pedido #123","paymentMethod":"pix","customer":{"name":"João Silva","email":"joao@exemplo.com","document":"12345678909"}}`
geram uma string cujo SHA-256 (UTF-8) é `9f3623e4ed27834921b88a1209d62300133e2faec6aa74a29007c2d0b920dbac`.

```javascript
import crypto from 'crypto';
import fs from 'fs';

const PUBLIC_KEY_ID = 'apix_pk_…';
const PRIVATE_KEY = fs.readFileSync('priv.pem', 'utf8');
const url = 'https://api.apix.tec.br/api/v1/direct-payments';
const body = JSON.stringify({ amount: 990, description: 'Pedido #123', paymentMethod: 'pix',
  customer: { name: 'João Silva', email: 'joao@exemplo.com', document: '12345678909' } });

const { pathname, search } = new URL(url);
const timestamp = new Date().toISOString();
const nonce = crypto.randomBytes(16).toString('base64url');
const signedData = JSON.stringify({ method: 'POST', path: pathname, query: search.slice(1), body, timestamp, nonce });
const signature = crypto.createSign('SHA256').update(signedData).sign(PRIVATE_KEY).toString('base64');

await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Public-Key-ID': PUBLIC_KEY_ID,
    'X-Timestamp': timestamp, 'X-Nonce': nonce, 'X-Signature': signature },
  body, // exatamente a string assinada
});
```

---

## 3. CRIAR COBRANÇA

Integração server-to-server: você define o valor e a descrição da cobrança.

```
POST https://api.apix.tec.br/api/v1/direct-payments
X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
```

**cURL (PIX):**
```bash
curl -X POST "https://api.apix.tec.br/api/v1/direct-payments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "amount": 9990,
    "description": "Pedido #1234",
    "paymentMethod": "pix",
    "customer": {
      "name": "João da Silva",
      "email": "joao@email.com",
      "document": "12345678901",
      "phone": "+5511999999999",
      "birthDate": "1990-01-15"
    }
  }'
```

**cURL (Cartão de Crédito):**
```bash
curl -X POST "https://api.apix.tec.br/api/v1/direct-payments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "amount": 15000,
    "description": "Assinatura mensal",
    "paymentMethod": "credit_card",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "document": "12345678901"
    },
    "cardData": [
      {
        "cardNumber": "4111111111111111",
        "cardHolderName": "MARIA SOUZA",
        "cardExpirationDate": "12/28",
        "cardCvv": "123",
        "parcels": 1,
        "value": 15000
      }
    ]
  }'
```

**JavaScript (fetch - PIX):**
```javascript
const res = await fetch("https://api.apix.tec.br/api/v1/direct-payments", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "pk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    amount: 9990,
    description: "Pedido #1234",
    paymentMethod: "pix",
    customer: { name: "João da Silva", email: "joao@email.com", document: "12345678901" },
  }),
});
const { data } = await res.json();
```

**Campos do body:**
| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| amount | number | Sim | Valor em centavos (mínimo 1). R$ 99,90 = 9990 |
| description | string | Sim | 3 a 255 caracteres. Alguns provedores mostram este texto ao pagador |
| paymentMethod | "pix" \| "credit_card" \| "bank_slip" | Sim | Método de pagamento |
| customer.name | string | Sim | Nome completo (3–128 chars) |
| customer.email | string | Sim | E-mail do comprador |
| customer.document | string | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos), sem máscara |
| customer.phone | string | Não | Telefone no formato E.164 (+5511999999999) |
| customer.birthDate | string | Não | Formato YYYY-MM-DD |
| customer.address | object | Não | zipCode, street, number, district, city, state, complement |
| cardData | array | Condicional | Obrigatório se paymentMethod === "credit_card" |
| useTwoCards | boolean | Não | Dividir em dois cartões (cardData com exatamente 2 objetos) |

**Regras:**
1. `amount` mínimo: `1` (em centavos).
2. `description` entre 3 e 255 caracteres.
3. Se `paymentMethod === "credit_card"`, `cardData` é obrigatório.
4. `customer.document` apenas dígitos.
5. `customer.birthDate` no formato `YYYY-MM-DD`.
6. Expiração do cartão no formato `MM/YY`.
7. Dados de cartão só podem trafegar do seu servidor para a APIX — nunca do navegador do comprador.

**Resposta de sucesso (201):**
```json
{
  "hasError": false,
  "data": {
    "transaction_id": "A1B2C3D4E5F6",
    "total_value": 9990,
    "status": "PENDING",
    "email": "joao@email.com",
    "payment_method": "pix",
    "payment_data": {
      "payment_id": "id-da-cobranca-no-provedor",
      "pix_key": "00020126...",
      "total_transaction_value": 9990,
      "expiration_date": "2026-09-16T18:00:00.000Z",
      "status": "pending",
      "status_detail": "waiting_payment"
    }
  }
}
```

> `payment_data.pix_key` é o PIX copia e cola: exiba como texto copiável e como QR Code.

---

## 4. CONSULTAR STATUS (POLLING)

```
GET https://api.apix.tec.br/api/v1/payments/:id/status
Auth: Pública
```

Use como plano B do webhook — o webhook continua sendo o caminho recomendado.

**cURL:**
```bash
curl -X GET "https://api.apix.tec.br/api/v1/payments/A1B2C3D4E5F6/status"
```

**JavaScript (fetch com polling):**
```javascript
const pollStatus = async (transactionId) => {
  const res = await fetch(
    `https://api.apix.tec.br/api/v1/payments/${transactionId}/status`
  );
  const { data } = await res.json();

  if (data.status === "PENDING") {
    setTimeout(() => pollStatus(transactionId), 15000); // 15s de intervalo
  } else if (data.status === "AUTHORIZED") {
    handleSuccess(data);
  } else {
    handleFailure(data.status); // REJECTED | FAILED
  }
};
```

**Resposta de sucesso (200):**
```json
{
  "hasError": false,
  "data": {
    "transaction_id": "A1B2C3D4E5F6",
    "total_value": 9990,
    "fee": 499,
    "net_value": 9491,
    "status": "AUTHORIZED",
    "payment_method": "pix",
    "payment_data": { "status": "approved", "status_detail": "accredited" }
  }
}
```

---

## 5. TABELA UNIFICADA DE STATUS

Esta tabela consolida todos os status possíveis de uma transação, eliminando qualquer ambiguidade.

| Status | Descrição | Final? | Aparece em polling? | Aparece em webhook? |
|--------|-----------|--------|---------------------|---------------------|
| `PENDING` | Aguardando pagamento ou processamento inicial | Não | Sim | Sim |
| `WAITING_PAYMENT` | Aguardando pagamento PIX ou boleto | Não | Sim | Sim |
| `IN_PROCESS` | Em processamento pelo gateway | Não | Sim | Sim |
| `AUTHORIZED` | Pagamento aprovado com sucesso | **Sim** | Sim | Sim |
| `REJECTED` | Pagamento recusado pelo processador | **Sim** | Sim | Sim |
| `FAILED` | Erro interno no processamento | **Sim** | Sim | Não |
| `REFUNDED` | Valor reembolsado ao comprador | **Sim** | Não | Sim |
| `CANCELLED` | Transação cancelada | **Sim** | Não | Sim |
| `CHARGED_BACK` | Contestação (chargeback) iniciada | **Sim** | Não | Sim |
| `CHARGEBACK` | Alias de CHARGED_BACK | **Sim** | Não | Sim |
| `IN_MEDIATION` | Disputa em processo de mediação | Não | Não | Sim |
| `IN_DISPUTE` | Alias de IN_MEDIATION (MED do PIX) | Não | Não | Sim |

**Regras para polling:**
- Pare o polling quando o status for final (`AUTHORIZED`, `REJECTED`, `FAILED`).
- Intervalo recomendado: **15 segundos**.
- `REFUNDED`, `CANCELLED`, `CHARGED_BACK` não aparecem em polling — chegam apenas via webhook.

**Regras para webhook:**
- `FAILED` não dispara webhook — detecte-o apenas via polling.
- Todos os outros status disparam pelo menos um webhook.

---

## 6. WEBHOOKS

### Como funciona
O sistema envia HTTP POST à URL configurada a cada mudança de status (evento `transaction.status_changed`).
Configure seus endpoints em /integracao (Integrações & APIs → Webhooks).

### Payload recebido
```json
{
  "transaction_id": "A1B2C3D4E5F6",
  "total_value": 99.90,
  "fee": 4.99,
  "net_value": 94.91,
  "status": "AUTHORIZED",
  "payment_method": "PIX",
  "payment_data": {
    "payment_id": "id-da-cobranca-no-provedor",
    "pix_key": "00020126..."
  },
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "document": "12345678901",
    "phone": "+5511999999999",
    "birth_date": null,
    "address": null
  }
}
```

> Consulte a **Seção 5** para saber quais status disparam webhook e quais são finais.

### Política de retry
- **Tentativas:** 3
- **Intervalo:** 15 segundos fixo entre cada tentativa
- **Sucesso:** resposta HTTP 2xx do endpoint receptor

### Receptor completo (Node.js / Express)

```javascript
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/apix', async (req, res) => {
  const { transaction_id, status, total_value, payment_method } = req.body;

  console.log(`[Webhook] ${transaction_id} → ${status}`);

  switch (status) {
    case 'AUTHORIZED':
      // Liberar o pedido, enviar e-mail de confirmação, atualizar banco
      await fulfillOrder(transaction_id, total_value);
      break;

    case 'REFUNDED':
      // Revogar acesso, processar reembolso interno, notificar cliente
      await revokeOrder(transaction_id);
      break;

    case 'CHARGED_BACK':
    case 'CHARGEBACK':
      // Revogar acesso, notificar equipe de risco
      await handleChargeback(transaction_id);
      break;

    case 'REJECTED':
    case 'CANCELLED':
      // Notificar cliente, oferecer nova tentativa
      await notifyFailure(transaction_id, status);
      break;

    case 'IN_MEDIATION':
    case 'IN_DISPUTE':
      // Registrar disputa (MED do PIX), aguardar resolução
      await flagDispute(transaction_id);
      break;
  }

  // SEMPRE responder 2xx — sem isso o sistema tentará novamente
  res.status(200).json({ received: true });
});

app.listen(3000);
```

---

## 7. EXEMPLOS DE FLUXOS COMPLETOS

### Fluxo A — PIX end-to-end

```bash
# 1. Criar a cobrança PIX
curl -X POST "https://api.apix.tec.br/api/v1/direct-payments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "amount": 9990,
    "description": "Pedido #1234",
    "paymentMethod": "pix",
    "customer": { "name": "João da Silva", "email": "joao@email.com", "document": "12345678901" }
  }'

# 2. Polling de status (usar transaction_id da resposta anterior)
curl -X GET "https://api.apix.tec.br/api/v1/payments/A1B2C3D4E5F6/status"
```

```javascript
// Fluxo completo em JavaScript (server-side)
async function cobrarPix(amount, description, customer) {
  // 1. Criar a cobrança
  const res = await fetch("https://api.apix.tec.br/api/v1/direct-payments", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.APIX_API_KEY,
    },
    body: JSON.stringify({ amount, description, paymentMethod: "pix", customer }),
  });
  const { data: payment } = await res.json();

  // 2. Exibir o PIX copia e cola como QR Code
  renderQRCode(payment.payment_data.pix_key);

  // 3. Polling como plano B do webhook
  const poll = async () => {
    const statusRes = await fetch("https://api.apix.tec.br/api/v1/payments/" + payment.transaction_id + "/status");
    const { data } = await statusRes.json();
    if (data.status === "PENDING") return setTimeout(poll, 15000);
    if (data.status === "AUTHORIZED") showSuccessPage();
    else showErrorPage(data.status);
  };
  poll();
}
```

---

### Fluxo B — Cartão de Crédito end-to-end

```bash
# 1. Criar pagamento
curl -X POST "https://api.apix.tec.br/api/v1/direct-payments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "amount": 9990,
    "description": "Assinatura mensal",
    "paymentMethod": "credit_card",
    "customer": { "name": "Maria Souza", "email": "maria@email.com", "document": "12345678901" },
    "cardData": [{
      "cardNumber": "4111111111111111",
      "cardHolderName": "MARIA SOUZA",
      "cardExpirationDate": "12/28",
      "cardCvv": "123",
      "parcels": 1,
      "value": 9990
    }]
  }'

# 2. Polling
curl -X GET "https://api.apix.tec.br/api/v1/payments/A1B2C3D4E5F6/status"
```

---

### Fluxo C — Webhook + Liberação do Pedido (end-to-end)

```bash
# Simular webhook localmente com ngrok
ngrok http 3000
# Cadastrar a URL pública gerada em /integracao (Integrações & APIs → Webhooks)
```

```javascript
// Servidor receptor do webhook
app.post('/webhooks/apix', async (req, res) => {
  const { transaction_id, status, total_value } = req.body;

  if (status === 'AUTHORIZED') {
    const order = await db.orders.findOne({ transaction_id });
    // Confira o valor recebido antes de liberar
    if (order && order.amount === total_value) {
      await db.orders.update({ transaction_id }, { status: 'paid' });
      await sendConfirmationEmail(order.customer_email);
      await grantAccess(order.user_id);
    }
  }

  res.status(200).json({ received: true });
});
```

---

## 8. FORMATOS DE DADOS

| Campo | Formato | Exemplo |
|-------|---------|---------|
| CPF | 11 dígitos sem máscara | `12345678901` |
| CNPJ | 14 dígitos sem máscara | `12345678000190` |
| Telefone | E.164 | `+5511999999999` |
| CEP | 8 dígitos sem hífen | `01001000` |
| Valores monetários | Inteiro em centavos | `9990` = R$ 99,90 |
| Data de nascimento | YYYY-MM-DD | `1990-01-15` |
| Expiração do cartão | MM/YY | `12/28` |
| Datas ISO | ISO 8601 | `2026-09-16T10:30:00.000Z` |

---

## 9. FORMATO DE ERRO

Todas as respostas de erro seguem o padrão:
```json
{ "error": "Mensagem descritiva do erro" }
```

| HTTP Status | Situação |
|-------------|----------|
| 400 | Dados inválidos (falha de validação) |
| 401 | API Key ausente ou inválida / assinatura inválida |
| 403 | IP fora da lista da chave ou chave sem a permissão necessária |
| 404 | Recurso não encontrado |
| 422 | Regra de negócio violada |
| 500 | Erro interno do servidor |

---

## 10. REGRAS CRÍTICAS PARA O LLM

Ao gerar código de integração, siga SEMPRE estas regras:

1. **Valores em centavos:** Nunca envie `9.90`, sempre `990`.
2. **Polling obrigatório:** Nunca assuma aprovação síncrona após `POST /direct-payments`.
3. **cardData condicional:** Inclua `cardData` apenas se `paymentMethod === "credit_card"`.
4. **Formato de documento:** Remova pontos, traços e barras antes de enviar.
5. **Chave server-side:** Nunca exponha `X-API-Key` nem a chave privada no browser ou app mobile.
6. **Resposta 2xx em webhooks:** Responda 2xx mesmo que ocorra erro no processamento interno.
7. **Idempotência:** O mesmo status pode chegar mais de uma vez; trate por `transaction_id` + `status`.
8. **Polling interval:** 15 segundos entre consultas. Não faça polling com intervalo menor.
9. **Stop polling:** Pare quando o status for `AUTHORIZED`, `REJECTED` ou `FAILED`.
10. **FAILED não gera webhook:** Detecte o status `FAILED` apenas via polling — ele nunca chegará por webhook.