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.

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 (Maximo de 250)

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