Comece em 10 minutos

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

Tenha uma conta Simplo

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

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.

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",
      "external_code": "crm_customer_123"
    }
  }'

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"

Localizar um cliente existente

Se você ainda não salvou o id do Simplo, use os filtros do GET /api/v1/customers. Você pode localizar o cliente por identifier (CPF/CNPJ) ou pelo external_code definido pela sua integração. Os dois valores são únicos dentro da sua conta. O documento pode ser enviado com ou sem pontuação.

curl -G https://besimplo.com/api/v1/customers \
  -H "Authorization: ApiKey $SIMPLO_API_KEY" \
  --data-urlencode "identifier=39053344705"

Para buscar pelo seu próprio identificador, use external_code:

curl -G https://besimplo.com/api/v1/customers \
  -H "Authorization: ApiKey $SIMPLO_API_KEY" \
  --data-urlencode "external_code=crm_customer_123"

As duas buscas retornam a lista paginada de clientes, com no máximo um resultado para cada filtro. Guarde o data[0].id retornado para as próximas chamadas.

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 da própria sessão, e os IDs do cliente, da fatura e da assinatura recém-criada:

{
  "id": "cs_01h455vb4pex5vsknk084sn02c",
  "object": "checkout_session",
  "amount": 9990,
  "created": 1741541000,
  "currency": "brl",
  "customer": "cus_01h455vb4pex5vsknk084sn02p",
  "expires_at": 1741544600,
  "invoice": "in_01h455vb4pex5vsknk084sn02q",
  "live_mode": false,
  "mode": "subscription",
  "status": "open",
  "subscription": "sub_01h455vb4pex5vsknk084sn02s",
  "success_url": "https://seu-app.com/obrigado",
  "url": "https://besimplo.com/checkout/sessions/cs_01h455vb4pex5vsknk084sn02c"
}

Guarde o id: GET /api/v1/checkout/sessions/{id} devolve a sessão a qualquer momento. 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.

Comece por aqui

Conceitos

Comece em 10 minutos

Antes de começar

Passo 1 — Criar um cliente

Localizar um cliente existente

Passo 2 — Criar um produto

Passo 3 — Criar um preço

Passo 4 — Criar a sessão de checkout

E agora?

Receba notificação quando pagar

Entenda os erros

Paginação

Referência completa

​Antes de começar

​Passo 1 — Criar um cliente

​Localizar um cliente existente

​Passo 2 — Criar um produto

​Passo 3 — Criar um preço

​Passo 4 — Criar a sessão de checkout

​E agora?

Receba notificação quando pagar

Entenda os erros

Paginação

Referência completa

Antes de começar

Passo 1 — Criar um cliente

Localizar um cliente existente

Passo 2 — Criar um produto

Passo 3 — Criar um preço

Passo 4 — Criar a sessão de checkout

E agora?