API docs by Redocly

API - Simplo (1.0.0)

Download OpenAPI specification:

Simplo: team@besimplo.com URL: https://besimplo.com

API para cobrança e assinaturas para contas Simplo

Clientes

Clientes são as pessoas que pagarão pelos produtos da sua conta

Criar novo cliente

Criar novo cliente na sua conta

Authorizations:
apiKeyAuth
Request Body schema: application/json
required

Dados do cliente que será criado

required
object

Responses

Request samples

Content type
application/json
{
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "customer",
  • "live_mode": true,
  • "external_code": "01953808-3a3a-712f-99ce-f6943c8141db",
  • "created": 1680893993,
  • "identifier": "123.456.789-00",
  • "name": "João Silva",
  • "email": "joao.silva@exemplo.com",
  • "phone": "+5511999998888",
  • "description": "individual",
  • "address": {
    }
}

Consultar cliente

Consultar dados de um cliente existente na sua conta

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

ID do cliente.

Responses

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "customer",
  • "live_mode": true,
  • "external_code": "01953808-3a3a-712f-99ce-f6943c8141db",
  • "created": 1680893993,
  • "identifier": "123.456.789-00",
  • "name": "João Silva",
  • "email": "joao.silva@exemplo.com",
  • "phone": "+5511999998888",
  • "description": "individual",
  • "address": {
    }
}

Atualizar cliente

Atualizar dados de um cliente existente na sua conta

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

ID do cliente.

Request Body schema: application/json
required

Dados do cliente que serão atualizados

required
object

Responses

Request samples

Content type
application/json
{
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "customer",
  • "live_mode": true,
  • "external_code": "01953808-3a3a-712f-99ce-f6943c8141db",
  • "created": 1680893993,
  • "identifier": "123.456.789-00",
  • "name": "João Silva",
  • "email": "joao.silva@exemplo.com",
  • "phone": "+5511999998888",
  • "description": "individual",
  • "address": {
    }
}

Produtos

Produtos representam os bens ou serviços que você vende

Criar produto

Cria um novo produto que pode ter preços associados.

Produtos representam os bens ou serviços que você vende. Preços são então associados aos Produtos para definir opções de precificação.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "product": {
    }
}

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "product",
  • "active": true,
  • "created": 1680893993,
  • "live_mode": false,
  • "name": "Plano Premium",
  • "description": "Acesso a todas as funcionalidades premium",
  • "external_code": "prod_premium"
}

Listar produtos

Retorna uma lista paginada de produtos da conta.

Authorizations:
apiKeyAuth
query Parameters
active
boolean

Filtrar por status ativo/inativo

limit
integer [ 1 .. 100 ]
Default: 20

Resultados por página

page
string

Cursor para próxima página

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/api/v1/products",
  • "has_more": false,
  • "data": [
    ]
}

Buscar produto

Retorna um produto pelo seu ID (UUID).

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>

UUID do produto

Responses

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "product",
  • "active": true,
  • "created": 1680893993,
  • "live_mode": false,
  • "name": "Plano Premium",
  • "description": "Acesso a todas as funcionalidades premium",
  • "external_code": "prod_premium"
}

Atualizar produto

Atualiza um produto existente.

Apenas os campos enviados serão atualizados. Campos não enviados mantêm seus valores atuais.

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>

UUID do produto

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "product": {
    }
}

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "product",
  • "active": true,
  • "created": 1680893993,
  • "live_mode": false,
  • "name": "Plano Premium",
  • "description": "Acesso a todas as funcionalidades premium",
  • "external_code": "prod_premium"
}

Preços

Preços definem quanto cobrar e a frequência de cobrança de um Produto

Criar preço

Cria um novo preço associado a um produto.

  • Para cobranças recorrentes, use type: recurring e inclua o objeto recurring
  • Para cobranças únicas, use type: one_time
  • O valor é em centavos (ex: 2990 = R$ 29,90)
Authorizations:
apiKeyAuth
Request Body schema: application/json
required

Dados do preço que será criado

required
object

Responses

Request samples

Content type
application/json
Example
{
  • "price": {
    }
}

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "price",
  • "active": true,
  • "live_mode": true,
  • "created": 1704672000,
  • "currency": "brl",
  • "description": "Plano Mensal Premium",
  • "product": "550e8400-e29b-41d4-a716-446655440001",
  • "type": "recurring",
  • "unit_amount": 2990,
  • "unit_amount_decimal": "2990",
  • "recurring": {
    },
  • "external_code": "price_premium_monthly"
}

Listar preços

Retorna uma lista paginada de preços da conta.

Authorizations:
apiKeyAuth
query Parameters
active
boolean

Filtrar por status ativo/inativo

product_id
string <uuid>

Filtrar por UUID do produto

type
string
Enum: "one_time" "recurring"

Filtrar por tipo de cobrança

limit
integer [ 1 .. 100 ]
Default: 20

Resultados por página

page
string

Cursor para próxima página

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/api/v1/prices",
  • "has_more": false,
  • "data": [
    ]
}

Buscar preço

Retorna um preço pelo ID

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>

UUID do preço

Responses

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "price",
  • "active": true,
  • "live_mode": true,
  • "created": 1704672000,
  • "currency": "brl",
  • "description": "Plano Mensal Premium",
  • "product": "550e8400-e29b-41d4-a716-446655440001",
  • "type": "recurring",
  • "unit_amount": 2990,
  • "unit_amount_decimal": "2990",
  • "recurring": {
    },
  • "external_code": "price_premium_monthly"
}

Atualizar preço

Atualiza um preço existente.

Campos imutáveis: unit_amount, type, recurring não podem ser alterados após criação.

Para alterar esses campos, crie um novo preço e desative o antigo.

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>

UUID do preço

Request Body schema: application/json
required

Dados do preço que serão atualizados

required
object

Responses

Request samples

Content type
application/json
{
  • "price": {
    }
}

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "price",
  • "active": true,
  • "live_mode": true,
  • "created": 1704672000,
  • "currency": "brl",
  • "description": "Plano Mensal Premium",
  • "product": "550e8400-e29b-41d4-a716-446655440001",
  • "type": "recurring",
  • "unit_amount": 2990,
  • "unit_amount_decimal": "2990",
  • "recurring": {
    },
  • "external_code": "price_premium_monthly"
}

Assinaturas

Assinaturas conectam clientes aos seus planos para cobrança recorrente

Criar nova assinatura

Criar nova assinatura na sua conta conectando um Cliente e um Preço existentes

Authorizations:
apiKeyAuth
Request Body schema: application/json
required

Dados da assinatura que será criada

required
object

Responses

Request samples

Content type
application/json
{
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "subscription",
  • "external_code": "ACCOUNT-SUB-XYZ",
  • "billing_cycle_anchor": 1764039600,
  • "created": 1764040287,
  • "customer": "019ab8fe-9c70-7ba7-9055-1061d0543f26",
  • "payment_method_type": "card",
  • "current_period_start": 1764039600,
  • "latest_invoice": "019ab8fe-9ce9-78bd-acce-55868b790d8c",
  • "discounts": {
    },
  • "ended": null,
  • "item": {
    },
  • "start_date": 1764039600,
  • "status": "active"
}

Consultar assinatura

Consultar dados de uma assinatura existente na sua conta

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

ID da assinatura

Responses

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "subscription",
  • "external_code": "ACCOUNT-SUB-XYZ",
  • "billing_cycle_anchor": 1764039600,
  • "created": 1764040287,
  • "customer": "019ab8fe-9c70-7ba7-9055-1061d0543f26",
  • "payment_method_type": "card",
  • "current_period_start": 1764039600,
  • "latest_invoice": "019ab8fe-9ce9-78bd-acce-55868b790d8c",
  • "discounts": {
    },
  • "ended": null,
  • "item": {
    },
  • "start_date": 1764039600,
  • "status": "active"
}

Cancelar assinatura

Cancela imediatamente uma assinatura existente, encerrando todas as cobranças pendentes

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

ID da assinatura

Responses

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "subscription",
  • "external_code": "ACCOUNT-SUB-XYZ",
  • "billing_cycle_anchor": 1764039600,
  • "created": 1764040287,
  • "customer": "019ab8fe-9c70-7ba7-9055-1061d0543f26",
  • "payment_method_type": "card",
  • "current_period_start": 1764039600,
  • "latest_invoice": "019ab8fe-9ce9-78bd-acce-55868b790d8c",
  • "discounts": {
    },
  • "ended": null,
  • "item": {
    },
  • "start_date": 1764039600,
  • "status": "inactive"
}

Finalizar checkout da assinatura

Ativa uma assinatura fornecendo um método de pagamento e efetuando a cobrança.

Este endpoint permite completar o processo de checkout de uma assinatura pendente, associando um método de pagamento e processando a primeira cobrança imediatamente.

Tipos de pagamento suportados:

  • card: Cartão de crédito
  • pix: Pagamento instantâneo via PIX (QR Code)

Fluxo para cartão de crédito:

  1. Valida os dados do cartão e informações de cobrança
  2. Cria o método de pagamento associado ao cliente
  3. Processa a cobrança do cartão
  4. Retorna a assinatura ativada com os detalhes do método de pagamento

Fluxo para PIX:

  1. Gera um QR code PIX sincronamente
  2. Retorna o QR code, código copia-e-cola e data de expiração
  3. O pagamento é confirmado via webhook quando o cliente pagar
  4. Se chamado novamente enquanto o PIX estiver válido, retorna o mesmo (idempotente)
  5. Se o PIX expirou, gera um novo automaticamente
Authorizations:
apiKeyAuth
path Parameters
subscription_id
required
string <uuid>
Example: 019ab8fe-9ce9-78bd-acce-55868b790d7b

ID único (UUID) da assinatura a ser finalizada

Request Body schema: application/json
required

Dados do método de pagamento para finalizar o checkout.

O campo type determina qual método de pagamento será utilizado.

Para type: card: requer os objetos card e billing_details. Para type: pix: não requer campos adicionais.

type
required
string
Enum: "card" "pix"

Tipo de método de pagamento a ser utilizado.

Valores suportados:

  • card: Cartão de crédito
  • pix: Pagamento instantâneo via PIX (QR Code)
object

Dados do cartão de crédito para processamento do pagamento.

Segurança: Os dados do cartão são tokenizados e nunca armazenados em texto claro. Apenas os últimos 4 dígitos e a bandeira são mantidos para referência.

object

Informações do titular do cartão para validação e prevenção de fraude.

O nome e documento são obrigatórios. O endereço é opcional mas recomendado para aumentar a taxa de aprovação das transações.

Responses

Request samples

Content type
application/json
Example

Gera um QR code PIX para pagamento instantâneo

{
  • "type": "pix"
}

Response samples

Content type
application/json
Example

Retorna o QR code PIX para pagamento

{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "subscription",
  • "created": 1764040287,
  • "current_period_end": 1766632287,
  • "current_period_start": 1764040287,
  • "customer": "019ab8fe-9c70-7ba7-9055-1061d0543f26",
  • "payment_method": {
    },
  • "status": "active"
}

Checkout

Sessões de checkout permitem que clientes completem pagamentos e assinaturas através de uma interface web

Criar nova sessão de checkout

Criar nova sessão de checkout na sua conta. A sessão permite que um cliente complete um pagamento ou assinatura através de uma interface web.

Limite de taxa: 10 requisições por minuto por chave de API.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required

Dados da sessão de checkout que será criada

required
object

Responses

Request samples

Content type
application/json
{
  • "session": {
    }
}

Response samples

Content type
application/json
{}

Faturas

Faturas representam cobranças geradas para clientes

Listar todas as faturas

Retorna uma lista paginada de faturas.

Authorizations:
apiKeyAuth
query Parameters
customer
string <uuid>

Filtrar por UUID do cliente

subscription
string <uuid>

Filtrar por UUID da assinatura

status
string
Enum: "draft" "open" "paid" "uncollectible" "void"

Filtrar por status

limit
integer [ 1 .. 100 ]
Default: 20

Resultados por página

page
string

Cursor para próxima página

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "/api/v1/invoices",
  • "has_more": false,
  • "data": [
    ]
}

Reembolsos

Reembolsos permitem devolver pagamentos já realizados aos clientes

Criar reembolso

Cria um reembolso para um pagamento existente. O reembolso será processado de acordo com o método de pagamento:

  • Cartão de crédito: Reembolso síncrono, status final retornado imediatamente.
  • PIX: Reembolso assíncrono, status inicial será "refunding" e atualizado via webhook quando concluído.
Authorizations:
apiKeyAuth
Request Body schema: application/json
required

Dados do reembolso a ser criado

required
object

Responses

Request samples

Content type
application/json
{
  • "refund": {
    }
}

Response samples

Content type
application/json
{
  • "id": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "object": "refund",
  • "amount": 9990,
  • "currency": "brl",
  • "payment_intent": "019ab8fe-9ce9-78bd-acce-55868b790d7b",
  • "status": "refunded",
  • "live_mode": true,
  • "created": 1704672000
}