# Primeros Pasos

Integre su aplicacion con la API de Monetarie y realice su primera operacion PIX en pocos minutos.

## 1. Obtenga sus credenciales

Solicite al administrador de su cuenta Monetarie:

- **Client ID** -- identificador de su API Key (prefijo `cli_`)
- **Client Secret** -- clave secreta para autenticacion y firma HMAC (prefijo `sk_`)

::: warning Seguridad
Nunca exponga el `client_secret` en codigo frontend o repositorios publicos. Utilice variables de entorno en su servidor.
:::

## 2. Configure la autenticacion

Todas las solicitudes exigen el header `Authorization` con sus credenciales API Key:

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

La API Key es permanente -- no expira. No es necesario generar tokens.

## 3. Consulte el saldo

Pruebe la integracion consultando el saldo de la cuenta:

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

**Respuesta:**

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

::: danger Valores monetarios
Los valores de **entrada** (request) son en **centavos**: R$ 30,00 = `3000`.
Los valores de **respuesta** son en **unidades base**: `300000` / 10.000 = R$ 30,00.
**Nunca use punto flotante** -- siempre enteros.
:::

## 4. Genere un cobro PIX (Cash-In)

Cree un QR Code para recibir 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"
```

**Respuesta:**

```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 envio `3000` (centavos) y recibio `300000` (unidades base). Ambos representan R$ 30,00.

Muestre el `qr_code_image` o el codigo copia y pega (`qr_code`) al pagador.

## 5. Consulte el estado

Acompane el pago consultando por el `transaction_id`:

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

Cuando el pago sea confirmado, el `status` cambia a `completed`.

Tambien puede consultar por el `external_id`:

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

## 6. Reciba notificaciones (Webhooks)

Para recibir notificaciones en tiempo real (recomendado en vez de polling):

```bash
BODY='{"url":"https://seusite.com.br/webhook","events":["pix.received","pix.completed"]}'
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"
```

## Proximos Pasos

- [Autenticacion](/es/auth-token) -- API Key + HMAC (3 capas de seguridad)
- [HMAC-SHA512](/es/hmac) -- como firmar solicitudes transaccionales
- [PIX Cash-In](/es/pix-cashin) -- generar cobros
- [PIX Cash-Out](/es/pix-cashout-key) -- enviar PIX por clave
- [Extracto](/es/bank-statement) -- consultar transacciones
- [Webhooks](/es/webhooks) -- notificaciones en tiempo real
- [Conceptos](/es/guide/concepts) -- valores, estados, external_id, idempotencia y claves PIX