# Primeiros Passos

Integre sua aplicação com a API da Monetarie e realize sua primeira operação PIX em poucos minutos.

## 1. Obtenha suas credenciais

Solicite ao administrador da sua conta Monetarie:

- **Client ID** -- identificador da sua API Key (prefixo `cli_`)
- **Client Secret** -- chave secreta para autenticação e assinatura HMAC (prefixo `sk_`)

::: warning Segurança
Nunca exponha o `client_secret` em código frontend ou repositórios públicos. Utilize variáveis de ambiente no seu servidor.
:::

## 2. Configure a autenticação

Todas as requisições exigem o header `Authorization` com suas credenciais API Key:

```bash
# Formato do header:
Authorization: ApiKey {client_id}:{client_secret}
```

A API Key é permanente -- não expira. Não é necessário gerar tokens.

## 3. Consulte o saldo

Teste a integração consultando o saldo da conta:

```bash
curl -X GET https://api.monetarie.com/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

**Resposta:**

```json
{
  "worked": true,
  "balance": 300000,
  "available": 300000,
  "pending": 0,
  "currency": "BRL"
}
```

::: danger Valores monetários
Valores de **entrada** (request) são em **centavos**: R$ 30,00 = `3000`.
Valores de **resposta** são em **unidades base**: `300000` ÷ 10.000 = R$ 30,00.
**Nunca use ponto flutuante** -- sempre inteiros.
:::

## 4. Gere uma cobrança PIX (Cash-In)

Crie um QR Code para receber R$ 30,00:

```bash
BODY='{"amount":3000,"description":"Pedido #1234","external_id":"order-9876"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.monetarie.com/api/external/pix/cash-in \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"
```

**Resposta:**

```json
{
  "worked": true,
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,...",
  "external_id": "order-9876",
  "amount": 300000,
  "status": "active"
}
```

Note que você enviou `3000` (centavos) e recebeu `300000` (unidades base). Ambos representam R$ 30,00.

Exiba o `qr_code_image` ou o código copia-e-cola (`qr_code`) ao pagador.

## 5. Consulte o status

Acompanhe o pagamento consultando pelo `transaction_id`:

```bash
curl -X GET https://api.monetarie.com/api/external/transactions/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

Quando o pagamento for confirmado, o `status` muda para `completed`.

Você também pode consultar pelo `external_id`:

```bash
curl -X GET https://api.monetarie.com/api/external/transactions/ref/order-9876 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

## 6. Receba notificações (Webhooks)

Para receber notificações em tempo real (recomendado em vez de polling):

```bash
BODY='{"url":"https://seusite.com.br/webhook","events":["pix.charge.paid","pix.payout.confirmed"]}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.monetarie.com/api/external/webhooks \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"
```

## Próximos Passos

- [Autenticação](/auth-token) -- API Key + HMAC (3 camadas de segurança)
- [HMAC-SHA512](/hmac) -- como assinar requisições transacionais
- [PIX Cash-In](/pix-cashin) -- gerar cobranças
- [PIX Cash-Out](/pix-cashout-key) -- enviar PIX por chave
- [Extrato](/bank-statement) -- consultar transações
- [Webhooks](/webhooks) -- notificações em tempo real
- [Conceitos](/guide/concepts) -- valores, status, external_id, idempotência e chaves PIX