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

# Quickstart

> Gere uma cobrança PIX e receba o webhook de pago, do início ao fim.

Este guia leva você de zero a um PIX pago. Ao final, você terá autenticado, criado uma cobrança e recebido a confirmação de pagamento por webhook.

## Pré-requisitos

Antes de começar, você precisa de:

* Uma **API key** (`public` + `secret`), gerada no painel da sua empresa. Veja [Autenticação](/guias/autenticacao).
* Um **endpoint público HTTPS** para receber os webhooks (pode ser um túnel local como ngrok durante os testes).

## Fluxo completo

<Steps>
  <Step title="Autenticar">
    Troque sua API key por um token de acesso. Use o token no header `Authorization` das próximas chamadas.

    ```bash theme={null}
    TOKEN=$(curl -s -X POST https://api.ephra.io/auth \
      -u "$PUBLIC:$SECRET" | jq -r .token)
    ```
  </Step>

  <Step title="Cadastrar o webhook (uma vez)">
    Registre a URL que receberá as notificações. Guarde o `signatureSecret` retornado.

    ```bash theme={null}
    curl -s -X POST https://api.ephra.io/v1/webhook \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://seusite.com/webhooks/ephra",
        "events": ["transaction_created", "transaction_paid"]
      }'
    ```
  </Step>

  <Step title="Criar a cobrança PIX">
    Gere o QR Code. A resposta traz o `emv` (copia e cola) e o `qrCode` (imagem PNG em base64) para o cliente pagar.

    ```bash theme={null}
    curl -s -X POST https://api.ephra.io/v1/pix/in/qrcode \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amountInCents": 10000,
        "description": "Pedido #1234",
        "customer": {
          "name": "Maria Silva",
          "email": "maria@email.com",
          "documentType": "cpf",
          "document": "12345678909"
        }
      }'
    ```

    A transação nasce com `status: "pending"`. Guarde o `data.id` para correlacionar o webhook.
  </Step>

  <Step title="Receber a confirmação">
    Quando o cliente pagar, seu endpoint recebe um `POST` com `event: "transaction_paid"` e `transaction.status: "paid"`. Esse é o gatilho para liberar o pedido.

    ```json theme={null}
    {
      "event": "transaction_paid",
      "transaction": { "id": "clxabc123def456", "amount": 10000, "status": "paid" }
    }
    ```
  </Step>
</Steps>

<Tip>
  Você recebe `transaction_created` quase imediatamente (status `pending`) e `transaction_paid` quando o pagamento for confirmado. Trate seu endpoint de forma idempotente — deduplique pelo `transaction.id`.
</Tip>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Cobrança no cartão" icon="credit-card" href="/guias/cartao">
    Tokenize o cartão e cobre em até 12 parcelas.
  </Card>

  <Card title="Entender os webhooks" icon="bell" href="/webhooks/visao-geral">
    Conheça o modelo de eventos, validação de assinatura e idempotência.
  </Card>
</CardGroup>