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 Obrigatório Tipo Tamanho Descrição
id N/A Integer   ID da assinatura
customer_id Não Integer   ID do Cliente. Quando esse ID é passado, os campos customer_person_name, customer_cnpj_cpf, customer_zipcode, customer_address, customer_city_name, customer_state e customer_neighborhood não são obrigatórios.
customer_person_name Sim String 120 Nome ou Razão Social do Pagador
customer_nickname Não String 255 Apelido ou Nome Fantasia do Pagador
customer_cnpj_cpf Sim String 20 CNPJ ou CPF do Pagador
customer_zipcode Sim Integer 8 CEP (formato 99999999)
customer_email Não String 80 E-mail do Pagador
customer_email_cc Não String 80 E-mail alternativo do Pagador
customer_address Sim String 25 Endereço
customer_city_name Sim String 60 Cidade(Nome deve estar correto e completo)
customer_state Sim String 2 Estado
customer_neighborhood Sim String 80 Bairro
customer_address_number Não String 10 Número
customer_address_complement Não String 60 Complemento
customer_phone_number Não String 11 Telefone (com DDD)
customer_person_type N/A String 10 Tipo de pagador (possíveis valores)
customer_mobile_local_code Não String 2 DDD do Celular
customer_mobile_number Não String 9 Celular
customer_notes Não Text   Anotações do Pagador
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   Valor 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
days_for_fine Não Integer   Quantidade de dias após o vencimento que a multa começará a incidir. O valor default é 1 dia (o dia posterior ao vencimento).
fine_for_delay Não Float   Alias para fine_percentage
interest_type Não Integer   Tipo de juros (possíveis valores)
interest_percentage Não Float   Porcentagem diária de juros. De 0.0 a 100.0 (Ex 1.5% = 1.5) Obrigatório se interest_type é igual a 1.
interest_value Não String   Valor diário de juros. Obrigatório se interest_type é igual a 2. (R$) Formato: 1.234,34
interest_daily_percentage Não Float   Porcentagem diária de juros. De 0.0 a 100.0 (Ex 1.5% = 1.5) Obrigatório se interest_type é igual a 1 ou 3. ATENÇÃO Este atributo está descontinuado e será removido do sistema em breve. Utilize interest_percentage.
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. ATENÇÃO Este atributo está descontinuado e será removido do sistema em breve. Utilize interest_value.
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. ATENÇÃO Este atributo está descontinuado e será removido do sistema em breve. Utilize interest_percentage passando a taxa diária.
days_for_interest Não Integer   Quantidade de dias após o vencimento que a mora começará a incidir. O valor default é 1 dia (o dia posterior ao vencimento).
late_payment_interest Não Float   Alias para interest_monthly_percentageao dia.)
discount_type Não Integer   Tipo de desconto. O tipo será o mesmo para todos os três descontos, caso existam. (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
second_discount_value Não String   Valor do segundo desconto. (R$) Formato: 1.234,34.
second_discount_percentage Não Float   Percentual do valor do boleto equivalente ao segundo desconto.
days_for_second_discount Não Integer   Dias para segundo desconto.
third_discount_value Não String   Valor do terceiro desconto. (R$) Formato: 1.234,34
third_discount_percentage Não Float   Percentual do valor do boleto equivalente ao terceiro desconto.
days_for_third_discount Não Integer   Dias para terceiro desconto.
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
prevent_registration Não Boolean   Caso true, impede que o boleto seja registrado. Para ser usado nos casos em que o boleto já foi registrado fora do Boleto Simples mas deseja-se incluí-lo no sistema.
divergent_payment_type Não Integer   Tipo de pagamento divergente. Válido apenas para Itaú e Caixa. (possíveis valores)
divergent_payment_value_type Não Integer   Tipo de valor a considerar para os limites de pagamentos. Válido apenas para Itaú e Caixa. (possíveis valores)
divergent_payment_minimum_value Não Float   Valor mínimo para a faixa de pagamentos divergentes. Válido apenas para Itaú e Caixa.
divergent_payment_maximum_value Não Float   Valor máximo para a faixa de pagamentos divergentes. Válido apenas para Itaú e Caixa.
divergent_payment_minimum_percentage Não Float   Percentual mínimo para a faixa de pagamentos divergentes. Válido apenas para Itaú e Caixa.
divergent_payment_maximum_percentage Não Float   Percentual máximo para a faixa de pagamentos divergentes. Válido apenas para Itaú e Caixa.
divergent_payment_limit Não Integer   Quantidade de pagamentos permitida. Obrigatório se informados dados para pagamento divergente. Usado somente pela Caixa.
custom_attachment_name Não String 255 Nome para ser usado nos arquivos de boleto enviados para o cliente em notificações. Aceita uso de variáveis. Caso seja deixado vazio, o padrão é a palavra “boleto” acompanhada do ID.

Dicionário de Dados

cycle

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

customer_person_type

individual Pessoa Física
juridical Pessoa Jurídica

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
2 Para valor diário
3 Para porcentagem diária após um dia útil. ATENÇÃO Esta opção está descontinuada e será removida do sistema em breve. Entradas com este valor estão sendo convertidas para 1.
4 Para valor diário após um dia útil. ATENÇÃO Esta opção está descontinuada e será removida do sistema em breve. Entradas com este valor estão sendo convertidas para 2.
5 Para porcentagem mensal após um dia corrido. ATENÇÃO Esta opção está descontinuada e será removida do sistema em breve. Entradas com este valor estão sendo convertidas para 1 e o valor da porcentagem recalculado de acordo.
6 Para porcentagem mensal após um dia útil. ATENÇÃO Esta opção está descontinuada e será removida do sistema em breve. Entradas com este valor estão sendo convertidas para 1 e o valor da porcentagem recalculado de acordo.

discount_type

discount_type

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

divergent_payment_type

1 Aceita qualquer valor divergente
2 Aceita pagamentos dentro de uma faixa de valores ou percentuais
3 Não aceita pagamento de valores divergentes
4 Aceita pagamentos de valores superiores a um valor ou percentual mínimo

divergent_payment_value_type

1 Informa pagamentos divergentes por valores
2 Informa pagamentos divergentes por percentuais

Criar assinatura

POST /api/v1/customer_subscriptions

Exemplo de requisição inválida

Requisição:
curl -i \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-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 \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-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",
 "customer_person_type":"individual",
 "customer_person_name":"Nome do Cliente",
 "customer_cnpj_cpf":"125.812.717-28",
 "customer_address":"Rua quinhentos",
 "customer_state":"RJ",
 "customer_neighborhood":"bairro",
 "customer_zipcode":"12312123",
 "customer_address_number":null,
 "customer_address_complement":null,
 "customer_phone_number":null,
 "customer_email":null,
 "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 \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-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",
 "customer_person_type":"individual",
 "customer_person_name":"Nome do Cliente",
 "customer_cnpj_cpf":"125.812.717-28",
 "customer_address":"Rua quinhentos",
 "customer_state":"RJ",
 "customer_neighborhood":"bairro",
 "customer_zipcode":"12312123",
 "customer_address_number":null,
 "customer_address_complement":null,
 "customer_phone_number":null,
 "customer_email":null,
 "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 \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-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 \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-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 Obrigatório Tipo Descrição
page Não Number Número da Página
per_page Não Number Quantidade de registros por página (Máximo de 50)

Exemplo

Requisição:
curl -i \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-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",
   "customer_person_type":"individual",
   "customer_person_name":"Nome do Cliente",
   "customer_cnpj_cpf":"125.812.717-28",
   "customer_address":"Rua quinhentos",
   "customer_state":"RJ",
   "customer_neighborhood":"bairro",
   "customer_zipcode":"12312123",
   "customer_address_number":null,
   "customer_address_complement":null,
   "customer_phone_number":null,
   "customer_email":null,
   "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 \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-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",
 "customer_person_type":"individual",
 "customer_person_name":"Nome do Cliente",
 "customer_cnpj_cpf":"125.812.717-28",
 "customer_address":"Rua quinhentos",
 "customer_state":"RJ",
 "customer_neighborhood":"bairro",
 "customer_zipcode":"12312123",
 "customer_address_number":null,
 "customer_address_complement":null,
 "customer_phone_number":null,
 "customer_email":null,
 "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 \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-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
...