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/A | Integer | ID do Cliente. | |
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 | |
customer_ignore_email | Não | Boolean | Nunca enviar e-mail para este cliente | |
customer_ignore_sms | Não | Boolean | Nunca enviar SMS para este cliente | |
customer_contact_person | Não | String | 120 | Contato do Pagador |
customer_update | Não | Boolean | Atualizar dados no cadastro 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 | 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 | Não | 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). | |
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 |
|
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). | |
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. |
guarantor_name | Não | String | 100 | Nome do Benecifiário final (Sacador/Avalista) |
guarantor_cnpj_cpf | Não | String | 20 | CNPJ/CPF do Benecifiário final (Sacador/Avalista) |
guarantor_zipcode | Não | String | 8 | CEP (formato 99999999) do Benecifiário final (Sacador/Avalista) |
guarantor_address | Não | String | 255 | Endereço do Benecifiário final (Sacador/Avalista) |
guarantor_city_name | Não | String | 60 | Cidade(Nome deve estar correto e completo) do Benecifiário final (Sacador/Avalista) |
guarantor_state | Não | String | 2 | Estado do Benecifiário final (Sacador/Avalista) |
guarantor_neighborhood | Não | String | 80 | Bairro do Benecifiário final (Sacador/Avalista) |
guarantor_address_number | Não | String | 10 | Número do Benecifiário final (Sacador/Avalista) |
guarantor_address_complement | Não | String | 60 | Complemento do Benecifiário final (Sacador/Avalista) |
guarantor_phone_number | Não | String | 11 | Telefone (com DDD) do Benecifiário final (Sacador/Avalista) |
payment_count | Não | Integer | Quantidade de pagamentos parciais. | |
days_for_sue | Não | Integer | Dias corridos para Protesto | |
days_for_revoke | Não | Integer | Dias corridos para Baixa/Devolução | |
days_for_negativation | Não | Integer | Dias corridos para Negativação (mais) |
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 |
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://api-sandbox.kobana.com.br/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://api-sandbox.kobana.com.br/v1/customer_subscriptions'Resposta:
HTTP/1.1 201 Created Date: Fri, 17 Oct 2014 19:30:06 GMT Status: 201 Created Location: https://api-sandbox.kobana.com.br/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" }
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://api-sandbox.kobana.com.br/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" }
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://api-sandbox.kobana.com.br/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://api-sandbox.kobana.com.br/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://api-sandbox.kobana.com.br/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://api-sandbox.kobana.com.br/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://api-sandbox.kobana.com.br/v1/customer_subscriptions?page=3&per_page=50>; rel="last", <https://api-sandbox.kobana.com.br/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" } ]
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://api-sandbox.kobana.com.br/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" }
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://api-sandbox.kobana.com.br/v1/customer_subscriptions/1'Resposta:
HTTP/1.1 204 No Content Date: Fri, 17 Oct 2014 19:30:06 GMT Status: 204 No Content ...