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.