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

# Comece em 10 minutos

> Do zero ao primeiro link de checkout: criar cliente, produto, preço e sessão de checkout em uma sequência única.

Este guia leva você do nada até **um link de checkout funcional** que pode ser enviado a um cliente real. Tudo em uma sessão de terminal, com dados mínimos.

## Antes de começar

<Steps>
  <Step title="Tenha uma conta Simplo">
    Cadastre-se em [besimplo.com](https://besimplo.com) se ainda não tem conta.
  </Step>

  <Step title="Pegue uma chave de sandbox">
    No painel, vá em **Configurações → Chaves de API** e copie a chave de **sandbox** (começa com `test_`).

    <Warning>
      Nunca use chaves de produção em ambiente de teste. Sandbox simula tudo sem cobrar de verdade.
    </Warning>
  </Step>

  <Step title="Exporte a chave no terminal">
    ```bash theme={null}
    export SIMPLO_API_KEY="test_sua_chave_aqui"
    ```
  </Step>
</Steps>

## Passo 1 — Criar um cliente

Toda cobrança no Simplo é feita contra um cliente. O único campo obrigatório é `name`. Aqui também enviamos um CPF válido para emissão fiscal:

<Note>
  O `identifier` (CPF/CNPJ) é validado por checksum. Padrões sequenciais como `123.456.789-09`, mesmo que matematicamente válidos, são rejeitados. Use um CPF/CNPJ real ou gerado por um validador.
</Note>

```bash theme={null}
curl -X POST https://besimplo.com/api/v1/customers \
  -H "Authorization: ApiKey $SIMPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Maria Silva",
      "identifier": "390.533.447-05"
    }
  }'
```

A resposta traz o `id` do cliente. Guarde-o:

```json theme={null}
{
  "id": "cus_01h455vb4pex5vsknk084sn02p",
  "object": "customer",
  "name": "Maria Silva",
  "identifier": "390.533.447-05"
}
```

```bash theme={null}
export CUSTOMER_ID="cus_01h455vb4pex5vsknk084sn02p"
```

## Passo 2 — Criar um produto

Produtos representam o **que** você vende. Não têm preço — preço é separado, para você poder ter o mesmo produto em planos mensais e anuais.

```bash theme={null}
curl -X POST https://besimplo.com/api/v1/products \
  -H "Authorization: ApiKey $SIMPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "name": "Plano Pro"
    }
  }'
```

```bash theme={null}
export PRODUCT_ID="prod_01h455vb4pex5vsknk084sn0gh"
```

## Passo 3 — Criar um preço

Aqui você define **quanto** e **com que frequência** cobrar. Valores em centavos. Para cobrança recorrente, envie o objeto `recurring`:

```bash theme={null}
curl -X POST https://besimplo.com/api/v1/prices \
  -H "Authorization: ApiKey $SIMPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "price": {
      "product_id": "'$PRODUCT_ID'",
      "type": "recurring",
      "unit_amount": 9990,
      "recurring": {
        "interval": "month",
        "interval_count": 1
      }
    }
  }'
```

`9990` significa **R\$ 99,90/mês**. A moeda é sempre `brl`.

```bash theme={null}
export PRICE_ID="price_01h455vb4pex5vsknk084sn0kk"
```

## Passo 4 — Criar a sessão de checkout

Em vez de criar a assinatura manualmente, deixe o Simplo cuidar disso através de uma **sessão de checkout**. Ela cria a assinatura, gera a fatura e devolve uma URL hospedada — pronta para enviar ao cliente:

```bash theme={null}
curl -X POST https://besimplo.com/api/v1/checkout/sessions \
  -H "Authorization: ApiKey $SIMPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session": {
      "customer_id": "'$CUSTOMER_ID'",
      "success_url": "https://seu-app.com/obrigado",
      "line_items": [
        { "price_id": "'$PRICE_ID'", "quantity": 1 }
      ]
    }
  }'
```

A resposta traz a `url` do checkout, o `id` do cliente, da fatura e da assinatura recém-criada:

```json theme={null}
{
  "live_mode": false,
  "customer":     { "id": "cus_01h455vb4pex5vsknk084sn02p" },
  "invoice":      { "id": "in_01h455vb4pex5vsknk084sn02q" },
  "subscription": { "id": "sub_01h455vb4pex5vsknk084sn02s" },
  "amount": 9990,
  "currency": "brl",
  "url": "https://besimplo.com/checkout/sessions/cs_01h455vb4pex5vsknk084sn02q?session_id=cs_01h455vb4pex5vsknk084sn02q"
}
```

Mande seu cliente para a `url`. Quando ele pagar, você recebe um webhook `invoice.paid`.

## E agora?

<CardGroup cols={2}>
  <Card title="Receba notificação quando pagar" icon="webhook" href="/conceitos/webhooks">
    Configure um webhook para o evento `invoice.paid` e atualize seu sistema na hora.
  </Card>

  <Card title="Entenda os erros" icon="circle-exclamation" href="/conceitos/erros">
    Como lidar com 422 (validação), 401 (auth) e 429 (rate limit).
  </Card>

  <Card title="Paginação" icon="layer-group" href="/conceitos/paginacao">
    Como percorrer listas grandes sem perder dados.
  </Card>

  <Card title="Referência completa" icon="book" href="/api-reference/introducao">
    Todos os endpoints, parâmetros e respostas.
  </Card>
</CardGroup>

<Tip>
  Em produção, automatize esses passos via SDK. Estamos preparando uma SDK Ruby oficial — em breve.
</Tip>