# Conceitos essenciais

Chaves, ambientes, ciclo de vida da ordem e idempotência — os conceitos essenciais do FaciConnect.

## Credenciais

| Credencial | Onde vive | Para que serve |
|---|---|---|
| `PUBLISHABLE_KEY` (`pk_test_…`/`pk_live_…`) | Frontend + backend | Inicializa a SDK e identifica a aplicação. |
| `CLIENT_ID` | **Só backend** | Identifica o parceiro na obtenção do token. |
| `CLIENT_SECRET` | **Só backend** | Segredo para obter o `access_token`. |
| `WEBHOOK_SECRET` | **Só backend** | Verifica a assinatura HMAC dos webhooks. |

<Warning>
`CLIENT_SECRET` e `WEBHOOK_SECRET` **nunca** podem ir para o bundle do frontend.
Mantenha-os em variáveis de ambiente no servidor.
</Warning>

### applicationUUID

Várias chamadas à API pedem `applicationUUID`. É a sua `PUBLISHABLE_KEY` **sem** o prefixo:

```js
const applicationUUID = PUBLISHABLE_KEY.replace(/^pk_(test|live)_/, '');
```

## Ambientes

| Ambiente | Prefixo da chave | Base URL |
|---|---|---|
| Sandbox | `pk_test_…` | `https://sandbox.api.faciconnect.com` |
| Produção | `pk_live_…` | `https://api.faciconnect.com` |

<Note>
Teste **sempre** todo o fluxo com `pk_test_` antes de mudar para `pk_live_`.
Produção exige **HTTPS**.
</Note>

## Ciclo de vida da ordem

Uma ordem tem três estados. A transição é dirigida pela FaciPay e confirmada pelo webhook.

```mermaid
stateDiagram-v2
    [*] --> PEN: createPaymentOrder
    PEN --> CON: pagamento confirmado
    PEN --> CAN: cancelado / expirado
    CON --> [*]
    CAN --> [*]
```

| Estado | Significado | Ação típica |
|---|---|---|
| `PEN` | Pendente | Aguardar (Multicaixa Express) ou mostrar referência (EMIS). |
| `CON` | Confirmado / pago | Fulfillment: confirmação, email, libertar produto. |
| `CAN` | Cancelado | Reabrir carrinho, libertar stock. |

## A fonte da verdade

O estado autoritativo de um pagamento vem **sempre do webhook** no seu backend, não dos
callbacks do frontend. Os callbacks (`onApprove`, `onPending`, `onCancel`) servem para a
**experiência do utilizador**; a confirmação de negócio (libertar produto, faturar) só
acontece quando o webhook confirma `CON`.

O endpoint [`GET /facipaypartner/paymentByExternalTransaction`](/pt/api-reference/introduction)
é apenas uma **rede de segurança** (fallback) para quando o webhook falha ou atrasa.

## Idempotência

O `externalTransactionId` é a chave de idempotência. Garante que:

- Cada ordem tem um `externalTransactionId` **único** (ex.: `order_<UUID>`).
- Se um webhook chegar repetido para uma ordem já em estado final (`CON`/`CAN`),
  responde `200` **sem reprocessar**.

```js
function updateOrder(externalTransactionId, paymentStatus) {
  const order = db.orders.find(externalTransactionId);
  if (!order) return;
  if (order.status === 'CON' || order.status === 'CAN') return; // já final → não reprocessa
  db.orders.update(externalTransactionId, { status: paymentStatus });
}
```

## Recebimentos e taxas

<Note>
**Onde fica o dinheiro.** Os valores recebidos são creditados na sua **conta FaciPay**. A
partir daí pode usá-los para pagamentos via FaciPay ou **levantar para o seu banco**. Sobre
cada transação aplica-se uma **taxa** — para os detalhes, fale com a equipa comercial da **Faci-X**.
</Note>

<Card title="Próximo passo: Segurança" icon="arrow-right" href="/pt/get-started/security">
  Verificação HMAC do webhook, passo a passo por framework.
</Card>