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_for_delay Não Float   Multa por Atraso Ex: 2% x R$ 250,00 = R$ 5,00
late_payment_interest Não Float   Juros de Mora Mensal (O valor será dividido por 30. Ex 3% = 0,1% ao dia.)
bank_billet_layout_id Não Integer   ID do Modelo de Boleto
bank_billet_ids Não Array   IDs de boletos vinculados a assinatura

Dicionário de Dados

cycle

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

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
...