# DevPix

> Plataforma multi-tenant pra criação e processamento de cobranças PIX via
> Mercado Pago. Empresas se cadastram, conectam suas contas MP via OAuth, e
> recebem pagamentos PIX com split automático de comissão pra plataforma.

## Preços

Pague só quando vender: **2,99% por pagamento aprovado**.
Mínimo por transação: R$ 0,49. Máximo por transação: R$ 9,99.
Sem mensalidade e sem setup. A taxa é deduzida automaticamente via split
do Mercado Pago em cada pagamento aprovado.

Cálculo: `fee = clamp(amount * percent, R$ 0,49, R$ 9,99)`.
Exemplos: R$ 5,00 → R$ 0,49 (mínimo); R$ 100,00 → R$ 2,99 (3%); R$ 500,00 → R$ 9,99 (máximo).

Detalhes na seção Preços em https://mp-payment-system.onrender.com/#pricing.

## Visão geral

A API REST permite que sistemas de clientes (web, mobile, ESP32 e outros
dispositivos IoT) criem cobranças PIX, recebam notificações em tempo real
quando pagamentos são confirmados, e consultem histórico/status.

Autenticação por chave de API (`X-API-Key`) ou token de dispositivo
(`X-Device-Token`). Ambos são gerados no painel da empresa.

A API é versionada (`/api/v1/...`) com OpenAPI 3 navegável em `/docs`.

## Documentação

- [API Docs (Swagger UI)](https://mp-payment-system.onrender.com/docs): documentação interativa da API
- [OpenAPI 3 spec (JSON)](https://mp-payment-system.onrender.com/openapi.json): spec completa pra importar em ferramentas
- [Página inicial](https://mp-payment-system.onrender.com/): visão geral do produto
- [Cadastro público](https://mp-payment-system.onrender.com/cadastro): formulário pra novas empresas
- [Política de privacidade & LGPD](https://mp-payment-system.onrender.com/privacidade): tratamento de dados pessoais

## Endpoints principais

### Cobranças (autenticadas por X-API-Key)

- `POST https://mp-payment-system.onrender.com/api/v1/charges`: cria cobrança PIX. Body: `{ amount, description?, external_reference?, payer_email?, expiration_minutes? }`. Aceita header opcional `Idempotency-Key` (8-200 chars, TTL 24h).
- `GET https://mp-payment-system.onrender.com/api/v1/charges`: lista cobranças (params `limit`, `offset`)
- `GET https://mp-payment-system.onrender.com/api/v1/charges/{id}`: busca cobrança por ID
- `POST https://mp-payment-system.onrender.com/api/v1/charges/{id}/refund`: estorna cobrança aprovada (parcial via `{ amount }` ou total)
- `GET https://mp-payment-system.onrender.com/api/v1/charges/public/{id}`: info pública (sem auth) pra página de pagamento

### Devices IoT (autenticadas por X-Device-Token)

- `GET https://mp-payment-system.onrender.com/api/v1/devices/me`: info do device autenticado
- `POST https://mp-payment-system.onrender.com/api/v1/devices/heartbeat`: avisa que device está online
- `GET https://mp-payment-system.onrender.com/api/v1/devices/current-charge`: cobrança ativa em formato compacto
- `GET https://mp-payment-system.onrender.com/api/v1/devices/wait-payment?timeout=30`: long polling até pagamento aprovado (até 60s)

## Webhooks (entrega assíncrona pra cliente)

Quando uma cobrança muda de status, a plataforma faz POST na URL configurada
no painel da empresa. Assina HMAC SHA256 no header `X-MPP-Signature`
(formato `sha256=<hex>`). Eventos:

- `charge.created`: cobrança criada
- `charge.approved`: pagamento confirmado pelo MP
- `charge.rejected`, `charge.cancelled`, `charge.expired`, `charge.updated`

Retry automático com backoff exponencial (30s, 2min, 10min, 30min, 2h, 6h)
em caso de falha (não-2xx ou timeout).

## Erros

Formato Problem Details (RFC 7807) com campo `code` estável:

```json
{
  "type": "about:blank",
  "title": "Empresa não conectou Mercado Pago",
  "status": 409,
  "code": "mp_not_connected",
  "detail": "..."
}
```

Codes comuns: `api_key_required`, `api_key_invalid`, `invalid_amount`,
`mp_not_connected`, `charge_not_found`, `mp_error`, `device_token_invalid`.

## Como integrar (resumo)

1. Empresa cadastra no painel
2. Empresa conecta conta Mercado Pago via OAuth ("Conectar com Mercado Pago")
3. Empresa cria API key no painel
4. Sistema do cliente faz POST em `/api/v1/charges` com a API key
5. Recebe `qrCode` (PIX copia-cola) e `qrCodeBase64` (PNG)
6. Cliente exibe QR pro pagador
7. Pagador paga via app do banco
8. Mercado Pago confirma → plataforma recebe webhook MP → atualiza status
9. Plataforma envia webhook outbound pro cliente com `charge.approved`

## Exemplo de cobrança (cURL)

```bash
curl -X POST 'https://mp-payment-system.onrender.com/api/v1/charges' \
  -H 'X-API-Key: SUA_API_KEY' \
  -H 'Idempotency-Key: '$(uuidgen) \
  -H 'Content-Type: application/json' \
  -d '{"amount": 100.00, "description": "Pedido #123"}'
```

## Exemplo de validação de webhook (Node.js)

```javascript
const crypto = require('crypto');

app.post('/pix-callback',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-mpp-signature']?.replace('sha256=', '');
    const expected = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(req.body).digest('hex');
    if (sig !== expected) return res.status(401).end();
    const event = JSON.parse(req.body);
    // event.event === 'charge.approved' | 'charge.created' | ...
    // event.data === { id, amount, status, ... }
    res.status(200).end();
  }
);
```

## Considerações de segurança

- Use HTTPS sempre. A plataforma só aceita webhook com TLS em produção.
- Guarde a API key em variável de ambiente, nunca hardcode em frontend.
- Valide o HMAC dos webhooks recebidos antes de processar.
- Use `Idempotency-Key` em retentativas pra evitar criar cobranças duplicadas.
- Renove tokens (API key, device token) regularmente.

## Limites

- Body de request: 500KB
- Rate limit geral: 120 req/min por IP
- Rate limit no login: 5 falhas / 15min
- Logo da plataforma/empresa: 1MB max em base64

## Suporte

Pra dúvidas sobre integração, consulte `/docs` ou abra um pedido pelo
formulário de contato no painel da empresa.