# PayApp — API de verificação de comprovativos

> Serviço que confirma se um comprovativo de transferência bancária angolano é
> genuíno, se o dinheiro foi para a conta certa e se aquele comprovativo já foi
> usado antes. Produto da Ferreira Korp, Luanda, Angola.

Base: `https://api.payapp.ferreirakorp.com`
Autenticação: cabeçalho `X-API-Key: pk_live_…` (ou `Authorization: Bearer pk_live_…`).
Obter chave: https://api.payapp.ferreirakorp.com/painel

## Princípio de privacidade (importante ao integrar)

O PDF enviado **não é guardado em lado nenhum**. É analisado em memória e
descartado no fim do pedido. O nome, o IBAN e o valor existem apenas na resposta
devolvida — não ficam no servidor.

Para detectar comprovativos repetidos guardamos só uma impressão digital
irreversível: `SHA-256(id_da_loja + numero_da_transaccao + sal_secreto)`. Leva o
identificador da loja lá dentro, por isso a mesma transacção gera impressões
diferentes em lojas diferentes.

Consequência prática: **se precisar do histórico com valores, guarde-o do seu
lado** a partir das respostas. A API só devolve contagens.

---

## POST /v1/verify

Verifica um comprovativo contra as contas registadas da loja.

Aceita três formatos de envio:

1. `multipart/form-data` com o campo `comprovativo` (ou `file`, ou `pdf`)
2. `application/json` com `{ "pdf_b64": "<base64>", "valor": 45000 }`
3. o PDF em bruto no corpo do pedido

O campo opcional `valor` é o montante esperado da encomenda. Quando enviado, a
verificação também confirma que o comprovativo cobre esse valor.

### Exemplo

```bash
curl -X POST https://api.payapp.ferreirakorp.com/v1/verify \
  -H "X-API-Key: pk_live_…" \
  -F "comprovativo=@transferencia.pdf"
```

### Resposta

```json
{
  "ok": true,
  "autentico": true,
  "repetido": false,
  "verdict": "VERDADEIRO",
  "valor": 45000,
  "txn": "0912847361",
  "nome": "Ana Miguel",
  "iban": "AO06…5017 9",
  "motivo": [],
  "cobrado": "gratis",
  "retencao": "nenhuma"
}
```

| Campo | Significado |
|---|---|
| `autentico` | a assinatura digital do banco confere e o destino é uma conta da loja |
| `repetido` | este comprovativo já tinha sido verificado nesta loja |
| `verdict` | `VERDADEIRO`, `FALSO`, `NAO_CONFIRMADO` ou `ERRO` |
| `valor` | montante em Kwanzas |
| `nome` | quem ordenou a transferência |
| `motivo` | lista de explicações em português quando falha (mostrável ao cliente) |
| `cobrado` | `gratis` (dentro das 100 do mês) ou `credito` |

**Regra de negócio:** só entregue a mercadoria quando `autentico === true` **e**
`repetido === false`. Um comprovativo autêntico mas repetido é a tentativa de
burla mais comum — o mesmo PDF verdadeiro reenviado a várias lojas.

### Erros

| Código | Situação |
|---|---|
| 401 | API key inválida |
| 400 | não veio PDF nenhum |
| 402 | sem créditos — a loja tem de recarregar |

---

## GET /v1/usage

Consumo do mês e saldo.

```json
{
  "ok": true,
  "mes": "2026-08",
  "usadas": 37,
  "gratis": 100,
  "restantes_gratis": 63,
  "creditos_kz": 5000,
  "verificacoes_pagas": 100,
  "preco_kz": 50
}
```

## GET /v1/stats

Público, sem autenticação. Só números, nenhum dado de ninguém.

```json
{
  "ok": true,
  "comprovativos_verificados": 1284,
  "lojas_integradas": 17,
  "retencao_de_dados": "nenhuma"
}
```

## POST /v1/register

Cria uma loja. Corpo: `{ "name", "email", "ibans", "phone" }`.
`ibans` aceita lista ou texto separado por vírgulas. É preciso pelo menos um
IBAN **ou** um número Multicaixa Express. Devolve a `api_key` — só é mostrada uma vez.

## POST /v1/credits/topup

Carrega créditos. A loja transfere para a conta da Ferreira Korp e envia o
comprovativo do depósito, no mesmo formato do `/v1/verify`. Depósito mínimo
1000 Kz. O crédito é libertado quando o comprovativo do depósito é validado.

## POST /v1/vitrine

`{ "site": "https://a-minha-loja.co.ao" }` — vamos ao site buscar o logótipo e
publicamo-lo na parede "Empresas que confiam em nós" da página inicial.

## GET /v1/versao

Versão actual da app Android e notas da versão.

---

## Notificações em tempo real

Configuram-se no painel: https://api.payapp.ferreirakorp.com/painel

**Webhook** — POST no seu servidor a cada verificação genuína.

```
x-payapp-timestamp: 1786060400
x-payapp-signature: v1=<hex>
```

A assinatura é `HMAC-SHA256(segredo_do_webhook, timestamp + "." + corpo_cru)`.
**Valide-a sempre** antes de confiar no conteúdo, e rejeite timestamps com mais
de 5 minutos — é isso que impede alguém de forjar um aviso de pagamento.

Corpo:

```json
{
  "evento": "comprovativo.verificado",
  "autentico": true,
  "valor": 45000,
  "txn": "0912847361",
  "nome": "Ana Miguel",
  "em": "2026-08-07T09:14:22.000Z"
}
```

**WebSocket** — `wss://payapp.ferreirakorp.com/rt/ws`. Público, só difunde o
contador global de verificações. Mensagens: `{ "tipo": "verificado", "total": 1284 }`.

**Email, SMS e WhatsApp** — configuram-se no painel, sem escrever código.

---

## Preço

100 verificações por mês grátis, sem prazo e sem cartão. A partir daí 50 Kz por
verificação, descontados de créditos carregados por transferência. Sem
mensalidade, sem contrato, sem mínimos.

## Limites

- Tamanho máximo do PDF: 22 MB
- O comprovativo tem de ser o **PDF** emitido pelo banco. Uma fotografia do ecrã
  não tem assinatura digital e não pode ser verificada.
- Comprovativos com mais de 30 dias são recusados por omissão.

## O que a API não faz

Não move dinheiro, não é carteira, não processa pagamentos e não toca nos fundos
de ninguém. Responde a uma pergunta: este comprovativo é verdadeiro?

## Contactos

+244 945 321 186 · payapp@ferreirakorp.com · https://payapp.ferreirakorp.com