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

# Quickstart

> Sua primeira cobrança Pix em menos de 5 minutos.

## Pela API

<Note>
  Conta nova opera **em modo teste** até passar pela
  [aprovação de produção](/aprovacao-de-producao). O caminho abaixo funciona inteiro no
  teste — integre primeiro, ative a produção depois.
</Note>

<Steps>
  <Step title="Crie uma conta e faça login">
    Pelo painel, ou por `POST /auth/register` e `POST /auth/login`. A resposta traz um
    `accessToken` (JWT) que serve para o próximo passo.
  </Step>

  <Step title="Gere uma chave de API de teste">
    Com o JWT, chame `POST /api-keys` com `environment: "test"`. A chave começa com
    `v4pay_test_` e **aparece uma única vez** na resposta — guarde na hora. (A chave de
    produção, `v4pay_live_`, só existe depois da aprovação.)

    ```bash theme={null}
    curl -X POST https://v4pay-api.vercel.app/api-keys \
      -H "Authorization: Bearer SEU_JWT" \
      -H "Content-Type: application/json" \
      -d '{ "name": "Integração da loja", "environment": "test" }'
    ```

    ```json theme={null}
    { "data": { "id": "…", "name": "Integração da loja", "prefix": "v4pay_test_3f9a2c1", "key": "v4pay_test_3f9a2c1e…" } }
    ```
  </Step>

  <Step title="Emita uma cobrança">
    Agora com a chave. Os seis campos abaixo são obrigatórios no modo manual — e três
    regras valem sempre: `amount` é em **reais** (`100` = R$ 100,00) e o mínimo é     **R$ 5,00\*\*; `customer_cpf` aceita **CPF ou CNPJ**, com os dígitos verificadores
    conferidos; `expires_at` diz até quando a cobrança pode ser paga — use uma data
    **futura**: a API aceita qualquer data, e uma no passado cria a cobrança já
    expirada.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://v4pay-api.vercel.app/pix \
        -H "Authorization: Bearer v4pay_SUA_CHAVE" \
        -H "Content-Type: application/json" \
        -d '{
          "amount": 100,
          "description": "Pedido 1234",
          "customer_name": "Maria Silva",
          "customer_email": "maria@exemplo.com.br",
          "customer_cpf": "12345678909",
          "expires_at": "2027-12-31T23:59:00Z"
        }'
      ```

      ```javascript JavaScript theme={null}
      const resposta = await fetch('https://v4pay-api.vercel.app/pix', {
        method: 'POST',
        headers: {
          Authorization: 'Bearer v4pay_SUA_CHAVE',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          amount: 100,
          description: 'Pedido 1234',
          customer_name: 'Maria Silva',
          customer_email: 'maria@exemplo.com.br',
          customer_cpf: '12345678909',
          expires_at: '2027-12-31T23:59:00Z',
        }),
      });

      const { data, error } = await resposta.json();
      if (error) throw new Error(error.message ?? error);
      console.log(data.txid, data.pix_code); // copia e cola
      ```

      ```python Python theme={null}
      import requests

      resposta = requests.post(
          "https://v4pay-api.vercel.app/pix",
          headers={"Authorization": "Bearer v4pay_SUA_CHAVE"},
          json={
              "amount": 100,
              "description": "Pedido 1234",
              "customer_name": "Maria Silva",
              "customer_email": "maria@exemplo.com.br",
              "customer_cpf": "12345678909",
              "expires_at": "2027-12-31T23:59:00Z",
          },
      )
      corpo = resposta.json()
      if "error" in corpo:
          raise RuntimeError(corpo["error"])
      print(corpo["data"]["txid"], corpo["data"]["pix_code"])
      ```
    </CodeGroup>

    A resposta (`201`) traz a cobrança inteira: `txid`, `pix_code` (copia e cola),
    `qr_code_url` (imagem em base64) e `status: "pending"`.
  </Step>

  <Step title="Mostre o QR code e espere o pagamento">
    Exiba `qr_code_url` como imagem e `pix_code` para copiar — ou mande o cliente para a
    página pública `https://pay.v4companyamaral.com/checkout/{txid}`, que faz tudo isso.
    Quando o cliente pagar, o status vira `paid`, o comprovante público fica em
    `/comprovante/{txid}` no painel e o pagador recebe o link por e-mail (quando o envio
    está configurado). Você fica sabendo de dois jeitos:

    * **Webhook** (recomendado): cadastre uma URL em `POST /webhook-endpoints` e receba
      o evento `charge.paid`. Veja [Webhooks](/webhooks).
    * **Consulta**: `GET /pix/status?txid=…` a qualquer momento.

    Em modo teste, "pagar" é `POST /pix/simulate-payment` — veja
    [Ambiente de testes](/ambiente-de-testes).
  </Step>
</Steps>

<Tip>
  As regras completas da emissão (modo produto, status, o que o pagador recebe) estão em
  [Cobranças](/cobrancas).
</Tip>

## Pelo painel

<Steps>
  <Step title="Entre no painel">
    Com e-mail e senha, ou com a conta Google. A conta nova entra em **modo teste** —
    uma faixa no topo avisa.
  </Step>

  <Step title="Experimente sem dinheiro">
    Crie cobranças e links normalmente: o QR code de teste não é pagável de propósito, e
    o botão **Simular pagamento** faz a cobrança virar paga — o fluxo inteiro, sem mover
    um centavo.
  </Step>

  <Step title="Ative a produção">
    Em **Ativar produção**, complete os dados da empresa e envie os três documentos.
    A equipe do V4 Pay analisa e você recebe um e-mail com o resultado — o passo a passo
    está em [Aprovação de produção](/aprovacao-de-producao).
  </Step>

  <Step title="Vá para produção e acompanhe">
    Aprovado, o botão **Ir para produção** ativa. Dali em diante a cobrança muda para
    **Paga** sozinha quando o Pix cai, e o histórico fica em **Cobranças**. Para onde o
    dinheiro vai está explicado em [Modo de recebimento](/modo-de-recebimento).
  </Step>
</Steps>