Documentação para Desenvolvedores

Carnês

Recurso Descrição
POST /api/v1/installments Criar carnê
GET /api/v1/installments/:id Informações do carnê
GET /api/v1/installments Listar Carnês
DELETE /api/v1/installments/:id Excluir carnê

Modelo de Dados

Parâmetro Obrigatório Tipo Tamanho Descrição
id N/A Integer   ID do carnê
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 255 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_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
customer_person_type N/A String 10 Tipo de pagador (possíveis valores)
bank_billet_account_id Sim Integer   ID da Carteira de Cobrança. Se não informado, usará a carteira padrão.
amount Sim String   Valor do carnê (R$) Formato: 1.234,34
cycle Não String 20 Ciclo do carnê (possíveis valores). Default: monthly
start_at Sim Date   Data da Primeira cobrança.
end_at Não Date   Data da última cobrança.
total Sim Integer   Quantidade de parcelas.
description Sim Text   Descrição do produto vendido ou serviço prestado.
instructions Não Text   Instruções para o caixa
status N/A String   Situação do carnê (possíveis valores)
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_percentage
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
url N/A String   URL para visualização do carnê
bank_billet_ids N/A Array   IDs de boletos vinculados ao carnê
notes Não Text   Anotações
tags Não Array   Tags associadas
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

status

created Gerando
processed Aberto
finished Finalizado

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 carnê

POST /api/v1/installments

Exemplo de requisição inválida

Requisição:
curl -i \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-d '{"installment":{}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/installments'
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":{"installment":["não pode ficar em branco"]}}

Exemplo de requisição válida

Requisição:
  curl -i \
  -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
  -d '{"installment":{"customer_id":"1", "bank_billet_account_id": "1", "amount": "1.120,4", "cycle": "monthly", "start_at": "2016-09-15", "total": "3", "description": "Hospedagem"}}' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp (myapp@example.com)' \
  -X POST 'https://sandbox.boletosimples.com.br/api/v1/installments'
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/installments/1
Content-Type: application/json; charset=utf-8
...

{
  "id":1,
  "amount":1120.4,
  "cycle":"monthly",
  "start_at":"2016-09-15",
  "end_at":"2016-11-16",
  "instructions":null,
  "customer_id":11,
  "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,
  "description":"Hospedagem",
  "created_at":"2016-08-15",
  "updated_at":"2016-08-15",
  "created_via_api":true,
  "total":3,
  "bank_billet_account_id":12,
  "status":"created",
  "fine_for_delay": 0.0,
  "late_payment_interest": 0.0
}

Informações do carnê

GET /api/v1/installments/: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/installments/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",
  "start_at":"2016-09-15",
  "end_at":"2016-11-16",
  "instructions":null,
  "customer_id":11,
  "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,
  "description":"Hospedagem",
  "created_at":"2016-08-15",
  "updated_at":"2016-08-15",
  "created_via_api":true,
  "total":3,
  "bank_billet_account_id":12,
  "status":"created",
  "fine_for_delay": 0.0,
  "late_payment_interest": 0.0
}

Listar Carnês

GET /api/v1/installments

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/installments?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/installments?page=3&per_page=50>; rel="last", <https://sandbox.boletosimples.com.br/api/v1/installments?page=2&per_page=50>; rel="next"
Total: 101
Content-Type: application/json; charset=utf-8
...

[
  {
    "id":1,
    "amount":1120.4,
    "cycle":"monthly",
    "start_at":"2016-09-15",
    "end_at":"2016-11-16",
    "instructions":null,
    "customer_id":11,
    "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,
    "description":"Hospedagem",
    "created_at":"2016-08-15",
    "updated_at":"2016-08-15",
    "created_via_api":true,
    "total":3,
    "bank_billet_account_id":12,
    "status":"created",
    "fine_for_delay": 0.0,
    "late_payment_interest": 0.0
  }
]

Excluir carnê

DELETE /api/v1/installments/:id

Nenhum boleto gerado pela carnê 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/installments/1'
Resposta:
HTTP/1.1 204 No Content
Date: Fri, 17 Oct 2014 19:30:06 GMT
Status: 204 No Content
...