> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goatpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Primeira integração

> Do zero ao primeiro PIX recebido — chave de API, saldo, cobrança e webhook

Este guia leva você da conta GoatPay até a **primeira cobrança PIX** confirmada por webhook. Tempo estimado: 15–20 minutos.

## Pré-requisitos

* Conta em [app.goatpay.com.br](https://app.goatpay.com.br)
* Backend ou ferramenta que faça HTTP (`curl`, Postman, seu servidor)
* URL HTTPS pública para webhooks (em dev, use [ngrok](https://ngrok.com) ou similar)

## 1. Criar a chave de API

1. Acesse **Integrações → Chaves de API**
2. Clique em **Nova chave**
3. Preencha:
   * **Descrição:** ex. `Produção ERP`
   * **Preset:** comece com `read` + adicione `payment-pix/create` e `webhooks/create`, ou use `write`
   * **Trilho:** `PADRAO` (único trilho operacional)
4. Copie o `gp_live_...` — ele aparece **uma única vez**

Guarde em variável de ambiente:

```bash theme={null}
export GOATPAY_API_KEY=gp_live_SUA_CHAVE
```

<Warning>
  Não existe sandbox separado. Todas as chaves são de produção; teste com valores baixos (ex. R\$ 1,00).
</Warning>

Detalhes de permissões: [Permissões da API key](/pages/guides/api-permissions) · [Chaves de API](/pages/guides/authentication).

## 2. Testar autenticação

```bash theme={null}
curl https://api.goatpay.com.br/v1/account/balance \
  -H "X-API-Key: $GOATPAY_API_KEY"
```

Resposta esperada (envelope padrão):

```json theme={null}
{
  "success": true,
  "message": "OK",
  "data": {
    "currency": "BRL",
    "availableAmount": 0,
    "pendingAmount": 0
  },
  "requestId": "req_..."
}
```

Se receber `401`, confira o header `X-API-Key`. Se `403`, ajuste permissões ou IP allowlist no dashboard.

## 3. Criar uma cobrança PIX

```bash theme={null}
curl -X POST https://api.goatpay.com.br/v1/payment-pix/create \
  -H "X-API-Key: $GOATPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1,
    "description": "Teste integração",
    "coverFee": false,
    "externalReference": "pedido-001"
  }'
```

Na resposta, use:

| Campo               | Uso                          |
| ------------------- | ---------------------------- |
| `data.id`           | Consultar status depois      |
| `data.copyPaste`    | Pix copia e cola no checkout |
| `data.qrCodeBase64` | QR em base64                 |
| `data.qrcodeUrl`    | URL da imagem do QR          |

Mostre o QR ou o copia e cola para o pagador. Guia completo: [Receber PIX](/pages/guides/receber-pix).

## 4. Cadastrar webhook

```bash theme={null}
curl -X POST https://api.goatpay.com.br/v1/webhooks/create \
  -H "X-API-Key: $GOATPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.suaempresa.com/goatpay/webhook",
    "events": ["payment.paid", "payment.created", "payment.pix.expired"]
  }'
```

Anote o `whsec_...` retornado — **só aparece na criação**. Guia passo a passo: [Webhooks na prática](/pages/guides/webhooks-pratica).

<Note>
  Endpoints criados por API key só recebem eventos de transações criadas pela **mesma** chave.
</Note>

## 5. Confirmar o pagamento

Após o pagador concluir o PIX:

1. Sua URL recebe `POST` com evento `payment.paid`
2. Valide `x-goatpay-signature` com o `whsec_...`
3. Use `data.externalReference` para marcar o pedido como pago no seu sistema

Alternativa sem webhook: `GET /v1/payment-pix/get/{id}` — mas prefira webhooks em produção.

## Checklist de produção

* [ ] Chave com permissões mínimas (não use `full` sem necessidade)
* [ ] `GOATPAY_API_KEY` em secret manager, nunca no repositório
* [ ] Webhook com HTTPS e validação HMAC
* [ ] Idempotência pelo `id` da entrega webhook
* [ ] `externalReference` em toda cobrança para reconciliação
* [ ] Tratamento de `429` (100 req/min por chave)

## Próximos passos

<CardGroup cols={2}>
  <Card title="Receber PIX" icon="qrcode" href="/pages/guides/receber-pix">
    Fluxo completo de cobrança e reconciliação.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pages/guides/webhooks-pratica">
    Código de validação HMAC e idempotência.
  </Card>

  <Card title="Integração com IA" icon="robot" href="/pages/guides/integracao-ia">
    Use llms.txt no Cursor, Claude ou ChatGPT.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Todas as rotas e playground interativo.
  </Card>
</CardGroup>