Documentação para Desenvolvedores

Assinaturas

Recurso Descrição
POST /api/v1/customer_subscriptions Criar assinatura
GET /api/v1/customer_subscriptions/:id Informações da assinatura
PATCH /api/v1/customer_subscriptions/:id Atualizar assinatura
PUT /api/v1/customer_subscriptions/:id Atualizar assinatura
GET /api/v1/customer_subscriptions Listar assinaturas
POST /api/v1/customer_subscriptions/:id/next_charge Gerar próxima cobrança
DELETE /api/v1/customer_subscriptions/:id Excluir assinatura

Modelo de Dados

Parâmetro Obr. Tipo Tamanho Descrição
id N/A Integer   ID da assinatura
customer_id Sim Integer   ID do Cliente
bank_billet_account_id Não Integer   ID da Carteira de Cobrança. Se não informado, usará a carteira padrão.
amount Sim String   Preço da Assinatura (R$) Formato: 1.234,34
cycle Não String 20 Ciclo da carnê (possíveis valores). Default: monthly
next_billing Não Date   Data da Primeira ou Próxima cobrança. Caso não seja enviado uma data, esse campo será calculado para ter o valor do dia da criação da assinatura mais o ciclo escolhido. Ex.: Mensal(Hoje + 30 dias)
end_at Não Date   Data em que deseja parar as cobranças. Caso em branco, as cobranças serão geradas automaticamente até que se informe uma data ou se exclua a assinatura.
description Sim Text   Descrição do produto vendido ou serviço prestado.
instructions Não Text   Instruções para o caixa
days_in_advance Não Integer   Com quantos dias de antecedência à data de vencimento a cobrança será gerada. Default: 7.
fine_type Não Integer   Tipo de multa (possíveis valores)
fine_percentage Não Float   Porcentagem de Multa por Atraso Ex: 2% x R$ 250,00 = R$ 5,00. Obrigatória se fine_type é igual a 1
fine_value Não String   Valor da multa. Obrigatório se fine_type é igual a 2. (R$) Formato: 1.234,34
fine_for_delay Não Float   Alias para fine_percentage
interest_type Não Integer   Tipo de juros (possíveis valores)
interest_daily_percentage Não Float   Porcentagem diária de juros. Obrigatório se interest_type é igual a 1 ou 3
interest_daily_value Não String   Valor diário de juros. Obrigatório se interest_type é igual a 2 ou 4. (R$) Formato: 1.234,34
interest_monthly_percentage Não Float   Juros de mora mensal (O valor será dividido por 30. Ex 3% = 0,1% ao dia.) Obrigatório se interest_type é igual a 5 ou 6
late_payment_interest Não Float   Alias para interest_monthly_percentageao dia.)
discount_type Não Integer   Tipo de desconto (possíveis valores)
discount_value Não String   Valor do desconto. Obrigatório se discount_type é igual a 1. (R$) Formato: 1.234,34
discount_percentage Não Float   Percentual do valor do boleto equivalente ao desconto. Obrigatório se discount_type é igual a 2
days_for_discount Não Integer   Dias para desconto. Obrigatório se discount_type é diferente de zero
bank_billet_layout_id Não Integer   ID do Modelo de Boleto
notes Não Text   Anotações
tags Não Array   Tags associadas
bank_billet_ids N/A Array   IDs de boletos vinculados a assinatura

Dicionário de Dados

cycle

biweekly Quinzenal
bimonthly Bimestral
monthly Mensal
quarterly Trimestral
semiannual Semestral
annual Anual

fine_type

0 Inexistente (Padrão)
1 Para percentual do valor do boleto
2 Para valor fixo

interest_type

0 Inexistente (Padrão)
1 Para porcentagem diária após um dia corrido
2 Para valor diário após um dia corrido
3 Para porcentagem diária após um dia útil
4 Para valor diário após um dia útil
5 Para porcentagem mensal após um dia corrido
6 Para porcentagem mensal após um dia útil

discount_type

0 Inexistente (Padrão)
1 Para valor fixo
2 Para percentual do valor do boleto

Criar assinatura

POST /api/v1/customer_subscriptions

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"customer_subscription":{}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions'
Resposta:
HTTP/1.1 422 Unprocessable Entity
Date: Fri, 17 Oct 2014 18:39:47 GMT
Status: 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
...

{"errors":{"customer_subscription":["não pode ficar em branco"]}}

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"customer_subscription":{"customer_id":"1", "bank_billet_account_id": "1", "amount": "1.120,4", "cycle": "monthly", "description": "Hospedagem"}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions'
Resposta:
HTTP/1.1 201 Created
Date: Fri, 17 Oct 2014 19:30:06 GMT
Status: 201 Created
Location: https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions/1
Content-Type: application/json; charset=utf-8
...

{
 "id":1,
 "amount":1120.4,
 "cycle":"monthly",
 "next_billing":"2016-06-18",
 "end_at":null,
 "instructions":null,
 "description":"Hospedagem",
 "created_at":"2016-05-18",
 "updated_at":"2016-05-18",
 "created_via_api":true,
 "customer_id":"1",
 "bank_billet_account_id":"1",
 "days_in_advance": "7",
 "fine_for_delay": 0.0,
 "late_payment_interest": 0.0
}

Informações do assinatura

GET /api/v1/customer_subscriptions/:id

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET 'https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions/1'
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
 "id":1,
 "amount":1120.4,
 "cycle":"monthly",
 "next_billing":"2016-06-18",
 "end_at":null,
 "instructions":null,
 "description":"Hospedagem",
 "created_at":"2016-05-18",
 "updated_at":"2016-05-18",
 "created_via_api":true,
 "customer_id":"1",
 "bank_billet_account_id":"1",
 "days_in_advance": "7",
 "fine_for_delay": 0.0,
 "late_payment_interest": 0.0
}

Atualizar assinatura

PATCH /api/v1/customer_subscriptions/:id ou PUT /api/v1/customer_subscriptions/:id

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"customer_subscription":{"amount":""}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PATCH 'https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions/1'
Resposta:
HTTP/1.1 422 Unprocessable Entity
Date: Fri, 17 Oct 2014 18:39:47 GMT
Status: 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
...

{"errors":{"amount":["não pode ficar em branco"]}}

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"customer_subscription":{"amount":"120,40"}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PUT 'https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions/1'
Resposta:
HTTP/1.1 204 No Content
Content-Length: 0
Connection: keep-alive
Status: 204 No Content
Cache-Control: no-cache
X-Ratelimit-Limit: 500
Location: https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions/1

Listar assinaturas

GET /api/v1/customer_subscriptions

Parâmetro Obr. Tipo Descrição
page Não Number Número da Página
per_page Não Number Quantidade de registros por página (Maximo de 250)

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET "https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions?page=1&per_page=50"
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Link: <https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions?page=3&per_page=50>; rel="last", <https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions?page=2&per_page=50>; rel="next"
Total: 101
Content-Type: application/json; charset=utf-8
...

[
  {
   "id":1,
   "amount":1120.4,
   "cycle":"monthly",
   "next_billing":"2016-06-18",
   "end_at":null,
   "instructions":null,
   "description":"Hospedagem",
   "created_at":"2016-05-18",
   "updated_at":"2016-05-18",
   "created_via_api":true,
   "customer_id":"1",
   "bank_billet_account_id":"1",
   "days_in_advance": "7",
   "fine_for_delay": 0.0,
   "late_payment_interest": 0.0
  }
]

Gerar próxima cobrança

POST /api/v1/customer_subscriptions/:id/next_charge

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions/1/next_charge'
Resposta:
HTTP/1.1 201 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 201 OK
Content-Type: application/json; charset=utf-8
...

{
 "id":1,
 "amount":1120.4,
 "cycle":"monthly",
 "next_billing":"2016-07-18",
 "end_at":null,
 "instructions":null,
 "description":"Hospedagem",
 "created_at":"2016-05-18",
 "updated_at":"2016-05-18",
 "created_via_api":true,
 "customer_id":"1",
 "bank_billet_account_id":"1",
 "days_in_advance": "7",
 "fine_for_delay": 0.0,
 "late_payment_interest": 0.0
}

Excluir assinatura

DELETE /api/v1/customer_subscriptions/:id

Nenhum boleto gerado pela assinatura será excluído.

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X DELETE 'https://sandbox.boletosimples.com.br/api/v1/customer_subscriptions/1'
Resposta:
HTTP/1.1 204 No Content
Date: Fri, 17 Oct 2014 19:30:06 GMT
Status: 204 No Content
...