Skip to main content

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.

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

1

Tenha uma conta Simplo

Cadastre-se em besimplo.com se ainda não tem conta.
2

Pegue uma chave de sandbox

No painel, vá em Configurações → Chaves de API e copie a chave de sandbox (começa com test_).
Nunca use chaves de produção em ambiente de teste. Sandbox simula tudo sem cobrar de verdade.
3

Exporte a chave no terminal

export SIMPLO_API_KEY="test_sua_chave_aqui"

​
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:
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.
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: 
{
  "id": "cus_01h455vb4pex5vsknk084sn02p",
  "object": "customer",
  "name": "Maria Silva",
  "identifier": "390.533.447-05"
}

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. 
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"
    }
  }'

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: 
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. 
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: 
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: 
{
  "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?

Receba notificação quando pagar

Configure um webhook para o evento invoice.paid e atualize seu sistema na hora.

Entenda os erros

Como lidar com 422 (validação), 401 (auth) e 429 (rate limit).

Paginação

Como percorrer listas grandes sem perder dados.

Referência completa

Todos os endpoints, parâmetros e respostas.
Em produção, automatize esses passos via SDK. Estamos preparando uma SDK Ruby oficial — em breve.