Introdução
Bem vindo a documentação da API Cobre Fácil.
Oferecemos uma solução completa para que você possa integrar ao seu sistema e utilizá-lo da melhor maneira possível no seu negócio.
Para utilizar nossa API é necessário ter uma conta na Cobre Fácil, caso ainda não tenha clique aqui.
Nesta documentação mostraremos os dados necessários para realizar uma requisição, os valores retornados e exemplos de códigos.
Caso tenha alguma dúvida ou precise de suporte acesse nossa página de ajuda.
Requisições e respostas
Exemplo básico do JSON retornado:
{
"success": true,
"data": {
...
}
}
Nossa API utiliza o padrão REST, todas as requisições e respostas são no formato JSON e os endpoints utilizam como base o endereço:
https://api.cobrefacil.com.br/v1/
Para indicar o sucesso ou falha nas requisições utilizamos códigos HTTP, no caso de requisições bem sucedidas o código é
o 201 quando um registro é criado ou 200 para indicar outras operações de sucesso, outros códigos representam algum tipo de erro.
Além disso, o JSON retornado contém um campo booleano chamado success que pode ser utilizado no lugar dos códigos para verificar o sucesso da operação.
A segurança no envio e recebimento dos dados é realizada através de autenticação via token.
Observações sobre tipos de campos para data
| Tipo | Observação |
|---|---|
Date |
utilizam o formato YYYY-MM-DD, exemplo 2020-01-30 |
DateTime |
geralmente retornados em created_at, updated_at e deleted_at utilizam o formato ISO 8601, exemplo 2020-01-30T12:34:56+00:00 |
Erros
Exemplo de retorno contendo o motivo do erro e dados adicionais:
{
"success": false,
"message": "Parâmetros inválidos.",
"errors": [
"Data de vencimento deve ser uma data maior ou igual a hoje.",
"O juros não pode ser maior que 3,3% ao dia."
]
}
Quando um erro é identificado o retorno da requisição conterá o código HTTP apropriado, que pode ser:
| Código | Descrição |
|---|---|
400 Bad Request |
Algum parâmetro obrigatório não foi enviado ou é inválido |
401 Unauthorized |
O token não foi enviado ou é inválido |
404 Not Found |
O endpoint ou o registro solicitado não existe |
500 Internal Server Error |
Algum problema no servidor da Cobre Fácil |
Além disso, o JSON retornado terá o campo success com o valor false e o campo message descreverá o motivo do erro,
em alguns casos também será retornado um array no campo errors contendo detalhes adicionais.
Autenticação
Para autenticar, utilize esse exemplo de código:
curl --location --request POST "https://api.cobrefacil.com.br/v1/authenticate" \
--header "Content-Type: application/json" \
--data "{
\"app_id\": \"meuapp_5dcae973d82c2\",
\"secret\": \"eba5893f056d7f0633838c1c475b89391ef72534\"
}"
Exemplo do JSON que será retornado:
{
"success": true,
"data": {
"token": "8c1301b8c246942b195dd4467846e10eb8ac9a18",
"expiration": 3600
}
}
A autenticação é feita através do envio de um token no header das requisições, exemplo:
Authorization: Bearer 8c1301b8c246942b195dd4467846e10eb8ac9a18
Para obter o token é necessário fazer uma requisição para o endpoint /authenticate enviando o seu app_id e secret, esses dados estão disponíveis no painel de sua conta na pagina /integrations.
Para ambiente de sandbox é necessario entrar em contato para solicitar as credenciais.
HTTP Request
POST https://api.cobrefacil.com.br/v1/authenticate
BODY Params
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
app_id |
String | Sim | Identificador da aplicação |
secret |
String | Sim | Chave secreta da aplicação |
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
token |
String | Token que deve ser utilizado nas requisições |
expiration |
Integer | Validade do token em segundos, após esse período será necessário obter um novo token |
Webhooks
JSON base de um evento enviado:
{
"event": "invoice.created",
"data": {
...
}
}
JSON de um evento referente a cobrança:
{
"event": "invoice.created",
"data": {
"id": "PQ9RDZ2376N7YMGJ8V1K",
"payable_with": "bankslip",
"due_date": "2020-12-15",
"price": 49.9,
"fine_delay": null,
"total_paid": null,
"amount_released": null,
"fee": null,
"paid_at": null,
"payment_method": null,
"document_number": null,
"barcode": "34191090570137951893731339210002284700000004990",
"barcode_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZUAAAAyCAYAAACUNUbZAAACHUlEQVR42u3V2wqAIAwA0P3/Txc9%0ABD6kuGkQcYIIb63W7EREHNfRXu+z126PUf9b657Gs/OycXrPPZo3u/5L93nqH9VDJS+7xnfX2Y78%0AVOq0uu9m5vfijdrV/Zep02q8mbytfJdM/Oy+XHmfal1V/4cr+Q+oQAUqUIEKVKACFahABSpQgQpU%0AoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKAC%0AFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWo%0AQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAF%0AKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQ%0AgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEK%0AVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSg%0AAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIV%0AqEAFKv9G5QSDfSad5j+EigAAAABJRU5ErkJggg==%0A",
"status": "pending",
"settings": null,
"items": [],
"customer": {
"id": "Z8J53ROD2JK1PQ47WG0E",
"person_type": 2,
"ein": null,
"company_name": "COBRE FACIL LTDA ME",
"taxpayer_id": "12345678909",
"personal_name": null,
"telephone": "11988887777",
"cellular": "11988887777",
"email": "exemplo@cobrefacil.com.br",
"email_cc": null,
"full_name": "COBRE FACIL LTDA ME",
"document": "12345678909",
"address": {
"id": "9W2LVGOPRJMR780DEJK1",
"description": "Endereço principal",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-04-03T11:31:52+00:00",
"updated_at": "2020-04-03T11:31:52+00:00",
"deleted_at": null
},
"created_at": "2020-04-03T11:31:52+00:00",
"updated_at": "2020-04-03T11:31:52+00:00",
"deleted_at": null
},
"created_at": "2020-04-03T13:54:59+00:00",
"updated_at": "2020-04-03T13:54:59+00:00"
}
}
O serviço de webhooks permite receber atualizações sobre eventos importantes em tempo real. Através deles é possível montar uma integração assíncrona com a Cobre Fácil, aumentando a escalabilidade da sua plataforma.
Para utilizar a notificação por webhooks é necessário cadastrar no painel da sua conta as URLs responsáveis por realizar o tratamento dos eventos que serão enviados.
Fluxo de retentativas de disparos
Uma vez que a primeira tentativa de entrega não obtém sucesso, será efetuado um novo disparo após 10 minutos. Após um número máximo de 6 tentativas sem sucesso o evento entrará em estado de falha na entrega.
Estrutura base do JSON enviado
| Atributo | Tipo | Descrição |
|---|---|---|
event |
String | Evento que disparou o envio das informações |
data |
Object | O objeto atualizado referente ao evento |
Eventos disponíveis
| Evento | Descrição |
|---|---|
invoice.created |
Cobrança criada |
invoice.viewed |
Cobrança visualizada |
invoice.reversed |
Cobrança cancelada por falha de comunicação com a adquirente aprovadora da transação |
invoice.declined |
Pagamento recusado |
invoice.pre_authorized |
Pagamento pré autorizado |
invoice.paid |
Cobrança paga |
invoice.refunded |
Cobrança estornada parcialmente |
invoice.canceled |
Cobrança estornada por completo ou cancelada |
invoice.dispute |
Disputa aberta para uma transação |
invoice.dispute_succeeded |
Vitória da disputa por parte do estabelecimento comercial |
invoice.charged_back |
Vitória da disputa por parte do portador do cartão |
| ------ | --------- |
subscription.canceled |
Mensalidade cancelada |
subscription.created |
Mensalidade criada |
subscription.paused |
Mensalidade pausada |
subscription.reactivated |
Mensalidade reativada |
subscription.terminated |
Mensalidade terminada |
| ------ | --------- |
tax_invoice.created |
Nota fiscal criada |
tax_invoice.rejected |
Nota fiscal rejeitada |
tax_invoice.denied |
Nota fiscal negada |
tax_invoice.actived |
Nota fiscal ativa |
tax_invoice.canceled |
Nota fiscal cancelada |
tax_invoice.cancellation_rejected |
Nota fiscal solicitação de cancelamento recusada |
Clientes
Nossa API permite criar, atualizar e remover seus
clientes.
Você também pode detalhar clientes individualmente ou listar clientes filtrando
os atributos desejados.
O objeto cliente
Exemplo de JSON do objeto cliente:
{
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "12345678909",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joao@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"full_name": "João da Silva",
"document": "12345678909",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "Endereço principal",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:52:48-03:00",
"deleted_at": null
},
"nfse": {
"inscricao_estadual": "123456789",
"iss_retido": true
},
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:52:48-03:00",
"deleted_at": null
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do cliente |
person_type |
Integer | 1 Pessoa física2 Pessoa jurídica |
ein |
String | CNPJ da empresa |
company_name |
String | Nome da empresa |
taxpayer_id |
String | CPF do cliente |
personal_name |
String | Nome do cliente |
telephone |
String | Telefone fixo |
cellular |
String | Telefone celular |
email |
String | E-mail do cliente |
email_cc |
String | E-mail que receberá cópias das mensagens enviadas |
full_name |
String | Nome completo do cliente |
document |
String | Documento do cliente (CPF ou CNPJ) |
address |
Object | Endereço |
address.id |
String | Identificador do endereço |
address.description |
String | Descrição do endereço |
address.zipcode |
String | CEP |
address.street |
String | Logradouro |
address.number |
String | Número |
address.complement |
String | Complemento |
address.neighborhood |
String | Bairro |
address.city |
String | Cidade |
address.state |
String | UF |
address.created_at |
DateTime | Data que o endereço foi criado |
address.updated_at |
DateTime | Data que o endereço foi atualizado |
address.deleted_at |
DateTime | Data que o endereço foi excluído |
nfse |
Object | Dados para geração de NFSe |
nfse.inscricao_estadual |
String | Inscrição estadual do tomador |
nfse.responsavel_retencao |
Integer | Responsável pela retenção, valores:1 Tomador2 Intermediário |
nfse.iss |
Object | Detalhamento do ISS |
nfse.iss.tipo_tributacao |
Integer | Tipo de Tributação do Serviço, valores:1 Isento de ISS2 Imune3 Não Incidência no Município4 Não Tributável5 Retido6 Tributável Dentro do Município7 Tributável Fora do Município8 Tributável Dentro do Município pelo tomador |
nfse.iss.exigibilidade |
Integer | Exigibilidade do ISS, valores:1 Exigível2 Não Incidência3 Isenção4 Exportação5 Imunidade6 Suspenso por Ação Judicial7 Suspenso por Ação Administrativa |
nfse.iss.retido |
Boolean | Reter ISS |
nfse.iss.processo_suspensao |
String | Número do Processo de Suspensão da Exigibilidade |
created_at |
DateTime | Data que o cliente foi criado |
updated_at |
DateTime | Data que o cliente foi atualizado |
deleted_at |
DateTime | Data que o cliente foi excluído |
Criar cliente
curl --location --request POST "https://api.cobrefacil.com.br/v1/customers" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"person_type\": 1,
\"taxpayer_id\": \"12345678909\",
\"personal_name\": \"João da Silva\",
\"telephone\": \"11999999999\",
\"cellular\": \"11888888888\",
\"email\": \"joao@cobrefacil.com.br\",
\"email_cc\": \"maria@cobrefacil.com.br\",
\"address\": {
\"description\": \"AP\",
\"zipcode\": \"01311000\",
\"street\": \"Avenida Paulista\",
\"number\": \"123\",
\"complement\": \"Ap 42\",
\"neighborhood\": \"Bela Vista\",
\"city\": \"São Paulo\",
\"state\": \"SP\"
}
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "12345678909",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joao@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "Endereço principal",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:52:48-03:00",
"deleted_at": null
},
"full_name": "João da Silva",
"document": "12345678909",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:52:48-03:00",
"deleted_at": null
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/customers
Body Params
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
person_type |
Integer | Sim | 1 Pessoa física2 Pessoa jurídica |
ein |
String | Se for pessoa jurídica | CNPJ da empresa |
company_name |
String | Se for pessoa jurídica | Nome da empresa |
taxpayer_id |
String | Se for pessoa física | CPF do cliente |
personal_name |
String | Se for pessoa física | Nome do cliente |
telephone |
String | Não | Telefone fixo |
cellular |
String | Não | Telefone celular |
email |
String | Não | E-mail do cliente |
email_cc |
String | Não | E-mail que receberá cópias das mensagens enviadas |
address |
Object | Sim | Endereço do cliente |
address.description |
String | Sim | Descrição do endereço |
address.zipcode |
String | Sim | CEP |
address.street |
String | Sim | Logradouro |
address.number |
String | Sim | Número |
address.complement |
String | Não | Complemento |
address.neighborhood |
String | Sim | Bairro |
address.city |
String | Sim | Cidade |
address.state |
String | Sim | UF |
nfse |
Object | Não | Endereço do cliente |
nfse.inscricao_estadual |
String | Não | Inscrição estadual do tomador |
nfse.responsavel_retencao |
Integer | Não | Responsável pela retenção, valores:1 Tomador2 Intermediário |
nfse.iss |
Object | Não | Detalhamento do ISS |
nfse.iss.tipo_tributacao |
Integer | Não | Tipo de Tributação do Serviço, valores:1 Isento de ISS2 Imune3 Não Incidência no Município4 Não Tributável5 Retido6 Tributável Dentro do Município7 Tributável Fora do Município8 Tributável Dentro do Município pelo tomador |
nfse.iss.exigibilidade |
Integer | Não | Exigibilidade do ISS, valores:1 Exigível2 Não Incidência3 Isenção4 Exportação5 Imunidade6 Suspenso por Ação Judicial7 Suspenso por Ação Administrativa |
nfse.iss.retido |
Boolean | Não | Reter ISS |
nfse.iss.processo_suspensao |
String | Não | Número do Processo de Suspensão da Exigibilidade |
Retorno
Em caso de sucesso será retornado um objeto cliente.
Atualizar cliente
curl --location --request PUT "https://api.cobrefacil.com.br/v1/customers" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"personal_name\": \"João da Silva Machado\",
\"email\": \"joaosilva@cobrefacil.com.br\",
\"address\": {
\"description\": \"AP 42\"
}
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "12345678909",
"personal_name": "João da Silva Machado",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joaosilva@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "AP 42",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
},
"full_name": "João da Silva Machado",
"document": "12345678909",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
}
}
Ao atualizar um cliente é necessário enviar apenas os dados que deseja alterar.
HTTP Request
PUT https://api.cobrefacil.com.br/v1/customers/[ID]
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador do cliente |
BODY Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
person_type |
Integer | Não | 1 Pessoa física2 Pessoa jurídica |
ein |
String | Não | CNPJ da empresa |
company_name |
String | Não | Nome da empresa |
taxpayer_id |
String | Não | CPF do cliente |
personal_name |
String | Não | Nome do cliente |
telephone |
String | Não | Telefone fixo |
cellular |
String | Não | Telefone celular |
email |
String | Não | E-mail do cliente |
email_cc |
String | Não | E-mail que receberá cópias das mensagens enviadas |
address |
Object | Não | Endereço do cliente |
address.description |
String | Não | Descrição do endereço |
address.zipcode |
String | Não | CEP |
address.street |
String | Não | Logradouro |
address.number |
String | Não | Número |
address.complement |
String | Não | Complemento |
address.neighborhood |
String | Não | Bairro |
address.city |
String | Não | Cidade |
address.state |
String | Não | UF |
nfse |
Object | Não | Endereço do cliente |
nfse.inscricao_estadual |
String | Não | Inscrição estadual do tomador |
nfse.responsavel_retencao |
Integer | Não | Responsável pela retenção, valores:1 Tomador2 Intermediário |
nfse.iss |
Object | Não | Detalhamento do ISS |
nfse.iss.tipo_tributacao |
Integer | Não | Tipo de Tributação do Serviço, valores:1 Isento de ISS2 Imune3 Não Incidência no Município4 Não Tributável5 Retido6 Tributável Dentro do Município7 Tributável Fora do Município8 Tributável Dentro do Município pelo tomador |
nfse.iss.exigibilidade |
Integer | Não | Exigibilidade do ISS, valores:1 Exigível2 Não Incidência3 Isenção4 Exportação5 Imunidade6 Suspenso por Ação Judicial7 Suspenso por Ação Administrativa |
nfse.iss.retido |
Boolean | Não | Reter ISS |
nfse.iss.processo_suspensao |
String | Não | Número do Processo de Suspensão da Exigibilidade |
Retorno
Em caso de sucesso será retornado um objeto cliente com os dados atualizados.
Detalhar cliente
curl --location --request GET "https://api.cobrefacil.com.br/v1/customers/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "12345678909",
"personal_name": "João da Silva Machado",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joaosilva@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "AP 42",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
},
"full_name": "João da Silva Machado",
"document": "12345678909",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
}
}
Para detalhar um cliente específico basta informar o ID retornado no momento da criação.
HTTP Request
GET https://api.cobrefacil.com.br/v1/customers/[ID]
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador do cliente |
Retorno
Em caso de sucesso será retornado um objeto cliente.
Listar clientes
curl --location --request GET "https://api.cobrefacil.com.br/v1/customers" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "12345678909",
"personal_name": "João da Silva Machado",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joaosilva@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"full_name": "João da Silva Machado",
"document": "12345678909",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "AP 42",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
},
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
}
]
}
Retorna uma lista paginada de clientes e seus respectivos endereços.
É possível controlar a paginação e realizar buscas através de parâmetros na URL, exemplos:
Buscar cliente pelo e-mail:
GET https://api.cobrefacil.com.br/v1/customers?email=joao@cobrefacil.com.br
Retornar 10 registros pulando os 10 primeiros:
GET https://api.cobrefacil.com.br/v1/customers?limit=10&offset=10
HTTP Request
GET https://api.cobrefacil.com.br/v1/customers
URL Parameters
| Parâmetro | Tipo | Descrição |
|---|---|---|
taxpayer_id |
String | Busca pelo CPF do cliente |
ein |
String | Busca pelo CNPJ da empresa |
email |
String | Busca pelo e-mail do cliente |
personal_name |
String | Busca pelo nome do cliente |
company_name |
String | Busca pelo nome da empresa |
sort_by |
String | Campo a ser utilizado na ordenação, o padrão é created_at |
order_by |
String | Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc |
limit |
Integer | Quantidade máxima de registros que devem ser retornados, o padrão é 100 |
offset |
Integer | Número de registros a serem pulados, o padrão é 0 |
Retorno
Em caso de sucesso será retornado um array de objetos cliente.
Remover cliente
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/customers/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "37673788250",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11999999999",
"email": "joao@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "Endereço principal",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T14:01:40-03:00",
"updated_at": "2020-06-25T16:41:03-03:00",
"deleted_at": "2020-06-25T16:41:03-03:00"
},
"full_name": "João da Silva",
"document": "37673788250",
"created_at": "2020-06-25T14:01:40-03:00",
"updated_at": "2020-06-25T16:41:03-03:00",
"deleted_at": "2020-06-25T16:41:03-03:00"
}
}
Ao remover um cliente as cobranças pertencentes a ele continuarão disponíveis para consulta, mas não será possível criar
novas cobranças para ele.
HTTP Request
DELETE https://api.cobrefacil.com.br/v1/customers/[ID]
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador do cliente |
Retorno
Em caso de sucesso será retornado um objeto cliente com os dados atualizados.
Cartão de crédito
Oferecemos a possibilidade de armazenar um ou vários cartões de um cliente para que seja realizada a cobrança posteriormente.
Além disso, utilizamos tokenização para proteger os dados dos cartões, cumprindo os padrões de segurança da indústria.
Cartões para teste
Para testar sua integração sem ter que utilizar cartões de crédito verdadeiros em ambiente de produção, você pode utilizar o nosso ambiente de testes e os números que fornecemos para simular determinadas situações.
| Número | Resultado esperado |
|---|---|
| 4539003370725497 | Transação autorizada - Bandeira Visa |
| 5356066320271893 | Transação autorizada - Bandeira Mastercard |
| 6011457819940087 | Transação negada |
Não utilize esses números de cartões no ambiente de produção.
O objeto cartão
Exemplo de JSON do objeto cartão:
{
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 1,
"brand": "visa",
"first6_digits": "453900",
"last4_digits": "5497",
"expiration_year": "2020",
"expiration_month": "12",
"created_at": "2020-06-25T10:06:10-03:00",
"updated_at": "2020-06-25T10:06:17-03:00",
"deleted_at": null
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do cartão |
customer_id |
String | Identificador do cliente |
default |
Integer | Informa se é o cartão padrão da conta, 1 sim e 0 não |
brand |
String | Bandeira do cartão, visa e mastercard |
first6_digits |
String | Primeiros 6 dígitos do número do cartão |
last4_digits |
String | Últimos 4 dígitos do número do cartão |
expiration_month |
String | Mês de expiração do cartão |
expiration_year |
String | Ano de expiração do cartão |
created_at |
String | Data que o cartão foi cadastrado |
updated_at |
String | Data que o cartão foi atualizado |
deleted_at |
String | Data que o cartão foi excluído |
Criar cartão
curl --location --request POST "https://api.cobrefacil.com.br/v1/cards" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"customer_id\": \"Z8J53ROD2JK1PQ47WG0E\",
\"default\": 1,
\"name\": \"João da Silva\",
\"number\": \"4539003370725497\",
\"expiration_month\": \"12\",
\"expiration_year\": \"2020\",
\"security_code\": \"123\"
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 1,
"brand": "visa",
"first6_digits": "453900",
"last4_digits": "5497",
"expiration_year": "2020",
"expiration_month": "12",
"created_at": "2020-06-25T10:06:10-03:00",
"updated_at": "2020-06-25T10:06:17-03:00",
"deleted_at": null
}
}
Ao criar um novo cartão de crédito deve ser informado o cliente que poderá utilizar o cartão para pagamentos.
Se o cliente informado não possuir um cartão padrão, o novo cartão cadastrado se tornará o padrão dele.
Caso deseje alterar o cartão padrão de um cliente, utilize a opção definir cartão padrão.
HTTP Request
POST https://api.cobrefacil.com.br/v1/cards
Body Params
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
customer_id |
String | Sim | Identificação do cliente |
default |
Integer | Não | Define se é o cartão padrão da conta, 1 sim e 0 não |
name |
String | Sim | Nome do portador do cartão |
number |
String | Sim | Número do cartão |
expiration_month |
String | Sim | Mês de expiração do cartão, deve conter 2 dígitos |
expiration_year |
String | Sim | Ano de expiração do cartão, deve conter 4 dígitos |
security_code |
String | Sim | Código de segurança do cartão |
Retorno
Em caso de sucesso será retornado um objeto cartão.
Definir cartão padrão
O único dado de um cartão que pode ser alterado após o seu cadastro, é o campo default, para isso oferecemos
esse endpoint que sempre que for chamado altera o cartão padrão de um usuário para o que foi informado na requisição.
curl --location --request POST "https://api.cobrefacil.com.br/v1/cards/[ID]/default" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 0,
"brand": "visa",
"first6_digits": "453900",
"last4_digits": "5497",
"expiration_year": "2020",
"expiration_month": "12",
"created_at": "2020-06-25T10:06:10-03:00",
"updated_at": "2020-06-25T10:09:01-03:00",
"deleted_at": null
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/cards/[ID]/default
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador do cartão |
Retorno
Em caso de sucesso será retornado um objeto cartão.
Detalhar cartão
curl --location --request GET "https://api.cobrefacil.com.br/v1/cards/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 0,
"brand": "visa",
"first6_digits": "453900",
"last4_digits": "5497",
"expiration_year": "2020",
"expiration_month": "12",
"created_at": "2020-06-25T10:06:10-03:00",
"updated_at": "2020-06-25T10:09:01-03:00",
"deleted_at": null
}
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/cards/[ID]
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador do cartão |
Retorno
Em caso de sucesso será retornado um objeto cartão.
Listar cartões
curl --location --request GET "https://api.cobrefacil.com.br/v1/cards" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 0,
"brand": "visa",
"first6_digits": "453900",
"last4_digits": "5497",
"expiration_year": "2020",
"expiration_month": "12",
"created_at": "2020-06-25T10:06:10-03:00",
"updated_at": "2020-06-25T10:09:01-03:00",
"deleted_at": null
}
]
}
Retorna uma lista paginada de cartões.
É possível controlar a paginação e realizar buscas através de parâmetros na URL, exemplos:
Buscar cartões por cliente:
GET https://api.cobrefacil.com.br/v1/cards?customer_id=Z8J53ROD2JK1PQ47WG0E
Retornar 10 cartões que irão expirar em um período específico:
GET https://api.cobrefacil.com.br/v1/cards?expiration_start=2021-09&expiration_end=2021-10&limit=10
HTTP Request
GET https://api.cobrefacil.com.br/v1/cards
URL Parameters
| Parâmetro | Tipo | Descrição |
|---|---|---|
customer_id |
String | Busca pelo identificador do cliente |
brand |
String | Busca pela bandeira do cartão |
expiration |
String | Busca pela data de expiração, deve estar no formato YYYY-MM,quando esse parâmetro é informado expiration_start e expiration_end não devem ser enviados ou serão ignorados |
expiration_start |
String | Busca por cartões com data de expiração maior ou igual a informada, deve estar no formato YYYY-MM |
expiration_end |
String | Busca por cartões com data de expiração menor ou igual a informada, deve estar no formato YYYY-MM |
sort_by |
String | Campo a ser utilizado na ordenação, o padrão é created_at |
order_by |
String | Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc |
limit |
Integer | Quantidade máxima de registros que devem ser retornados, o padrão é 100 |
offset |
Integer | Número de registros a serem pulados, o padrão é 0 |
Retorno
Em caso de sucesso será retornado um array de objetos cartão.
Remover cartão
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/cards/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 1,
"first6_digits": "453900",
"last4_digits": "5497",
"brand": "visa",
"expiration_year": "2021",
"expiration_month": "12",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T16:58:00-03:00",
"deleted_at": "2020-06-25T16:58:00-03:00"
}
}
Ao remover um cartão que é o padrão, caso o cliente possua mais cartões, o novo cartão default será o mais recente cadastrado.
HTTP Request
DELETE https://api.cobrefacil.com.br/v1/cards/[ID]
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador do cartão |
Retorno
Em caso de sucesso será retornado um objeto cartão.
Produtos e Serviços
As mensalidades, planos e links de pagamento possuem itens de produtos e serviços, os endpoints são criar, atualizar e remover produtos e serviços.
Você também pode listar filtrando os atributos desejados, detalhar, ativar e desativar produtos e serviços.
O objeto produto serviço
Exemplo de JSON do objeto produto/serviço:
{
"id": "76JXDLQYEORE0P45WXMO",
"description": "Produto Especial",
"fixed_price": 1,
"price": 42.90,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do produto/serviço |
description |
String | Nome e/ou descrição do produto/serviço |
fixed_price |
Integer | Valor é fixo:1 Sim0 Não |
price |
Float | preço do produto/serviço |
status |
String | pode ser:actived quando ativoinactived quando desativado |
updated_at |
DateTime | Data que o produto/serviço foi atualizado |
deleted_at |
DateTime | Data que o produto/serviço foi excluído |
Criar produtos / serviços
Ao criar um produto/serviço além da descrição, preço e status, você precisa informar se o preço é fixo ou não em fixed_price, pois quando informado 1 as modificações de valores feitas neste serviço, irão alterar os preços das mensalidades, links de pagamento, planos e itens adicionais que utilizarem este serviço.
curl --location --request POST "https://api.cobrefacil.com.br/v1/product-services" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"description\": \"Produto Especial\",
\"fixed_price\": 1,
\"price\": 4290,
\"status\": \"actived\"
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "QG04KL8MED3N7V1XDZYR",
"description": "Produto Especial",
"fixed_price": 1,
"price": 42.90,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/product-services
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
description |
String | Sim | Nome e/ou descrição do produto/serviço |
fixed_price |
Integer | Não | O valor 1 é para fixo e 0 para não fixo, o padrão é 0 |
price |
Integer | Sim | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290 |
status |
String | Não | padrão é actived |
Retorno
Em caso de sucesso será retornado um objeto produto/serviço.
Atualizar produtos / serviços
Ao atualizar um produto é somente necessário enviar os campos que vão ser alterados.
curl --location --request PUT "https://api.cobrefacil.com.br/v1/product-services/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"description\": \"Produto Especial\",
\"fixed_price\": 1,
\"price\": 4290,
\"status\": \"actived\"
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "QG04KL8MED3N7V1XDZYR",
"description": "Produto Especial",
"fixed_price": 1,
"price": 42.90,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
PUT https://api.cobrefacil.com.br/v1/product-services/[ID]
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
description |
String | Sim | Nome e/ou descrição do produto/serviço |
fixed_price |
Integer | Não | O valor 1 é para fixo e 0 para não fixo, o padrão é 0 |
price |
Integer | Sim | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290 |
status |
String | Não | padrão é actived |
Retorno
Em caso de sucesso será retornado um objeto produto/serviço.
Remover produtos / serviços
A remoção de um produto é feita através do seu identificador, após a sua remoção todas as mensalidades, links de pagamento, planos e itens adicionais planos que utilizam este produto/serviço manterá o preço e descrição em em geração de cobranças, mas não será listado como produto/serviço na criação/edição dos serviços citados.
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/product-services/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "QG04KL8MED3N7V1XDZYR",
"description": "Produto Especial",
"fixed_price": 1,
"price": 42.90,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00",
"deleted_at": "2022-01-01 00:00:00"
}
}
HTTP Request
DELETE https://api.cobrefacil.com.br/v1/product-services/[ID]
Retorno
Em caso de sucesso será retornado um objeto produto/serviço com a data de exclusão deleted_at.
Detalhar produtos / serviços
O detalhamento de um produto é feito através do seu identificador.
curl --location --request GET "https://api.cobrefacil.com.br/v1/product-services/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "QG04KL8MED3N7V1XDZYR",
"description": "Produto Especial",
"fixed_price": 1,
"price": 42.90,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/product-services/[ID]
Retorno
Em caso de sucesso será retornado um objeto produto/serviço.
Listar produtos / serviços
curl --location --request GET "https://api.cobrefacil.com.br/v1/product-services" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "QG04KL8MED3N7V1XDZYR",
"description": "Produto Especial",
"fixed_price": 1,
"price": 42.90,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"pagination": {
"total_records": 1,
"display_records": 1
}
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/product-services
URL Parameters
| Parâmetro | Tipo | Descrição |
|---|---|---|
status |
String | Filtrar pelo status |
sort_by |
String | Campo a ser utilizado na ordenação, o padrão é created_at |
order_by |
String | Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc |
limit |
Integer | Quantidade máxima de registros que devem ser retornados, o padrão é 100 |
offset |
Integer | Número de registros a serem pulados, o padrão é 0 |
Retorno
Em caso de sucesso será retornado um array de objetos produtos/serviços.
Ativar produtos / serviços
curl --location --request POST "https://api.cobrefacil.com.br/v1/product-services/[ID]/activate" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "QG04KL8MED3N7V1XDZYR",
"description": "Produto Especial",
"fixed_price": 1,
"price": 42.90,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/product-services/[ID]/activate
Retorno
Em caso de sucesso será retornado um objeto produto/serviço.
Desativar produtos / serviços
Ao desativar um produto o mesmo não será mais listado em mensalidades, links de pagamento, planos e itens adicionais.
curl --location --request POST "https://api.cobrefacil.com.br/v1/product-services/[ID]/inactivate" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "QG04KL8MED3N7V1XDZYR",
"description": "Produto Especial",
"fixed_price": 1,
"price": 42.90,
"status": "inactived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/product-services/[ID]/inactivate
Retorno
Em caso de sucesso será retornado um objeto produto/serviço com status inactived.
Planos
Planos podem ser utilizados em mensalidades e link de pagamentos, esses são os endpoints para criar, atualizar e remover planos.
Você também pode listar filtrando os atributos desejados, detalhar, habilitar, pausar e cancelar planos.
O objeto plano
Exemplo de JSON do objeto plano:
{
"success": true,
"data": {
"id": "ZCYFP6YXQYZ18NZ4L752",
"description": "Descrição do Plano",
"discount": 20,
"goal": 1,
"items": [
{
"id": "CQXXZQ1NV3K8PLE7KMRB",
"quantity": 1,
"price": 999.97,
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"name": "Nome do Plano",
"notify_reactivation_at": null,
"price": 999.97,
"price_with_discount": 799.98,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do plano |
description |
String | Descrição do plano |
discount |
Integer | Percentual de desconto |
goal |
Integer | Meta de planos a ser vendidos |
items |
Array | Array de objetos do tipo objeto item do plano |
name |
String | Nome plano |
notify_reactivation_at |
Date | Data para notificações no sistema e via e-mail para reativar o plano |
price |
Float | preço do plano |
price_with_discount |
Float | preço com atribuição do desconto |
status |
String | pode ser:actived quando ativopaused quando pausadocanceled quando cancelado |
created_at |
DateTime | Data que o plano foi criado |
updated_at |
DateTime | Data que o plano foi atualizado |
Criar planos
Ao criar um plano com status actived o mesmo já poderá ser atribuído a mensalidades e links de pagamento.
curl --location --request POST "https://api.cobrefacil.com.br/v1/plans" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"description\": \"Descrição do Plano\",
\"discount\": 20,
\"goal\": 10,
\"items\": [
{
\"quantity\": 1,
\"products_services_id\": \"51MXVCYAQYR53J1YP5X8\"
}
],
\"name\": \"Nome do Plano\",
\"notify_reactivation_at\": null,
\"status\": \"actived\"
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "ZCYFP6YXQYZ18NZ4L752",
"description": "Description",
"discount": 20,
"goal": 1,
"items": [
{
"id": "CQXXZQ1NV3K8PLE7KMRB",
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"quantity": 1,
"price": 999.97,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"name": "Nome do Plano",
"notify_reactivation_at": "2022-01-01",
"price": 999.97,
"price_with_discount": 799.98,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/plans
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
description |
String | Sim | Descrição do plano |
discount |
Integer | Não | Percentual de desconto |
goal |
Integer | Não | Meta de planos a ser vendidos |
items |
Array | Sim | Array de objetos do tipo objeto item do plano |
name |
String | Sim | Nome plano |
notify_reactivation_at |
Date | Não | Data para notificações no sistema e via e-mail para reativar o plano |
status |
String | Sim | pode ser:actived quando ativopaused quando pausadocanceled quando cancelado (opcional, default: actived) |
Retorno
Em caso de sucesso será retornado um objeto plano.
Atualizar planos
Para editar o plano é necessário somente passar os campos que devem ser alterados.
curl --location --request PUT "https://api.cobrefacil.com.br/v1/plans/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"description\": \"Descrição do Plano Atualizado\",
\"discount\": 20,
\"goal\": 10,
\"items\": [
{
\"quantity\": 1,
\"products_services_id\": \"51MXVCYAQYR53J1YP5X8\"
}
],
\"name\": \"Nome do Plano Atualizado\",
\"notify_reactivation_at\": null,
\"status\": \"actived\"
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "ZCYFP6YXQYZ18NZ4L752",
"description": "Description",
"discount": 20,
"goal": 1,
"items": [
{
"id": "CQXXZQ1NV3K8PLE7KMRB",
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"quantity": 1,
"price": 999.97,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"name": "Nome do Plano",
"notify_reactivation_at": "2022-01-01",
"price": 999.97,
"price_with_discount": 799.98,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
PUT https://api.cobrefacil.com.br/v1/plans/[ID]
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
description |
String | Não | Descrição do plano |
discount |
Integer | Não | Percentual de desconto |
goal |
Integer | Não | Meta de planos a ser vendidos |
items |
Array | Não | Array de objetos do tipo objeto item do plano |
name |
String | Não | Nome plano |
notify_reactivation_at |
Date | Não | Data para notificações no sistema e via e-mail para reativar o plano |
status |
String | Não | pode ser:actived quando ativopaused quando pausadocanceled quando cancelado |
Retorno
Em caso de sucesso será retornado um objeto plano.
Remover planos
Ao remover um plano o mesmo não ficará mais como disponível para mensalidades e link de pagamento, porém as cobranças geradas desses items ainda contabilizam o valor total do plano.
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/plans/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "M8YVP5EKDYZ07NZ4L693",
"description": "Description",
"discount": 20,
"goal": 1,
"name": "Nome do Plano",
"price": 999.97,
"price_with_discount": 799.98,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00",
"deleted_at": "2022-01-01 00:00:00"
}
}
HTTP Request
DELETE https://api.cobrefacil.com.br/v1/plans/[ID]
Retorno
Em caso de sucesso será retornado um objeto plano com a data de exclusão deleted_at.
Detalhar plano
Informando o ID referenciador é retornado todas as informações do plano.
curl --location --request GET "https://api.cobrefacil.com.br/v1/plans/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "ZCYFP6YXQYZ18NZ4L752",
"description": "Descrição do Plano",
"discount": 20,
"goal": 1,
"goaled_percentage": 0,
"items": [
{
"id": "CQXXZQ1NV3K8PLE7KMRB",
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"quantity": 1,
"price": 999.97,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"name": "Nome do Plano",
"notify_reactivation_at": "2022-01-01",
"price": 999.97,
"price_with_discount": 799.98,
"status": "actived",
"total_subscriptions": 0,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/plans/[ID]
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do plano |
description |
String | Descrição do plano |
discount |
Integer | Percentual de desconto |
goal |
Integer | Meta de planos a ser vendidos |
goaled_percentage |
Integer | Percentual atingido da meta goal |
items |
Array | Array de objetos do tipo objeto item do plano |
name |
String | Nome plano |
notify_reactivation_at |
Date | Data para notificações no sistema e via e-mail para reativar o plano |
price |
Float | preço do plano |
price_with_discount |
Float | preço com desconto |
status |
String | pode ser:actived quando ativopaused quando pausadocanceled quando cancelado |
total_subscriptions |
Integer | Número de mensalidades com o plano |
updated_at |
DateTime | Data que o plano foi atualizado |
deleted_at |
DateTime | Data que o plano foi excluído |
Listar planos
No endpoint de listar planos é possível filtrar por status, além de limitar a quantidade de itens retornados e ordenação por campo escolhido.
curl --location --request GET "https://api.cobrefacil.com.br/v1/plans" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "NZM916730PQJLO8KG52X",
"description": "Descrição do Plano",
"discount": 20,
"goal": 1,
"goaled_percentage": 0,
"items": [
{
"id": "CQXXZQ1NV3K8PLE7KMRB",
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"quantity": 1,
"price": 999.97,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"name": "Nome do Plano",
"notify_reactivation_at": null,
"price": 999.97,
"price_with_discount": 799.98,
"status": "actived",
"total_subscriptions": 0,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"pagination": {
"total_records": 1,
"display_records": 1
}
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/plans
URL Parameters
| Parâmetro | Tipo | Descrição |
|---|---|---|
status |
String | Filtrar pelo status do plano, status actived, paused ou canceled, podendo ser enviado mais de um status entre vírgulas, exemplo actived,paused. Caso não seja informado, retorna todos os planos |
sort_by |
String | Campo a ser utilizado na ordenação, o padrão é created_at |
order_by |
String | Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc |
limit |
Integer | Quantidade máxima de registros que devem ser retornados, o padrão é 100 |
offset |
Integer | Número de registros a serem pulados, o padrão é 0 |
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do plano |
description |
String | Descrição do plano |
discount |
Integer | Percentual de desconto |
goal |
Integer | Meta de planos a ser vendidos |
goaled_percentage |
Integer | Percentual atingido da meta goal |
items |
Array | Array de objetos do tipo objeto item do plano |
name |
String | Nome plano |
notify_reactivation_at |
Date | Data para notificações no sistema e via e-mail para reativar o plano |
price |
Float | preço do plano |
price_with_discount |
Float | preço com atribuição do desconto |
status |
String | pode ser:actived quando ativopaused quando pausadocanceled quando cancelado |
total_subscriptions |
Integer | Número de mensalidades com o plano |
updated_at |
DateTime | Data que o plano foi atualizado |
deleted_at |
DateTime | Data que o plano foi excluído |
Ativar planos
Esse endpoint altera o status do plano para actived.
curl --location --request POST "https://api.cobrefacil.com.br/v1/plans/[ID]/activate" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "ZCYFP6YXQYZ18NZ4L752",
"description": "Descrição do Plano",
"discount": 20,
"goal": 1,
"items": [
{
"id": "CQXXZQ1NV3K8PLE7KMRB",
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"quantity": 1,
"price": 999.97,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"name": "Nome do Plano",
"notify_reactivation_at": null,
"price": 999.97,
"price_with_discount": 799.98,
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/plans/[ID]/activate
Retorno
Em caso de sucesso será retornado um objeto plano.
Pausar planos
Ao pausar um plano o mesmo fica com o status paused e não é exibido na listagem de planos em mensalidades e links de pagamento.
curl --location --request POST "https://api.cobrefacil.com.br/v1/plans/[ID]/pause" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "ZCYFP6YXQYZ18NZ4L752",
"description": "Descrição do Plano",
"discount": 20,
"goal": 1,
"items": [
{
"id": "CQXXZQ1NV3K8PLE7KMRB",
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"quantity": 1,
"price": 999.97,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"name": "Nome do Plano",
"notify_reactivation_at": null,
"price": 999.97,
"price_with_discount": 799.98,
"status": "paused",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/plans/[ID]/pause
Retorno
Em caso de sucesso será retornado um objeto plano com status paused.
Cancelar planos
Ao cancelar planos o status do mesmo será canceled e não será exibido na listagem de planos em mensalidades e links de pagamento e não será possível reativá-lo.
curl --location --request POST "https://api.cobrefacil.com.br/v1/plans/[ID]/cancel" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "ZCYFP6YXQYZ18NZ4L752",
"description": "Descrição do Plano",
"discount": 20,
"goal": 1,
"items": [
{
"id": "CQXXZQ1NV3K8PLE7KMRB",
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"quantity": 1,
"price": 999.97,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"name": "Nome do Plano",
"notify_reactivation_at": null,
"price": 999.97,
"price_with_discount": 799.98,
"status": "canceled",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/plans/[ID]/cancel
Retorno
Em caso de sucesso será retornado um objeto plano com status canceled.
Cadastrar itens do plano
O cadastro de itens é utilizado para adicionar produtos ou serviços a um plano existente.
curl --location --request POST "https://api.cobrefacil.com.br/v1/plans/[ID]/items" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"quantity\": 1,
\"product_service_id\": \"K25LRJWON2OE6G5Z37VQ\"
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "CQXXZQ1NV3K8PLE7KMRB",
"quantity": 1,
"price": 999.97,
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/plans/[ID]/items
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
product_service_id |
String | Sim | ID do produto/serviço |
quantity |
Integer | Sim | Quantidade de items |
Retorno
Em caso de sucesso será retornado um objeto item do plano.
Remover itens do plano
Esse endpoint serve para remover itens de produtos/serviços de um plano específico.
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/plans/[ID]/items/[ITEM_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"data": {
"id": "CQXXZQ1NV3K8PLE7KMRB",
"quantity": 1,
"price": 999.97,
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00",
"deleted_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/plans/[ID]/items
Retorno
Em caso de sucesso será retornado um objeto item do plano com deleted_at.
O objeto item do plano
Exemplo de JSON do objeto plano:
{
"success": true,
"data": {
"id": "CQXXZQ1NV3K8PLE7KMRB",
"quantity": 1,
"price": 999.97,
"products_services_id": "51MXVCYAQYR53J1YP5X8",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do plano |
quantity |
Integer | Nome plano |
price |
Float | preço do plano |
product_service |
Array | Objeto do tipo objeto produto/serviço |
created_at |
DateTime | Data que o item do plano foi criado |
updated_at |
DateTime | Data que o item do plano foi atualizado |
Mensalidades
As mensalidades são perfeitas para cobranças recorrentes ou que tenham um período definido, os endpoints
para criar, atualizar, renovar,
e remover mensalidades.
Você também pode listar filtrando os atributos
desejados, detalhar, pausar, cancelar, finalizar, ativar
e reativar mensalidades.
As mensalidades possuem itens que são produtos e serviços, os endpoints
de criar item, atualizar, remover
item da mensalidade e listar.
Existem também a opção de gerar cobrança e ativar para antes ou depois da emissão
da nota fiscal.
Os assinantes PRO tem a opção em mensalidades de salvar anexo, remover anexo
e exibir link do anexo.
O objeto mensalidade
Exemplo de JSON do objeto mensalidade:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"items": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"description": "Produto Especial",
"price": 500,
"quantity": 1,
"type": "service"
}
],
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": null,
"payable_with": "bankslip,credit,pix",
"plans_id": null,
"quantity_generated": 1,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"settings": {
"discount": {
"amount": "5.00",
"limit_date": 1,
"mode": "percentage"
},
"discount_subscription": {
"amount": "5.00",
"mode": "percentage",
"number_installments": 1
},
"interest": {
"amount": "10.00",
"mode": "monthly_percentage"
},
"late_fee": {
"amount": "10.55",
"mode": "percentage"
},
"send_tax_invoice": 0,
"warning": {
"description": "Description"
},
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
},
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
| Atributo | Tipo | Descrição |
|---|---|---|
contract_number |
String | Número de contrato |
create_invoice |
Date | Data de criação da cobrança |
customer_id |
String | Id do cliente |
due_day |
Integer | Dia da data de vencimento |
expires_at |
Date | Data final da mensalidade |
first_due_date |
Date | Data de vencimento da primeira cobrança da mensalidade |
generate_days |
Integer | Dias antes do vencimento será gerado a cobrança |
interval_type |
String | Ciclo de cobrança pode ser diário = day e mensal = month, |
interval_size |
Integer | Quantidade de ciclo de cobrança. exemplo interval_type = month e interval_size = 6 a cobrança será semestral |
invoices |
Array | Array de cobranças |
items |
Array | Array de objetos - itens de mensalidade |
next_expiration |
Date | Data da próxima cobrança |
notification_rule_id |
String | Id da régua de cobrança |
paused_at |
Date | Data de quando foi pausada a mensalidade |
payable_with |
String | Formas aceitas de pagamento, podendo ser: bankslip, credit ou pixPara mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix |
plans_id |
String | Id do plano |
quantity_generated |
Integer | Número de cobranças geradas |
reactivate_at |
Date | Data de quando será reativada a mensalidade |
reference |
String | Referência da mensalidade, podendo ser: none para "nenhuma" prev para "Mês anterior" current para "Mês atual" next para "Próximo mês"Exemplo: Vencimento em Setembro, referente ao mês de agosto. |
sequencial_number |
String | Número sequencial de mensalidades geradas |
settings |
Object | objeto settings |
status |
String | Status da mensalidade, a lista completa em status mensalidade |
created_at |
DateTime | Data que a mensalidade foi criado |
updated_at |
DateTime | Data que a mensalidade foi atualizado |
deleted_at |
DateTime | Data que a mensalidade foi deletado |
O objeto settings
| Atributo | Tipo | Descrição |
|---|---|---|
discount |
Json | Desconto para pagamento antecipado |
discount.mode |
String | Modo de desconto, pode ser: percentage ou fixed |
discount.amount |
Float | Valor do desconto em porcentagem ou em reais |
discount.limit_date |
Float | Número de dias antes do vencimento para desconto |
discount_subscription |
Json | Desconto ao início do contrato |
discount_subscription.mode |
String | Modo de desconto no início da mensalidade, pode ser: percentage ou fixed |
discount_subscription.amount |
Float | Valor do desconto no início da mensalidade, pode ser em porcentagem ou em reais |
discount_subscription.number_installments |
Float | Número de parcelas de desconto no início da mensalidade |
interest |
Json | Cobrar juro de mora após vencimento |
interest.mode |
String | Modo de juro de mora após vencimento, pode ser: monthly_percentage, daily_percentage e daily_amount |
interest.amount |
Float | Valor do juro de mora após vencimento, pode ser em porcentagem ou em reais |
late_fee |
Json | Multas para pagamentos após data de vencimento |
late_fee.mode |
String | Modo de multas para pagamentos após data de vencimento, pode ser: percentage ou fixed |
late_fee.amount |
Float | Valor do multas para pagamentos após data de vencimento, pode ser em porcentagem ou em reais |
send_tax_invoice |
Integer | Momento em que a nota fiscal deve ser gerada:0 não deve gerar nota fiscal1 a nota fiscal deve ser gerada após confirmação do pagamento2 a nota fiscal deve ser gerada após a criação da cobrançaOBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal |
warning |
Json | Informações de desconto, multas e juros, não terão validade neste campo |
O objeto item de mensalidade
Exemplo de JSON do objeto plano:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"description": "Produto Especial",
"generated_installments": 0,
"number_installments": 1,
"price": 500,
"products_services_id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"type": "service"
}
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do item |
description |
String | Descrição do item |
generated_installments |
Integer | Número de cobranças geradas para esse item |
number_installments |
Integer | Número de parcelas para esse item |
price |
Float | preço do plano |
product_service_id |
Array | Objeto do tipo objeto produto/serviço |
created_at |
DateTime | Data que o item do plano foi criado |
updated_at |
DateTime | Data que o item do plano foi atualizado |
Status mensalidades
| Status | Descrição |
|---|---|
actived |
Mensalidade ativa |
canceled |
Mensalidade cancelada, não são geradas cobranças |
finished |
Mensalidade finalizado de forma manual, não são geradas novas cobranças |
inactived |
Mensalidade inativada, não são geradas novas cobranças |
paused |
Mensalidade pausada, não são geradas novas cobranças |
renewed |
Mensalidade renovada, existe outra mensalidade tendo essa como origem |
suspended |
Mensalidade suspensa, não são geradas novas cobranças |
terminated |
Mensalidade finalizado automática pelo período informado |
terminating |
Mensalidade próxima do tempo de expiração, alerta que não serão geradas novas cobranças |
Criar mensalidades
A criação da mensalidade é feita através das informações contratadas pelo cliente como: início de cobrança, planos ou serviços, forma de pagamento, ciclos de pagamento, régua de cobrança, regras de multa, juros e descontos. Depois da mensalidade criada é possível gerar as cobranças através do método gerar cobrança ou aguardar a geração automática.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"customer_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"contract_number\" : \"Número do Contrato\",
\"first_due_date\" : \"2022-01-01\",
\"generate_days\" : 1,
\"interval_type\" : \"month\",
\"interval_size\" : 1,
\"items\" : [
{
\"products_services_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"quantity\" : 1,
\"price\": 50000
}
],
\"notification_rule_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"payable_with\" : \"bankslip,credit,pix\",
\"plans_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"reference\" : \"none\",
\"settings\" : {
\"enable_duplicate\" : 1,
\"late_fee\" : {
\"mode\" : \"percentage\",
\"amount\" : 10.55
},
\"interest\" : {
\"mode\" : \"monthly_percentage\",
\"amount\" : 10.00
},
\"discount\" : {
\"mode\" : \"percentage\",
\"amount\" : 5.00,
\"limit_date\" : 1
},
\"discount_subscription\" : {
\"mode\" : \"percentage\",
\"amount\" : 5.00,
\"number_installments\" : 1
},
\"warning\" : {
\"description\" : \"Description\"
}
}
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"items": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"description": "Produto Especial",
"price": 500,
"quantity": 1,
"type": "service"
}
],
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": null,
"payable_with": "bankslip,credit,pix",
"plans_id": null,
"quantity_generated": 1,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"settings": {
"discount": {
"amount": "5.00",
"limit_date": 1,
"mode": "percentage"
},
"discount_subscription": {
"amount": "5.00",
"mode": "percentage",
"number_installments": 1
},
"interest": {
"amount": "10.00",
"mode": "monthly_percentage"
},
"late_fee": {
"amount": "10.55",
"mode": "percentage"
},
"send_tax_invoice": 0,
"warning": {
"description": "Description"
}
},
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
contract_number |
String | Não | Número de contrato |
customer_id |
String | Sim | Id do cliente |
expires_at |
Date | Não | Data final da mensalidade |
first_due_date |
Date | Sim | Data de vencimento da primeira cobrança da mensalidade |
generate_days |
Integer | Sim | Número de dias antes do vencimento que será gerado a cobrança |
interval_type |
String | Não | Ciclo de cobrança que pode ser diário = day ou mensal = month, sendo o padrão month |
interval_size |
Integer | Sim | Quantidade de ciclo de cobrança. exemplo interval_type = month e interval_size = 6 a cobrança será semestral |
items |
Array | Sim* | Array de objetos - itens de mensalidade |
items.*.products_services_id |
String | Sim | Id do produto ou serviço |
items.*.quantity |
Integer | Não | Quantidade de produtos ou serviços, caso não informado o valor padrão é 1 |
items.*.price |
Integer | Não | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo |
notification_rule_id |
String | Sim | Id da régua de cobrança |
payable_with |
String | Formas aceitas de pagamento, podendo ser: bankslip, credit ou pixPara mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix |
|
plans_id |
String | Sim* | Id do plano |
reference |
String | Sim | Referência da mensalidade, podendo ser: none para "nenhuma" prev para "Mês anterior" current para "Mês atual" next para "Próximo mês"Exemplo: Vencimento em Setembro, referente ao mês de agosto. |
settings |
Object | Não | objeto settings |
*Lembrando que deve ser escolhido items ou plans_id e não pode ser escolhido os dois ao mesmo tempo.
Retorno
Em caso de sucesso será retornado um objeto mensalidade.
Atualizar mensalidades
A atualização da mensalidade requer somente os dados que vão ser alterados, em caso de produtos/serviços é necessário
enviar o id do item para alterá-lo, caso não seja informado o id será criado um novo item.
curl --location --request PUT "https://api.cobrefacil.com.br/v1/subscriptions/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"contract_number\" : \"Número do Contrato\",
\"next_expiration\" : \"2022-01-01 00:00:00\",
\"generate_days\" : 1,
\"interval_type\" : \"month\",
\"interval_size\" : 1,
\"items\" : [
{
\"products_services_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"quantity\" : 1,
\"price\": 50000
}
],
\"notification_rule_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"payable_with\" : \"bankslip,credit,pix\",
\"plans_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"reference\" : \"none\",
\"settings\" : {
\"enable_duplicate\" : 1,
\"late_fee\" : {
\"mode\" : \"percentage\",
\"amount\" : 10.55
},
\"interest\" : {
\"mode\" : \"monthly_percentage\",
\"amount\" : 10.00
},
\"discount\" : {
\"mode\" : \"percentage\",
\"amount\" : 5.00,
\"limit_date\" : 1
},
\"discount_subscription\" : {
\"mode\" : \"percentage\",
\"amount\" : 5.00,
\"number_installments\" : 1
},
\"warning\" : {
\"description\" : \"Description\"
}
}
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"invoices": [],
"items": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"description": "Produto Especial",
"price": 500,
"quantity": 1,
"type": "service"
}
],
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": null,
"payable_with": "bankslip,credit,pix",
"plans_id": null,
"quantity_generated": 1,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"settings": {
"discount": {
"amount": "5.00",
"limit_date": 1,
"mode": "percentage"
},
"discount_subscription": {
"amount": "5.00",
"mode": "percentage",
"number_installments": 1
},
"interest": {
"amount": "10.00",
"mode": "monthly_percentage"
},
"late_fee": {
"amount": "10.55",
"mode": "percentage"
},
"send_tax_invoice": 0,
"warning": {
"description": "Description"
}
},
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
PUT https://api.cobrefacil.com.br/v1/subscriptions/[ID]
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
contract_number |
String | Não | Número de contrato |
expires_at |
Date | Não | Data final da mensalidade |
generate_days |
Integer | Não | Número de dias antes do vencimento que será gerado a cobrança |
interval_type |
String | Não | Ciclo de cobrança que pode ser diário = day ou mensal = month, sendo o padrão month |
interval_size |
Integer | Não | Quantidade de ciclo de cobrança. exemplo interval_type = month e interval_size = 6 a cobrança será semestral |
items |
Array | Não | Array de objetos - itens de mensalidade |
next_expiration |
Date | Não | Data de vencimento da próxima cobrança da mensalidade |
notification_rule_id |
String | Não | Id da régua de cobrança |
payable_with |
String | Formas aceitas de pagamento, podendo ser: bankslip, credit ou pixPara mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix |
|
plans_id |
String | Não | Id do plano |
reference |
String | Não | Referência da mensalidade, podendo ser: none para "nenhuma" prev para "Mês anterior" current para "Mês atual" next para "Próximo mês"Exemplo: Vencimento em Setembro, referente ao mês de agosto. |
settings |
Object | Não | objeto settings |
Retorno
Em caso de sucesso será retornado um objeto mensalidade.
Renovar mensalidades
A renovação de uma mensalidade, é semelhante com o criar mas com a diferença que o status da
mensalidade informada será alterado para renewed e criado uma nova mensalidade.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/renew" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"customer_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"contract_number\" : \"Número do Contrato\",
\"next_expiration\" : \"2022-01-01 00:00:00\",
\"generate_days\" : 1,
\"interval_type\" : \"month\",
\"interval_size\" : 1,
\"items\" : [
{
\"products_services_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"quantity\" : 1,
\"price\": 50000
}
],
\"notification_rule_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"payable_with\" : \"bankslip,credit,pix\",
\"plans_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"reference\" : \"none\",
\"settings\" : {
\"enable_duplicate\" : 1,
\"late_fee\" : {
\"mode\" : \"percentage\",
\"amount\" : 10.55
},
\"interest\" : {
\"mode\" : \"monthly_percentage\",
\"amount\" : 10.00
},
\"discount\" : {
\"mode\" : \"percentage\",
\"amount\" : 5.00,
\"limit_date\" : 1
},
\"discount_subscription\" : {
\"mode\" : \"percentage\",
\"amount\" : 5.00,
\"number_installments\" : 1
},
\"warning\" : {
\"description\" : \"Description\"
}
}
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"invoices": [],
"items": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"description": "Produto Especial",
"price": 500,
"quantity": 1,
"type": "service"
}
],
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": null,
"payable_with": "bankslip,credit,pix",
"plans_id": null,
"quantity_generated": 1,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"settings": {
"discount": {
"amount": "5.00",
"limit_date": 1,
"mode": "percentage"
},
"discount_subscription": {
"amount": "5.00",
"mode": "percentage",
"number_installments": 1
},
"interest": {
"amount": "10.00",
"mode": "monthly_percentage"
},
"late_fee": {
"amount": "10.55",
"mode": "percentage"
},
"send_tax_invoice": 0,
"warning": {
"description": "Description"
}
},
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
PUT https://api.cobrefacil.com.br/v1/subscriptions/[ID]
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
contract_number |
String | Não | Número de contrato |
customer_id |
String | Sim | Id do cliente |
expires_at |
Date | Não | Data final da mensalidade |
first_due_date |
Date | Sim | Data de vencimento da primeira cobrança da mensalidade |
generate_days |
Integer | Sim | Número de dias antes do vencimento que será gerado a cobrança |
interval_type |
String | Não | Ciclo de cobrança que pode ser diário = day ou mensal = month, sendo o padrão month |
interval_size |
Integer | Sim | Quantidade de ciclo de cobrança. exemplo interval_type = month e interval_size = 6 a cobrança será semestral |
items |
Array | Sim* | Array de objetos - itens de mensalidade |
notification_rule_id |
String | Sim | Id da régua de cobrança |
payable_with |
String | Formas aceitas de pagamento, podendo ser: bankslip, credit ou pixPara mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix |
|
plans_id |
String | Sim* | Id do plano |
reference |
String | Sim | Referência da mensalidade, podendo ser: none para "nenhuma" prev para "Mês anterior" current para "Mês atual" next para "Próximo mês"Exemplo: Vencimento em Setembro, referente ao mês de agosto. |
settings |
Object | Não | objeto settings |
Retorno
Em caso de sucesso será retornado um objeto mensalidade.
Remover mensalidades
Para remover uma mensalidade basta enviar um DELETE para com id da mensalidade. Ao remover a mensalidade, todas as
cobranças geradas relacionadas a ela continuarão válidas, mas não serão geradas novas cobranças.
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/subscriptions/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"invoices": [],
"items": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"description": "Produto Especial",
"price": 500,
"quantity": 1,
"type": "service"
}
],
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": null,
"payable_with": "bankslip,credit,pix",
"plans_id": null,
"quantity_generated": 1,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"settings": {
"discount": {
"amount": "5.00",
"limit_date": 1,
"mode": "percentage"
},
"discount_subscription": {
"amount": "5.00",
"mode": "percentage",
"number_installments": 1
},
"interest": {
"amount": "10.00",
"mode": "monthly_percentage"
},
"late_fee": {
"amount": "10.55",
"mode": "percentage"
},
"send_tax_invoice": 0,
"warning": {
"description": "Description"
}
},
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00",
"deleted_at": "2022-01-01 00:00:00"
}
}
HTTP Request
DELETE https://api.cobrefacil.com.br/v1/subscriptions/[ID]
Retorno
Em caso de sucesso será retornado um objeto mensalidade com a data de exclusão deleted_at.
Detalhar mensalidades
Para detalhar uma mensalidade é necessário informar o id.
curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"invoices": [],
"items": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"description": "Produto Especial",
"price": 500,
"quantity": 1,
"type": "service"
}
],
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": null,
"payable_with": "bankslip,credit,pix",
"plans_id": null,
"quantity_generated": 1,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"settings": {
"discount": {
"amount": "5.00",
"limit_date": 1,
"mode": "percentage"
},
"discount_subscription": {
"amount": "5.00",
"mode": "percentage",
"number_installments": 1
},
"interest": {
"amount": "10.00",
"mode": "monthly_percentage"
},
"late_fee": {
"amount": "10.55",
"mode": "percentage"
},
"send_tax_invoice": 0,
"warning": {
"description": "Description"
}
},
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/subscriptions/[ID]
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
attachment |
String | Url do anexo da mensalidade |
contract_number |
String | Número de contrato |
create_invoice |
Date | Data de criação da cobrança |
customer_id |
String | Id do cliente |
due_day |
Integer | Dia da data de vencimento |
expires_at |
Date | Data final da mensalidade |
first_due_date |
Date | Data de vencimento da primeira cobrança da mensalidade |
generate_days |
Integer | Dias antes do vencimento será gerado a cobrança |
interval_type |
String | Ciclo de cobrança pode ser diário = day e mensal = month, |
interval_size |
Integer | Quantidade de ciclo de cobrança. exemplo interval_type = month e interval_size = 6 a cobrança será semestral |
invoices |
Array | Array de cobranças |
items |
Array | Array de objetos - itens de mensalidade |
next_expiration |
Date | Data da próxima cobrança |
notification_rule_id |
String | Id da régua de cobrança |
paused_at |
Date | Data de quando foi pausada a mensalidade |
payable_with |
String | Formas aceitas de pagamento, podendo ser: bankslip, credit ou pixPara mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix |
plans_id |
String | Id do plano |
quantity_generated |
Integer | Número de cobranças geradas |
reactivate_at |
Date | Data de quando será reativada a mensalidade |
reference |
String | Referência da mensalidade, podendo ser: none para "nenhuma" prev para "Mês anterior" current para "Mês atual" next para "Próximo mês"Exemplo: Vencimento em Setembro, referente ao mês de agosto. |
sequencial_number |
String | Número sequencial de mensalidades geradas |
settings |
Object | objeto settings |
status |
String | Status da mensalidade, a lista completa em status mensalidade |
created_at |
DateTime | Data que a mensalidade foi criado |
updated_at |
DateTime | Data que a mensalidade foi atualizado |
Listar mensalidades
No endpoint de listar mensalidades é possível filtrar por status, além de limitar a quantidade de itens retornados e ordenação por campo escolhido.
curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": "",
"contract_number": "",
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 4,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"items": [
{
"description": "Serviço 1",
"price": 500,
"quantity": 1,
"type": "plan"
}
],
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": null,
"payable_with": "bankslip",
"plans_id": "XXXXXXXXXXXXXXXXXXXX",
"price": 500,
"quantity_generated": 1,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"settings": {
"discount": null,
"discount_subscription": null,
"interest": null,
"late_fee": null,
"send_tax_invoice": 0,
"warning": {
"description": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento."
}
},
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"pagination": {
"total_records": 1,
"display_records": 1
}
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/subscriptions
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
attachment |
String | Url do anexo da mensalidade |
contract_number |
String | Número de contrato |
create_invoice |
Date | Data de criação da cobrança |
customer_id |
String | Id do cliente |
due_day |
Integer | Dia da data de vencimento |
expires_at |
Date | Data final da mensalidade |
first_due_date |
Date | Data de vencimento da primeira cobrança da mensalidade |
generate_days |
Integer | Dias antes do vencimento será gerado a cobrança |
interval_type |
String | Ciclo de cobrança pode ser diário = day e mensal = month, |
interval_size |
Integer | Quantidade de ciclo de cobrança. exemplo interval_type = month e interval_size = 6 a cobrança será semestral |
invoices |
Array | Array de cobranças |
items |
Array | Array de objetos - itens de mensalidade |
next_expiration |
Date | Data da próxima cobrança |
notification_rule_id |
String | Id da régua de cobrança |
paused_at |
Date | Data de quando foi pausada a mensalidade |
payable_with |
String | Formas aceitas de pagamento, podendo ser: bankslip, credit ou pixPara mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix |
plans_id |
String | Id do plano |
quantity_generated |
Integer | Número de cobranças geradas |
reactivate_at |
Date | Data de quando será reativada a mensalidade |
reference |
String | Referência da mensalidade, podendo ser: none para "nenhuma" prev para "Mês anterior" current para "Mês atual" next para "Próximo mês"Exemplo: Vencimento em Setembro, referente ao mês de agosto. |
sequencial_number |
String | Número sequencial de mensalidades geradas |
settings |
Object | objeto settings |
status |
String | Status da mensalidade, a lista completa em status mensalidade |
created_at |
DateTime | Data que a mensalidade foi criado |
updated_at |
DateTime | Data que a mensalidade foi atualizado |
total_records |
Integer | Número total de mensalidades cadastrados e filtrados |
display_records |
Integer | Número total de mensalidades exibidos |
Reativar mensalidades
O endpoint de reativar mensalidade muda o status da mensalidade para actived alterando a data do próximo vencimento e
expiração (não obrigatório).
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/reactivate" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"next_expiration\" : \"2022-01-01\",
\"expires_at\" : \"2022-01-01\"
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"invoices": [],
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": null,
"payable_with": "bankslip,credit,pix",
"plans_id": null,
"quantity_generated": 1,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"settings": {
"discount": {
"amount": "5.00",
"limit_date": 1,
"mode": "percentage"
},
"discount_subscription": {
"amount": "5.00",
"mode": "percentage",
"number_installments": 1
},
"interest": {
"amount": "10.00",
"mode": "monthly_percentage"
},
"late_fee": {
"amount": "10.55",
"mode": "percentage"
},
"send_tax_invoice": 0,
"warning": {
"description": "Description"
}
},
"status": "actived",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/reactivate
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
next_expiration |
Date | Sim | Data de vencimento |
expires_at |
Date | Não | Data final da mensalidade |
Retorno
Em caso de sucesso será retornado um objeto mensalidade.
Pausar mensalidades
O endpoint de pausar mensalidade muda o status da mensalidade para paused e não são geradas novas cobranças.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/pause" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"reactivate_at\" : \"2022-01-01\"
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": "2022-01-01T03:00:00.000000Z",
"payable_with": "bankslip",
"plans_id": null,
"quantity_generated": 0,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"status": "paused",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/pause
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
reactivate_at |
Date | Não | Data para reativar automaticamente a mensalidade |
Retorno
Em caso de sucesso será retornado um objeto mensalidade com status paused.
Cancelar mensalidades
O endpoint de pausar mensalidade muda o status da mensalidade para canceled e não são geradas novas cobranças.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/cancel" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": "2022-01-01T03:00:00.000000Z",
"payable_with": "bankslip",
"plans_id": null,
"quantity_generated": 0,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"status": "canceled",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/cancel
Retorno
Em caso de sucesso será retornado um objeto mensalidade com status canceled.
Finalizar mensalidades
Endpoint destinado a finalizar mensalidades para não gerar novas cobranças e indicar o final do contrato.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/finished" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"attachment": null,
"contract_number": null,
"create_invoice": "2022-01-01",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"due_day": 1,
"expires_at": null,
"first_due_date": "2022-01-01",
"generate_days": 1,
"interval_size": 1,
"interval_type": "month",
"next_expiration": "2022-01-01",
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paused_at": "2022-01-01T03:00:00.000000Z",
"payable_with": "bankslip",
"plans_id": null,
"quantity_generated": 0,
"reactivate_at": null,
"reference": "none",
"sequencial_number": "MENS00000001",
"status": "finished",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/finished
Retorno
Em caso de sucesso será retornado um objeto mensalidade com status finished.
Criar item mensalidades
Este endpoint tem como finalidade a criação de itens de mensalidades, sendo utilizado para adicionar produtos ou serviços a uma mensalidade existente.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"quantity\": 1,
\"product_service_id\": \"K25LRJWON2OE6G5Z37VQ\",
\"price\": 50000
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": null,
"number_installments": 1,
"price": 999.97,
"products_services_id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"subscriptions_id": "XXXXXXXXXXXXXXXXXXXX",
"type": "service",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
products_services_id |
String | Sim | Id do produto ou serviço |
quantity |
Integer | Não | Quantidade de produtos ou serviços, caso não informado o valor padrão é 1 |
price |
Integer | Não | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo |
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items
Retorno
Em caso de sucesso será retornado um objeto item da mensalidade.
Atualizar item mensalidades
Este endpoint tem como finalidade a atualizar itens de mensalidades, sendo utilizado para quantidades, produtos/serviços e preço cobrado de um item.
curl --location --request PUT "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items/[ITEM_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"quantity\": 1,
\"products_services_id\": \"K25LRJWON2OE6G5Z37VQ\",
\"price\": 50000
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": null,
"generated_installments": 0,
"number_installments": 1,
"price": 500,
"products_services_id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"type": "service",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
PUT https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
products_services_id |
String | Sim | Id do produto ou serviço |
quantity |
Integer | Não | Quantidade de produtos ou serviços, caso não informado o valor padrão é 1 |
price |
Integer | Não | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo |
Retorno
Em caso de sucesso será retornado um objeto item da mensalidade.
Remover item mensalidades
Remove um item de mensalidade.
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items/[ITEM_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": null,
"generated_installments": 0,
"number_installments": 1,
"price": 500,
"products_services_id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"type": "service",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items
Retorno
Em caso de sucesso será retornado um objeto item da mensalidade com deleted_at.
Listar items mensalidades
Lista todos os itens de mensalidades.
curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": null,
"generated_installments": 0,
"number_installments": 1,
"price": 500,
"products_services_id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"type": "service",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
]
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items
Retorno
Em caso de sucesso será retornado um objeto item da mensalidade.
Criar item adicional de mensalidades
Este endpoint tem como finalidade a criação de itens adicionais de mensalidades.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"first_due_date\": \"2022-01-01\",
\"number_installments\": 10,
\"product_service_id\": \"K25LRJWON2OE6G5Z37VQ\",
\"price\": 50000,
\"quantity\": 1
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": "2022-01-01",
"number_installments": 1,
"price": 999.97,
"products_services_id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"type": "additional",
"subscriptions_id": "XXXXXXXXXXXXXXXXXXXX",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
products_services_id |
String | Sim | Id do produto ou serviço |
quantity |
Integer | Não | Quantidade de produtos ou serviços, caso não informado o valor padrão é 1 |
price |
Integer | Não | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo |
number_installments |
Integer | Não | Número de parcelas do item adicional, caso não informado o valor padrão é 1 |
first_due_date |
Date | Não | Data de início da cobrança do item adicional, caso não informado o valor padrão é hoje |
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals
Retorno
Em caso de sucesso será retornado um objeto item da mensalidade.
Atualizar item adicional de mensalidades
Este endpoint tem como finalidade a atualizar itens adicionais de mensalidades, sendo utilizado para quantidades, produtos/serviços, preço cobrado, data inicial de cobrança e número de parcelas.
curl --location --request PUT "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"first_due_date\": \"2022-01-01\",
\"number_installments\": 10,
\"product_service_id\": \"K25LRJWON2OE6G5Z37VQ\",
\"price\": 50000,
\"quantity\": 1
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": "2022-01-01",
"number_installments": 1,
"price": 999.97,
"products_services_id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"type": "additional",
"subscriptions_id": "XXXXXXXXXXXXXXXXXXXX",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
PUT https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
products_services_id |
String | Sim | Id do produto ou serviço |
quantity |
Integer | Não | Quantidade de produtos ou serviços, caso não informado o valor padrão é 1 |
price |
Integer | Não | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo |
number_installments |
Integer | Não | Número de parcelas do item adicional, caso não informado o valor padrão é 1 |
first_due_date |
Date | Não | Data de início da cobrança do item adicional, caso não informado o valor padrão é hoje |
Retorno
Em caso de sucesso será retornado um objeto item da mensalidade.
Remover item adicional de mensalidades
Remove um item adicional de uma mensalidade, mesmo que ele ainda tenha parcelas em aberto.
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals/[ITEM_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"price": 999.97,
"product_service_id": "XXXXXXXXXXXXXXXXXXXX",
"type": "additional",
"updated_at": "2022-01-01 00:00:00",
"created_at": "2022-01-01 00:00:00",
"deleted_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals
Retorno
Em caso de sucesso será retornado um objeto item da mensalidade com deleted_at.
Listar items adicionais de mensalidades
Lista todos os items adicionais de uma mensalidade.
curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": "2022-01-01",
"generated_installments": 0,
"number_installments": 1,
"price": 500,
"products_services_id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"type": "additional",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
]
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals
Retorno
Em caso de sucesso será retornado um objeto item da mensalidade.
O objeto item da mensalidade
Exemplo de JSON do objeto mensalidade:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"quantity": 1,
"price": 999.97,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00",
"product_service": "XXXXXXXXXXXXXXXXXXXX"
}
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do mensalidade |
first_due_date |
Date | Data de início da cobrança do item mensalidade, em caso de type = additional |
number_installments |
Integer | Número de cobranças geradas para esse item, em caso de type = additional |
price |
Float | preço do mensalidade |
products_services_id |
Integer | Id do produto ou serviço |
quantity |
Integer | Nome mensalidade |
type |
String | Tipo de item de mensalidade, podendo ser service ou additional |
created_at |
DateTime | Data que o item do mensalidade foi criado |
updated_at |
DateTime | Data que o item do mensalidade foi atualizado |
deleted_at |
DateTime | Data que o item do mensalidade foi deletado |
Gerar cobrança mensalidades
Ao executar o endpoint com ID da mensalidade será gerada a próxima cobrança da mensalidade.
curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/generate-invoice" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"amount": null,
"amount_released": null,
"barcode": null,
"barcode_data": null,
"booklet": null,
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"discount": null,
"document_number": null,
"due_date": "2022-01-01",
"duedate_reference": null,
"fine_delay": null,
"installment": null,
"installment_number": 1,
"items": [
{
"description": "###Produto Especial",
"price": "500.00",
"quantity": 1,
"type": "service"
},
{
"description": "Desconto Mensalidade",
"price": "-0.25",
"quantity": 1,
"type": "discount_subscription"
}
],
"paid_at": null,
"payable_with": "bankslip",
"payable_with_checkout": 0,
"payable_with_converted": 0,
"payment_method": null,
"pending_reminder_at": null,
"price": "499.75",
"price_reference": null,
"sequencial_number": "COB00000001",
"settings": {
"discount": {
"mode": "percentage",
"limit_date": 1,
"amount": "5.00"
},
"discount_subscription": {
"mode": "percentage",
"amount": "5",
"number_installments": 1
},
"interest": {
"mode": "monthly_percentage",
"amount": "10.00"
},
"late_fee": {
"mode": "percentage",
"amount": "10.55"
},
"send_tax_invoice": 0,
"warning": "Description"
},
"status": "pending",
"tax_invoices_with_status_active": [],
"total_paid": null,
"transaction_number": null,
"url_document": null,
"url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
"url_receipt": null,
"url_tax_invoice": null,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/generate-invoice
Retorno
Em caso de sucesso será retornado um objeto da cobrança.
Nota fiscal mensalidades
Opção para gerar antes ou depois a nota fiscal para mensalidades. Necessário configuração da empresa para gerar a nota fiscal dentro do sistema.
curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/enable-nf" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"nf_generate\": \"after\"
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"nf_generate": "after"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/enable-nf
Body Parameters
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
nf_generate |
String | Sim | Geração da Nota-Fiscal antes before ou depois after da geração da cobrança |
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
nf_generate |
String | Geração da Nota-Fiscal antes before ou depois after da geração da cobrança |
Salvar anexo
Opção para salvar anexo a uma mensalidade.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
-F "attachment"="@/path/to/a/file.jpg" \
Exemplo de JSON retornado:
{
"success": true,
"data": "https://urldaimagem.jpg"
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments
Body Parameters
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
attachment |
File | Sim | Arquivo anexo de extensão PNG, PDF e DOC com até 2MB de tamanho |
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
data |
String | Url do anexo |
Remover anexo
Remove um anexo de uma mensalidade.
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": true
}
HTTP Request
DELETE https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments
Retorno
Apenas é retornado true se caso o anexo foi removido com sucesso.
Exibir link anexo
Exibe o link temporário de uma mensalidade.
curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": "https://urldaimagem.jpg"
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
data |
String | Url do anexo |
Ativar Cobrança Recorrente
Ativa uma cobrança recorrente. A cobrança recorrente pode ser ativada a qualquer momento após a criação da mensalidade. É necessário que o cliente tenha um cartão de crédito cadastrado como default.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/enable-recurrence" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": true
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/enable-recurrence
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
data |
String | true se a cobrança recorrente foi ativada com sucesso ou mensagens que impossibilitaram a ativação da cobrança recorrente. |
Desativar Cobrança Recorrente
Desativa uma cobrança recorrente.
curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/disable-recurrence" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": true
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/disable-recurrence
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
data |
String | true se a cobrança recorrente foi desativada com sucesso ou mensagem de erro para desativar a cobrança recorrente. |
Cobranças
Através da nossa API é possível criar cobranças via Pix
, boleto bancário e cartão de crédito utilizando um único
endpoint.
Todos os boletos são registrados e para cobranças via cartão de crédito contamos com um sistema de análise de risco
para garantir ao máximo a segurança nas transações.
A criação de uma cobrança acontece de forma assíncrona, pela necessidade de realizarmos as ações que garantem a
segurança da transação.
Por isso, ao solicitar a criação de uma cobrança, ela ficará com o status processing até que o boleto seja de fato
gerado e registrado ou a cobrança via cartão analisada.
Após a cobrança ser processada, o status será atualizado e você será notificado caso tenha configurado um webhook para isso.
Possíveis status
Uma cobrança pode possuir diferentes status e é importante compreender quando cada um deles acontece.
Fluxo dos status para cobranças via Pix e boleto
Ao criar uma cobrança via Pix ou boleto, ela iniciará com o status processing e será atualizado para pending quando
a cobrança for gerada e registrada.
Caso a cobrança seja paga o status será alterado para paid e caso seja executada a ação de cancelar o status será
alterada para canceled.
Fluxo dos status para cobranças via cartão de crédito
Ao criar uma cobrança via cartão de crédito ela iniciará com o status processing e ficará assim até que a análise da
transação seja concluída,
após isso, caso a transação seja recusada o status será alterado para declined.
Se a transação for sem captura automática e for aprovada o status será alterado para pre_authorized,
mas se for com captura automática e for aprovada o status será alterado para paid.
No caso de uma captura de transação pré autorizada, caso a captura seja aprovada o status será alterado para paid ou
se for recusado para declined.
Durante a comunicação com a adquirente aprovadora caso aconteça algum erro o status será alterado para reversed.
Observação: caso seja utilizada a opção de checkout via cartão, a cobrança ao ser criada
ficará com o status pending
até o cliente acessar o link de pagamento e informar os dados do cartão de crédito, após isso o fluxo dos status seguirá
como explicado anteriormente.
Estorno
Apenas cobranças via cartão de crédito com status paid ou refunded podem ser estornadas, após o estorno o status da
cobrança será alterado para refunded.
Fluxo de disputa e charge back
Quando um processo de disputa for iniciado o status da cobrança será alterado para dispute,
após a análise da disputa caso o retorno seja favorável ao estabelecimento comercial o status da cobrança voltará a
ser paid,
mas caso o retorno seja favorável ao comprador o status da cobrança será alterado para charged_back.
Split de pagamentos na cobrança
O split de pagamento é forma ideal para divisão do valor recebido de uma cobrança entre contas Cobre Fácil, isso tudo de
forma automática.
Ao criar uma cobrança você pode configurar as regras para até 2 recebedores, podendo ser pelo montante fixed que não
depende do valor recebido e porcentagem percentage que paga o % sobre o valor recebido. Para mais informações veja na
sessão split de pagamentos.
O objeto cobrança
Exemplo de JSON do objeto cobrança:
{
"id": "ZN8V0PD9W005WLRGQE5K",
"reference": null,
"payable_with": "bankslip",
"due_date": "2020-12-15",
"price": "89.98",
"fine_delay": null,
"total_paid": null,
"amount_released": null,
"fee": null,
"paid_at": null,
"payment_method": null,
"document_number": "4604618",
"url_receipt": null,
"barcode": "34191090570137951893731339210002284700000008998",
"barcode_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZUAAAAyCAYAAACUNUbZAAACHUlEQVR42u3V2wqAIAwA0P3/Txc9%0ABD6kuGkQcYIIb63W7EREHNfRXu+z126PUf9b657Gs/OycXrPPZo3u/5L93nqH9VDJS+7xnfX2Y78%0AVOq0uu9m5vfijdrV/Zep02q8mbytfJdM/Oy+XHmfal1V/4cr+Q+oQAUqUIEKVKACFahABSpQgQpU%0AoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKAC%0AFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWo%0AQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAF%0AKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQ%0AgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEK%0AVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSg%0AAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIV%0AqEAFKv9G5QSDfSad5j+EigAAAABJRU5ErkJggg==%0A",
"status": "pending",
"settings": {
"late_fee": null,
"interest": null,
"discount": null,
"warning": null,
"max_installments": null,
"send_tax_invoice": 1
},
"split_rules": [
{
"id": "O0QTKY8VNNOR5GXW7DLZ",
"payment_method": null,
"mode": "fixed",
"amount": 10,
"status": "pending",
"document": "58267712080152"
}
],
"items": [
{
"description": "Teclado",
"quantity": 1,
"price": "49.99"
},
{
"description": "Mouse",
"quantity": 1,
"price": "39.99"
}
],
"customer": {
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "37673788250",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11999999999",
"email": "joao@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "Endereço principal",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T14:01:40-03:00",
"updated_at": "2020-06-25T14:01:40-03:00",
"deleted_at": null
},
"full_name": "João da Silva",
"document": "37673788250",
"created_at": "2020-06-25T14:01:40-03:00",
"updated_at": "2020-06-25T14:01:41-03:00",
"deleted_at": null
},
"url": "https://app.cobrefacil.com.br/minha-fatura/ZN8V0PD9W005WLRGQE5K",
"url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/ZN8V0PD9W005WLRGQE5K/boleto-impressao",
"pix_br_code": null,
"pix_emv": null,
"created_at": "2020-06-25T14:01:52-03:00",
"updated_at": "2020-06-25T14:01:54-03:00"
}
Este objeto é utilizado tanto para boleto quanto cartão de crédito.
Por este motivo, para facilitar a leitura dos dados retornados alguns atributos são exibidos apenas para determinados tipos de cobrança.
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador da cobrança |
reference |
String | Código de referência utilizado para identificar a cobrança no seu sistema |
status |
String | Situação atual da cobrança, pode ser:processing o sistema está processando a cobrançapending a cobrança aguarda pagamentoreversed a cobrança foi cancelada por falha de comunicação com a adquirente aprovadora da transaçãopre_authorized a cobrança foi pré autorizada (apenas cartão)paid a cobrança foi pagadeclined o pagamento foi recusado (apenas cartão)refunded a cobrança foi parcialmente estornada (apenas cartão)canceled a cobrança foi totalmente estornada ou canceladadispute contestação da transação em análisecharged_back contestação aprovada e dinheiro devolvido |
payable_with |
String | Formas de pagamento aceitas:bankslip boletocredit cartão de créditopix PixOBS: caso deseje informar mais de uma forma de pagamento, utilize vírgula para separar os valores, exemplo: bankslip,credit |
payment_method |
String | Forma de pagamento, este campo é preenchido apenas quando a cobrança é paga e pode ser:bankslip boletocredit cartão de créditopix Pix |
price |
Float | Valor da cobrança |
total_paid |
Float | Valor pago |
amount_released |
Float | Valor liberado depois de pago, descontando a tarifa da Cobre Fácil |
fee |
Float | Tarifa da Cobre Fácil |
paid_at |
Date | Data de pagamento |
due_date |
Date | Data de vencimento da cobrança. OBS: utilizado apenas por cobranças via boleto |
fine_delay |
Float | Valor da multa da segunda via. OBS: utilizado apenas por cobranças via boleto |
document_number |
String | Número do documento. OBS: utilizado apenas por cobranças via boleto |
url_receipt |
String | URL do recibo de pagamento |
transaction_number |
String | Número de identificação da transação. OBS: utilizado apenas por cobranças via cartão de crédito |
barcode |
String | Código de barras. OBS: utilizado apenas por cobranças via boleto |
barcode_data |
String | Imagem do código de barras em formato base64. OBS: utilizado apenas por cobranças via boleto |
split_rules |
Array | Split de pagamento somente para boleto |
split_rules[].id |
String | Identificador do split de pagamento |
split_rules[].payment_method |
String | Método de pagamento do split de pagamento |
split_rules[].mode |
String | Modo que split de pagamento será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
split_rules[].amount |
Float | Porcentagem ou valor do split de pagamento |
split_rules[].status |
String | Status do split de pagamento, pode ser:pending o split de pagamento ainda não foi pagopaid o split de pagamento foi pago |
split_rules[].document |
String | CPF ou CNPJ do recebedor do split de pagamento |
items |
Array | Produtos ou serviços que estão sendo cobrados |
items[].description |
String | Descrição do item |
items[].quantity |
String | Quantidade cobrada do item |
items[].price |
Float | Valor unitário do item |
settings |
Object | Configurações da cobrança. OBS: utilizado apenas por cobranças do tipo bankslip e all |
settings.late_fee |
Object | Multa por atraso |
settings.late_fee.mode |
String | Modo que a multa por atraso será calculada, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.late_fee.amount |
Float | Porcentagem ou valor da multa cobrada após o vencimento |
settings.interest |
Object | Juros |
settings.interest.mode |
String | Modo que o juros será calculado, pode ser:monthly_percentage porcentagem mensal sobre o valor totaldaily_percentage porcentagem diária sobre o valor totaldaily_amount valor fixo diário |
settings.interest.amount |
Float | Porcentagem ou valor dos juros cobrados após o vencimento |
settings.discount |
Object | Desconto |
settings.discount.mode |
String | Modo que o desconto será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.discount.amount |
Float | Porcentagem ou valor do desconto |
settings.discount.limit_date |
Integer | Limite de dias antes do vencimento para poder aplicar o desconto |
settings.warning |
String | Mensagem exibida no campo instruções do boleto |
settings.max_installments |
Integer | Máximo de parcelas que o cliente pode escolher ao realizar um pagamento via cartão de crédito |
settings.send_tax_invoice |
Integer | Momento em que a nota fiscal deve ser gerada:0 não deve gerar nota fiscal1 a nota fiscal deve ser gerada após confirmação do pagamento2 a nota fiscal deve ser gerada após a criação da cobrançaOBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal |
customer |
Object | Cliente da cobrança |
credit_card |
Object | Cartão de crédito utilizado OBS: utilizado apenas por cobranças via cartão de crédito |
capture |
Integer | 0 Criar uma pré-autorização para capturar posteriormente1 Capturar transação após a autorizaçãoOBS: utilizado apenas por cobranças via cartão de crédito |
request_ip |
String | Ip do cliente, utilizado na análise de risco OBS: utilizado apenas por cobranças via cartão de crédito |
url |
String | URL para visualizar a cobrança |
url_bankslip |
String | URL para visualizar apenas o boleto OBS: utilizado apenas por cobranças via boleto |
pix_br_code |
String | Representação do BR Code em formato Base64 (BR Code é o nome do padrão de QR Code para Pix) OBS: utilizado apenas por cobranças via Pix |
pix_emv |
String | Código para realizar o pagamento através da função copia-cola OBS: utilizado apenas por cobranças via Pix |
created_at |
DateTime | Data que a cobrança foi criada |
updated_at |
DateTime | Data que a cobrança foi atualizada |
Criar cobrança via Pix
curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"reference\": \"100042\",
\"payable_with\": \"pix\",
\"customer_id\": \"Y73MNPGJ18Y18V5KQODX\",
\"due_date\": \"2020-12-15\",
\"items\": [
{
\"description\": \"Teclado\",
\"quantity\": 1,
\"price\": 4999
},
{
\"description\": \"Mouse\",
\"quantity\": 1,
\"price\": 3999
}
],
\"settings\": {
\"late_fee\": {
\"mode\": \"percentage\",
\"amount\": 10
},
\"interest\": {
\"mode\": \"daily_percentage\",
\"amount\": 0.1
},
\"discount\": {
\"mode\": \"fixed\",
\"amount\": 9.99,
\"limit_date\": 5
},
\"warning\": {
\"description\": \"- Em caso de dúvidas entre em contato com nossa Central de Atendimento.\"
},
\"send_tax_invoice\": 1
}
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "2KD9LGERW897NZ6JM5V4",
"reference": "100042",
"payable_with": "pix",
"due_date": "2020-12-15",
"price": "89.98",
"fine_delay": null,
"total_paid": null,
"amount_released": null,
"fee": null,
"paid_at": null,
"payment_method": null,
"document_number": null,
"url_receipt": null,
"barcode": null,
"barcode_data": null,
"status": "processing",
"settings": {
"late_fee": {
"mode": "percentage",
"amount": "10"
},
"interest": {
"mode": "daily_percentage",
"amount": "0.1"
},
"discount": {
"mode": "fixed",
"limit_date": 5,
"amount": "9.99"
},
"warning": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento.",
"max_installments": null,
"send_tax_invoice": 1
},
"items": [
{
"description": "Teclado",
"quantity": 1,
"price": "49.99"
},
{
"description": "Mouse",
"quantity": 1,
"price": "39.99"
}
],
"customer": {
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "12345678909",
"personal_name": "João da Silva Machado",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joaosilva@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "AP 42",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
},
"full_name": "João da Silva Machado",
"document": "12345678909",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
},
"url": "https://app.cobrefacil.com.br/minha-fatura/2KD9LGERW897NZ6JM5V4",
"created_at": "2020-06-25T10:14:22-03:00",
"updated_at": "2020-06-25T10:14:22-03:00"
}
}
Para que uma cobrança via Pix possa ser criada é necessário respeitar algumas regras sobre:
Vencimento e valor:
- O vencimento deve ser igual ou maior a data atual
- O valor total da cobrança deve ser entre R$ 10,00 e R$ 20.000,00
Desconto, juros e multa:
- O valor do desconto não pode ser menor que R$ 0,01 e não pode ser igual ou maior ao valor total
- O valor dos juros mensal não pode ser inferior a R$ 0,30 e a porcentagem maior que 3,3% ao dia
- O valor da multa não pode ser maior que 99% do valor total
HTTP Request
POST https://api.cobrefacil.com.br/v1/invoices
BODY Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
reference |
String | Não | Código de referência utilizado para identificar a cobrança no seu sistema |
payable_with |
String | Sim | Informe pix |
customer_id |
String | Sim | Identificador do cliente |
due_date |
Date | Sim | Data de vencimento da cobrança |
items |
Array | Sim | Produtos ou serviços que estão sendo cobrados |
items[].description |
String | Sim | Descrição do item |
items[].quantity |
Float | Sim | Quantidade cobrada do item |
items[].price |
Integer | Sim | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290 |
settings |
Object | Não | Configurações da cobrança |
settings.late_fee |
Object | Não | Multa por atraso |
settings.late_fee.mode |
String | Quando settings.late_fee for informado |
Modo que a multa por atraso será calculada, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.late_fee.amount |
Float | Quando settings.late_fee for informado |
Porcentagem ou valor da multa cobrada após o vencimento |
settings.interest |
Object | Não | Juros |
settings.interest.mode |
String | Quando settings.interest for informado |
Modo que o juros será calculado, pode ser:monthly_percentage porcentagem mensal sobre o valor totaldaily_percentage porcentagem diária sobre o valor totaldaily_amount valor fixo diário |
settings.interest.amount |
Float | Quando settings.interest for informado |
Porcentagem ou valor dos juros cobrados após o vencimento |
settings.discount |
Object | Não | Desconto |
settings.discount.mode |
String | Quando settings.discount for informado |
Modo que o desconto será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.discount.amount |
Float | Quando settings.discount for informado |
Porcentagem ou valor do desconto |
settings.discount.limit_date |
Integer | Quando settings.discount for informado |
Limite de dias antes do vencimento para poder aplicar o desconto |
settings.warning |
Object | Não | Instruções gerais sobre o pagamento |
settings.warning.description |
String | Quando settings.warning for informado |
Mensagem contendo instruções gerais sobre o pagamento |
settings.send_tax_invoice |
Integer | Não | Momento em que a nota fiscal deve ser gerada:0 não deve gerar nota fiscal1 a nota fiscal deve ser gerada após confirmação do pagamento2 a nota fiscal deve ser gerada após a criação da cobrançaOBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal |
Retorno
Em caso de sucesso será retornado um objeto cobrança.
Criar cobrança via boleto
curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"reference\": \"100042\",
\"payable_with\": \"bankslip\",
\"customer_id\": \"Y73MNPGJ18Y18V5KQODX\",
\"due_date\": \"2020-12-15\",
\"split_rules\": [
{
\"document\": \"58267712080152\",
\"mode\": \"fixed\",
\"amount\": 1000
}
],
\"items\": [
{
\"description\": \"Teclado\",
\"quantity\": 1,
\"price\": 4999
},
{
\"description\": \"Mouse\",
\"quantity\": 1,
\"price\": 3999
}
],
\"settings\": {
\"late_fee\": {
\"mode\": \"percentage\",
\"amount\": 10
},
\"interest\": {
\"mode\": \"daily_percentage\",
\"amount\": 0.1
},
\"discount\": {
\"mode\": \"fixed\",
\"amount\": 9.99,
\"limit_date\": 5
},
\"warning\": {
\"description\": \"- Em caso de dúvidas entre em contato com nossa Central de Atendimento.\"
},
\"send_tax_invoice\": 1
}
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "2KD9LGERW897NZ6JM5V4",
"reference": "100042",
"payable_with": "bankslip",
"due_date": "2020-12-15",
"price": "89.98",
"fine_delay": null,
"total_paid": null,
"amount_released": null,
"fee": null,
"paid_at": null,
"payment_method": null,
"document_number": null,
"url_receipt": null,
"barcode": "34191090570137951893731339210002284700000008998",
"barcode_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZUAAAAyCAYAAACUNUbZAAACHUlEQVR42u3V2wqAIAwA0P3/Txc9%0ABD6kuGkQcYIIb63W7EREHNfRXu+z126PUf9b657Gs/OycXrPPZo3u/5L93nqH9VDJS+7xnfX2Y78%0AVOq0uu9m5vfijdrV/Zep02q8mbytfJdM/Oy+XHmfal1V/4cr+Q+oQAUqUIEKVKACFahABSpQgQpU%0AoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKAC%0AFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWo%0AQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAF%0AKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQ%0AgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEK%0AVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSg%0AAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIV%0AqEAFKv9G5QSDfSad5j+EigAAAABJRU5ErkJggg==%0A",
"status": "processing",
"settings": {
"late_fee": {
"mode": "percentage",
"amount": "10"
},
"interest": {
"mode": "daily_percentage",
"amount": "0.1"
},
"discount": {
"mode": "fixed",
"limit_date": 5,
"amount": "9.99"
},
"warning": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento.",
"max_installments": null,
"send_tax_invoice": 1
},
"split_rules": [
{
"id": "O0QTKY8VNNOR5GXW7DLZ",
"payment_method": null,
"mode": "fixed",
"amount": 10,
"status": "pending",
"document": "58267712080152"
}
],
"items": [
{
"description": "Teclado",
"quantity": 1,
"price": "49.99"
},
{
"description": "Mouse",
"quantity": 1,
"price": "39.99"
}
],
"customer": {
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "12345678909",
"personal_name": "João da Silva Machado",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joaosilva@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "AP 42",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
},
"full_name": "João da Silva Machado",
"document": "12345678909",
"created_at": "2020-06-25T09:52:48-03:00",
"updated_at": "2020-06-25T09:55:50-03:00",
"deleted_at": null
},
"url": "https://app.cobrefacil.com.br/minha-fatura/2KD9LGERW897NZ6JM5V4",
"created_at": "2020-06-25T10:14:22-03:00",
"updated_at": "2020-06-25T10:14:22-03:00"
}
}
Para que uma cobrança via boleto possa ser criada é necessário respeitar algumas regras sobre:
Vencimento e valor:
- O vencimento deve ser igual ou maior a data atual
- O valor total da cobrança deve ser entre R$ 10,00 e R$ 20.000,00
Desconto, juros e multa:
- O valor do desconto não pode ser menor que R$ 0,01 e não pode ser igual ou maior ao valor total
- O valor dos juros mensal não pode ser inferior a R$ 0,30 e a porcentagem maior que 3,3% ao dia
- O valor da multa não pode ser maior que 99% do valor total
HTTP Request
POST https://api.cobrefacil.com.br/v1/invoices
BODY Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
reference |
String | Não | Código de referência utilizado para identificar a cobrança no seu sistema |
payable_with |
String | Sim | Informe bankslip |
customer_id |
String | Sim | Identificador do cliente |
due_date |
Date | Sim | Data de vencimento da cobrança |
split_rules |
Array | Não | Array de regras de split de pagamento (divisão da cobrança), sendo no máximo duas por cobrança |
split_rules[].document |
String | Sim | Documento da conta Cobre Fácil, sendo CPF ou CNPJ, lembrando que deve ser uma conta ativa |
split_rules[].mode |
String | Sim | Modo que split de pagamento será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
split_rules[].amount |
Integer | Sim | Porcentagem ou valor do split de pagamento, exemplo: 10,5% deve ser informado como 1050 ou quando valor R$ 10,90 deve ser informado como 1090 |
items |
Array | Sim | Produtos ou serviços que estão sendo cobrados |
items[].description |
String | Sim | Descrição do item |
items[].quantity |
Float | Sim | Quantidade cobrada do item |
items[].price |
Integer | Sim | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290 |
settings |
Object | Não | Configurações da cobrança |
settings.late_fee |
Object | Não | Multa por atraso |
settings.late_fee.mode |
String | Quando settings.late_fee for informado |
Modo que a multa por atraso será calculada, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.late_fee.amount |
Float | Quando settings.late_fee for informado |
Porcentagem ou valor da multa cobrada após o vencimento |
settings.interest |
Object | Não | Juros |
settings.interest.mode |
String | Quando settings.interest for informado |
Modo que o juros será calculado, pode ser:monthly_percentage porcentagem mensal sobre o valor totaldaily_percentage porcentagem diária sobre o valor totaldaily_amount valor fixo diário |
settings.interest.amount |
Float | Quando settings.interest for informado |
Porcentagem ou valor dos juros cobrados após o vencimento |
settings.discount |
Object | Não | Desconto |
settings.discount.mode |
String | Quando settings.discount for informado |
Modo que o desconto será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.discount.amount |
Float | Quando settings.discount for informado |
Porcentagem ou valor do desconto |
settings.discount.limit_date |
Integer | Quando settings.discount for informado |
Limite de dias antes do vencimento para poder aplicar o desconto |
settings.warning |
Object | Não | Instruções do boleto |
settings.warning.description |
String | Quando settings.warning for informado |
Mensagem exibida no campo instruções do boleto |
settings.send_tax_invoice |
Integer | Não | Momento em que a nota fiscal deve ser gerada:0 não deve gerar nota fiscal1 a nota fiscal deve ser gerada após confirmação do pagamento2 a nota fiscal deve ser gerada após a criação da cobrançaOBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal |
Retorno
Em caso de sucesso será retornado um objeto cobrança.
Autorizar cobrança via cartão
curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"payable_with\": \"credit\",
\"customer_id\": \"Z8J53ROD2JK1PQ47WG0E\",
\"credit_card_id\": \"E65OPXNV9D59WM7JL402\",
\"capture\": 0,
\"session_id\": \"SESSION_CLIENT\",
\"request_ip\": \"168.190.36.98\",
\"installment\": {
\"number\": 3,
\"mode\": \"with_interest\"
},
\"items\": [
{
\"description\": \"Teclado\",
\"quantity\": 1,
\"price\": 4999
},
{
\"description\": \"Mouse\",
\"quantity\": 1,
\"price\": 3999
}
],
\"settings\": {
\"send_tax_invoice\": 1
}
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "OY4Q3NVG7VD759PRLD60",
"reference": null,
"payable_with": "credit",
"due_date": "2020-06-25",
"price": "89.98",
"total_paid": null,
"amount_released": null,
"fee": null,
"paid_at": null,
"payment_method": null,
"transaction_number": "Z777775-0716a705-b5cb-4ec7-ae13-773dbd378c71",
"url_receipt": null,
"status": "processing",
"request_ip": "168.190.36.98",
"capture": 0,
"amount_refunded": 0,
"installment": {
"mode": "with_interest",
"number": 3
},
"credit_card": {
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 1,
"first6_digits": "453900",
"last4_digits": "5497",
"brand": "visa",
"expiration_year": "2021",
"expiration_month": "12",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:03-03:00",
"deleted_at": null
},
"settings": {
"send_tax_invoice": 1
},
"items": [
{
"description": "Teclado",
"quantity": 1,
"price": "49.99"
},
{
"description": "Mouse",
"quantity": 1,
"price": "39.99"
}
],
"customer": {
"id": "Z8J53ROD2JK1PQ47WG0E",
"person_type": 1,
"ein": null,
"company_name": "COBRE FACIL LTDA ME",
"taxpayer_id": "12345678909",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joao@cobrefacil.com.br",
"email_cc": null,
"address": {
"id": "9W2LVGOPRJMR780DEJK1",
"description": "Endereço principal",
"zipcode": "01311100",
"street": "Av Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"full_name": "João da Silva",
"document": "12345678909",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"url": null,
"created_at": "2020-06-25T13:59:40-03:00",
"updated_at": "2020-06-25T13:59:40-03:00"
}
}
Na autorização de uma cobrança via cartão de crédito é possível utilizar um cartão cadastrado,
informando o id dele ou cadastrar um novo na mesma requisição de criação da cobrança
.
Ao criar uma cobrança via cartão de crédito, o sistema primeiro irá fazer uma reserva do valor cobrado e depois uma
confirmação de cobrança no saldo do portador do cartão.
Estes processos são chamados de autorização e captura e podem ser feitos juntos ou separadamente de acordo com a
necessidade.
O session_id é um identificador único da sessão do cliente, ele é utilizado na análise de risco da transação via cartão de crédito. Para funcionamento correto é obrigatório utilizar o script abaixo no seu site:
<form ...>
<input type="hidden" id="cobrefacil_session_id" value="">
</form>
<script src="https://app.cobrefacil.com.br/assets/js/credit-card-risk.js"></script>
HTTP Request
POST https://api.cobrefacil.com.br/v1/invoices
BODY Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
reference |
String | Não | Código de referência utilizado para identificar a cobrança no seu sistema |
payable_with |
String | Sim | Informe credit |
customer_id |
String | Sim | Identificador do cliente |
credit_card_id |
String | Quando credit_card não for informado |
Identificador do cartão de crédito |
credit_card |
Object | Quando credit_card_id não for informado |
Cartão de crédito |
credit_card.name |
String | Quando credit_card for informado |
Nome do portador do cartão |
credit_card.number |
String | Quando credit_card for informado |
Número do cartão |
credit_card.expiration_month |
String | Quando credit_card for informado |
Mês de expiração do cartão, deve conter 2 dígitos |
credit_card.expiration_year |
String | Quando credit_card for informado |
Ano de expiração do cartão, deve conter 4 dígitos |
credit_card.security_code |
String | Quando credit_card for informado |
Código de segurança do cartão |
capture |
Integer | Quando credit_card for informado |
0 Criar uma pré-autorização para capturar posteriormente1 Capturar transação |
request_ip |
String | Não | Ip do cliente, utilizado na análise de risco |
session_id |
String | Não | Identificador da sessão do cliente, utilizado na análise de risco |
installment |
Object | Quando credit_card for informado |
Configurações de parcelamento |
installment.number |
Integer | Quando installment for informado |
Número de parcelas, informe entre 1 e 12 |
installment.mode |
String | Quando installment for informado |
Modo de parcelamento:with_interest com juros no emissorinterest_free sem juros, com o custo já calculado no valor da transação |
items |
Array | Sim | Produtos ou serviços que estão sendo cobrados |
items[].description |
String | Sim | Descrição do item |
items[].quantity |
Float | Sim | Quantidade cobrada do item |
items[].price |
Integer | Sim | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290 |
settings.send_tax_invoice |
Integer | Não | Momento em que a nota fiscal deve ser gerada:0 não deve gerar nota fiscal1 a nota fiscal deve ser gerada após confirmação do pagamento2 a nota fiscal deve ser gerada após a criação da cobrançaOBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal |
Retorno
Em caso de sucesso será retornado um objeto cobrança.
Capturar cobrança via cartão
curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices/[ID]/capture" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"amount\": 6998
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "OY4Q3NVG7VD759PRLD60",
"reference": null,
"payable_with": "credit",
"due_date": "2020-06-25",
"price": "89.98",
"total_paid": "89.98",
"amount_released": null,
"fee": "3.85",
"paid_at": "2020-06-25",
"payment_method": "credit",
"transaction_number": "Z777775-0716a705-b5cb-4ec7-ae13-773dbd378c71",
"url_receipt": null,
"status": "paid",
"request_ip": "168.190.36.98",
"capture": 0,
"amount_refunded": 0,
"installment": {
"mode": "with_interest",
"number": 3
},
"credit_card": {
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 1,
"first6_digits": "453900",
"last4_digits": "5497",
"brand": "visa",
"expiration_year": "2021",
"expiration_month": "12",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:03-03:00",
"deleted_at": null
},
"settings": {
"send_tax_invoice": 1
},
"items": [
{
"description": "Teclado",
"quantity": 1,
"price": "49.99"
},
{
"description": "Mouse",
"quantity": 1,
"price": "39.99"
}
],
"customer": {
"id": "Z8J53ROD2JK1PQ47WG0E",
"person_type": 1,
"ein": null,
"company_name": "COBRE FACIL LTDA ME",
"taxpayer_id": "12345678909",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joao@cobrefacil.com.br",
"email_cc": null,
"address": {
"id": "9W2LVGOPRJMR780DEJK1",
"description": "Endereço principal",
"zipcode": "01311100",
"street": "Av Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"full_name": "João da Silva",
"document": "12345678909",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"url": null,
"created_at": "2020-06-25T13:59:40-03:00",
"updated_at": "2020-06-25T14:00:44-03:00"
}
}
Utilize essa opção para capturar uma transação pré autorizada, utilizando ID da cobrança.
É possível capturar apenas um valor menor ou igual ao valor total da cobrança.
HTTP Request
POST https://api.cobrefacil.com.br/v1/invoices/[ID]/capture
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador da cobrança |
BODY Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount |
Integer | Não | Valor a ser capturado em centavos, exemplo: R$ 42,90 deve ser informado como 4290quando não informado será capturado o valor total da cobrança |
Retorno
Em caso de sucesso será retornado um objeto cobrança.
Checkout via cartão
Uma outra forma de realizar uma cobrança via cartão é enviando um link para o seu cliente realizar o pagamento.
Esse processo é semelhate a autorizar uma cobrança, mas você não precisa informar os dados do cartão de crédito, isso será feito pelo cliente posteriormente.
curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"payable_with\": \"credit\",
\"customer_id\": \"Y73MNPGJ18Y18V5KQODX\",
\"due_date\": \"2020-12-15\",
\"items\": [
{
\"description\": \"Teclado\",
\"quantity\": 1,
\"price\": 4999
},
{
\"description\": \"Mouse\",
\"quantity\": 1,
\"price\": 3999
}
],
\"settings\": {
\"late_fee\": {
\"mode\": \"percentage\",
\"amount\": 10
},
\"interest\": {
\"mode\": \"daily_percentage\",
\"amount\": 0.1
},
\"discount\": {
\"mode\": \"fixed\",
\"amount\": 9.99,
\"limit_date\": 5
},
\"max_installments\": 3,
\"send_tax_invoice\": 1
}
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "OY4Q3NVG7VD759PRLD60",
"reference": null,
"payable_with": "credit",
"due_date": "2020-06-25",
"price": "89.98",
"total_paid": null,
"amount_released": null,
"fee": null,
"paid_at": null,
"payment_method": null,
"transaction_number": null,
"url_receipt": null,
"status": "pending",
"request_ip": "168.190.36.98",
"capture": 0,
"amount_refunded": 0,
"items": [
{
"description": "Teclado",
"quantity": 1,
"price": "49.99"
},
{
"description": "Mouse",
"quantity": 1,
"price": "39.99"
}
],
"customer": {
"id": "Z8J53ROD2JK1PQ47WG0E",
"person_type": 1,
"ein": null,
"company_name": "COBRE FACIL LTDA ME",
"taxpayer_id": "12345678909",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joao@cobrefacil.com.br",
"email_cc": null,
"address": {
"id": "9W2LVGOPRJMR780DEJK1",
"description": "Endereço principal",
"zipcode": "01311100",
"street": "Av Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"full_name": "João da Silva",
"document": "12345678909",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"settings": {
"late_fee": {
"mode": "percentage",
"amount": "10"
},
"interest": {
"mode": "daily_percentage",
"amount": "0.1"
},
"discount": {
"mode": "fixed",
"limit_date": 5,
"amount": "9.99"
},
"max_installments": 3,
"send_tax_invoice": 1
},
"url": null,
"created_at": "2020-06-25T13:59:40-03:00",
"updated_at": "2020-06-25T14:00:44-03:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/invoices
BODY Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
payable_with |
String | Sim | Informe credit |
customer_id |
String | Sim | Identificador do cliente |
due_date |
Date | Sim | Prazo máximo para pagamento da cobrança |
items |
Array | Sim | Produtos ou serviços que estão sendo cobrados |
items[].description |
String | Sim | Descrição do item |
items[].quantity |
Float | Sim | Quantidade cobrada do item |
items[].price |
Integer | Sim | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290 |
settings |
Object | Não | Configurações da cobrança |
settings.late_fee |
Object | Não | Multa por atraso |
settings.late_fee.mode |
String | Quando settings.late_fee for informado |
Modo que a multa por atraso será calculada, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.late_fee.amount |
Float | Quando settings.late_fee for informado |
Porcentagem ou valor da multa cobrada após o vencimento |
settings.interest |
Object | Não | Juros |
settings.interest.mode |
String | Quando settings.interest for informado |
Modo que o juros será calculado, pode ser:monthly_percentage porcentagem mensal sobre o valor totaldaily_percentage porcentagem diária sobre o valor totaldaily_amount valor fixo diário |
settings.interest.amount |
Float | Quando settings.interest for informado |
Porcentagem ou valor dos juros cobrados após o vencimento |
settings.discount |
Object | Não | Desconto |
settings.discount.mode |
String | Quando settings.discount for informado |
Modo que o desconto será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.discount.amount |
Float | Quando settings.discount for informado |
Porcentagem ou valor do desconto |
settings.discount.limit_date |
Integer | Quando settings.discount for informado |
Limite de dias antes do vencimento para poder aplicar o desconto |
settings.max_installments |
Integer | Não | Máximo de parcelas que o cliente pode escolher ao realizar o pagamento |
settings.send_tax_invoice |
Integer | Não | Momento em que a nota fiscal deve ser gerada:0 não deve gerar nota fiscal1 a nota fiscal deve ser gerada após confirmação do pagamento2 a nota fiscal deve ser gerada após a criação da cobrançaOBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal |
Retorno
Em caso de sucesso será retornado um objeto cobrança.
Detalhar cobrança
curl --location --request GET "https://api.cobrefacil.com.br/v1/invoices/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Para detalhar uma cobrança específica basta fornecer o identificador retornado na criação dela.
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "ZN8V0PD9W005WLRGQE5K",
"reference": null,
"payable_with": "bankslip",
"due_date": "2020-12-15",
"price": "89.98",
"fine_delay": null,
"total_paid": null,
"amount_released": null,
"fee": null,
"paid_at": null,
"payment_method": null,
"document_number": null,
"url_receipt": null,
"barcode": null,
"barcode_data": null,
"status": "processing",
"settings": {
"late_fee": null,
"interest": null,
"discount": null,
"warning": null,
"max_installments": null,
"send_tax_invoice": 1
},
"items": [
{
"description": "Teclado",
"quantity": 1,
"price": "49.99"
},
{
"description": "Mouse",
"quantity": 1,
"price": "39.99"
}
],
"customer": {
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "37673788250",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11999999999",
"email": "joao@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"address": {
"id": "E1V3649DR48XJQ87OMNL",
"description": "Endereço principal",
"zipcode": "01311000",
"street": "Avenida Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T14:01:40-03:00",
"updated_at": "2020-06-25T14:01:40-03:00",
"deleted_at": null
},
"full_name": "João da Silva",
"document": "37673788250",
"created_at": "2020-06-25T14:01:40-03:00",
"updated_at": "2020-06-25T14:01:41-03:00",
"deleted_at": null
},
"url": "https://app.cobrefacil.com.br/minha-fatura/ZN8V0PD9W005WLRGQE5K",
"created_at": "2020-06-25T14:01:52-03:00",
"updated_at": "2020-06-25T14:01:52-03:00"
}
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/invoices/[ID]
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador da cobrança |
Retorno
Em caso de sucesso será retornado um objeto cobrança.
Listar cobranças
curl --location --request GET "https://api.cobrefacil.com.br/v1/invoices" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "ZN8V0PD9W005WLRGQE5K",
"reference": null,
"payable_with": "bankslip",
"due_date": "2020-12-15",
"price": "89.98",
"fine_delay": null,
"total_paid": null,
"amount_released": null,
"fee": null,
"paid_at": null,
"payment_method": null,
"document_number": "4604618",
"url_receipt": null,
"barcode": "34191090406046183893431339210002484700000008998",
"barcode_data": null,
"status": "pending",
"customer": {
"id": "Y73MNPGJ18Y18V5KQODX",
"person_type": 1,
"ein": null,
"company_name": null,
"taxpayer_id": "37673788250",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11999999999",
"email": "joao@cobrefacil.com.br",
"email_cc": "maria@cobrefacil.com.br",
"full_name": "João da Silva",
"document": "37673788250",
"created_at": "2020-06-25T14:01:40-03:00",
"updated_at": "2020-06-25T14:01:41-03:00",
"deleted_at": null
},
"settings": {
"late_fee": null,
"interest": null,
"discount": null,
"warning": null,
"max_installments": null,
"send_tax_invoice": 1
},
"url": "https://app.cobrefacil.com.br/minha-fatura/ZN8V0PD9W005WLRGQE5K",
"created_at": "2020-06-25T14:01:52-03:00",
"updated_at": "2020-06-25T14:01:54-03:00"
}
]
}
Retorna uma lista paginada das cobranças existentes e os respectivos clientes.
É possível controlar a paginação e realizar buscas através de parâmetros na URL, exemplos:
Cobranças pagas em determinado período:
GET https://api.cobrefacil.com.br/v1/invoices?paid_at_start=2022-01-15&paid_at_end=2022-01-15
Cobranças com vencimento em determinado período:
GET https://api.cobrefacil.com.br/v1/invoices?due_date_start=2022-01-15&due_date_end=2022-01-15
Cobranças criadas em determinado período:
GET https://api.cobrefacil.com.br/v1/invoices?created_at_start=2022-01-15&created_at_end=2022-01-15
Cobranças atualizadas em determinado período:
GET https://api.cobrefacil.com.br/v1/invoices?updated_at_start=2022-01-15&updated_at_end=2022-01-15
Cobranças criadas recentemente:
GET https://api.cobrefacil.com.br/v1/invoices?sort_by=created_at&order_by=desc
HTTP Request
GET https://api.cobrefacil.com.br/v1/invoices
URL Parameters
| Parâmetro | Tipo | Descrição |
|---|---|---|
status |
String | Informe os status que você deseja filtrar separados por , |
reference |
String | Busca pelo código de referência utilizado para identificar a cobrança no seu sistema |
payable_with |
String | Busca pela forma de cobrança |
payment_method |
String | Busca pela forma de pagamento |
due_date_start |
Date | Retorna resultados quando due_date for igual ou maior a data informada |
due_date_end |
Date | Retorna resultados quando due_date for igual ou menor a data informada |
paid_at_start |
Date | Retorna resultados quando paid_at for igual ou maior a data informada |
paid_at_end |
Date | Retorna resultados quando paid_at for igual ou menor a data informada |
created_at_start |
Date | Retorna resultados quando created_at for igual ou maior a data informada, a data deve estar no formato YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS |
created_at_end |
Date | Retorna resultados quando created_at for igual ou menor a data informada, a data deve estar no formato YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS |
taxpayer_id |
String | Busca pelo CPF do cliente |
ein |
String | Busca pelo CNPJ da empresa |
email |
String | Busca pelo e-mail do cliente |
personal_name |
String | Busca pelo nome do cliente |
company_name |
String | Busca pelo nome da empresa |
bad_credit |
Integer | Define se devem ser retornados registros com ou sem negativação:0 Cobranças sem negativação1 Cobranças negativadas |
sort_by |
String | Campo a ser utilizado na ordenação, o padrão é created_at |
order_by |
String | Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc |
limit |
Integer | Quantidade máxima de registros que devem ser retornados, o padrão é 100 |
offset |
Integer | Número de registros a serem pulados, o padrão é 0 |
Retorno
Em caso de sucesso será retornado um array de objetos cobrança.
Estornar cobrança via cartão
curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices/[ID]/refund" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"amount\": 1000
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "OY4Q3NVG7VD759PRLD60",
"reference": null,
"payable_with": "credit",
"due_date": "2020-06-25",
"price": "89.98",
"total_paid": "89.98",
"amount_released": null,
"fee": "3.85",
"paid_at": "2020-06-25",
"payment_method": "credit",
"transaction_number": "Z133937-000260004",
"url_receipt": null,
"status": "refunded",
"request_ip": "168.190.36.98",
"capture": 0,
"amount_refunded": "10.00",
"installment": {
"mode": "with_interest",
"number": 3
},
"credit_card": {
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 1,
"first6_digits": "453900",
"last4_digits": "5497",
"brand": "visa",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:03-03:00",
"deleted_at": null
},
"settings": {
"send_tax_invoice": 1
},
"items": [
{
"description": "Teclado",
"quantity": 1,
"price": "49.99"
},
{
"description": "Mouse",
"quantity": 1,
"price": "39.99"
}
],
"customer": {
"id": "Z8J53ROD2JK1PQ47WG0E",
"person_type": 1,
"ein": null,
"company_name": "COBRE FACIL LTDA ME",
"taxpayer_id": "12345678909",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joao@cobrefacil.com.br",
"email_cc": null,
"address": {
"id": "9W2LVGOPRJMR780DEJK1",
"description": "Endereço principal",
"zipcode": "01311100",
"street": "Av Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"full_name": "João da Silva",
"document": "12345678909",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"url": null,
"created_at": "2020-06-25T13:59:40-03:00",
"updated_at": "2020-06-25T14:06:19-03:00"
}
}
É possível estornar o valor total de uma cobrança ou apenas parte dele.
Quando uma cobrança é estornada seu status é alterado para refunded.
HTTP Request
POST https://api.cobrefacil.com.br/v1/invoices/[ID]/refund
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador da cobrança |
BODY Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount |
Integer | Não | Valor a ser estornado em centavos, exemplo: R$ 42,90 deve ser informado como 4290quando não informado será estornado o valor total da cobrança |
Retorno
Em caso de sucesso será retornado um objeto cobrança.
Cancelar cobrança
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/invoices/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "OY4Q3NVG7VD759PRLD60",
"reference": null,
"payable_with": "credit",
"due_date": "2020-06-25",
"price": "89.98",
"total_paid": "89.98",
"amount_released": null,
"fee": "3.85",
"paid_at": "2020-06-25",
"payment_method": "credit",
"transaction_number": "Z133937-000260004",
"url_receipt": null,
"status": "canceled",
"request_ip": "168.190.36.98",
"capture": 0,
"amount_refunded": 10,
"installment": {
"mode": "with_interest",
"number": 3
},
"credit_card": {
"id": "E65OPXNV9D59WM7JL402",
"customer_id": "Z8J53ROD2JK1PQ47WG0E",
"default": 1,
"first6_digits": "453900",
"last4_digits": "5497",
"brand": "visa",
"expiration_year": "2021",
"expiration_month": "12",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:03-03:00",
"deleted_at": null
},
"settings": {
"send_tax_invoice": 1
},
"items": [
{
"description": "Teclado",
"quantity": 1,
"price": "49.99"
},
{
"description": "Mouse",
"quantity": 1,
"price": "39.99"
}
],
"customer": {
"id": "Z8J53ROD2JK1PQ47WG0E",
"person_type": 1,
"ein": null,
"company_name": "COBRE FACIL LTDA ME",
"taxpayer_id": "12345678909",
"personal_name": "João da Silva",
"telephone": "11988887777",
"cellular": "11988887777",
"email": "joao@cobrefacil.com.br",
"email_cc": null,
"address": {
"id": "9W2LVGOPRJMR780DEJK1",
"description": "Endereço principal",
"zipcode": "01311100",
"street": "Av Paulista",
"number": "807",
"complement": "A813 CJ 2315",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"full_name": "João da Silva",
"document": "12345678909",
"created_at": "2020-06-25T10:26:02-03:00",
"updated_at": "2020-06-25T10:26:02-03:00",
"deleted_at": null
},
"url": null,
"created_at": "2020-06-25T13:59:40-03:00",
"updated_at": "2020-06-25T14:08:55-03:00"
}
}
Ao cancelar uma cobrança o status é alterado para canceled e a ação não pode ser desfeita.
No caso de cobranças via boleto, apenas as cobranças com status pending podem ser canceladas.
Cobranças via cartão podem ser canceladas quando tiver o status pending ou pre_authorized.
HTTP Request
DELETE https://api.cobrefacil.com.br/v1/invoices/[ID]
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador da cobrança |
BODY Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cancel_tax_invoice |
Integer | Não | Cancela a nota fiscal relacionada à cobrança caso exista:0 Não1 SimO padrão é 0 |
cancel_tax_invoice_reason |
String | Não | Motivo do cancelamento da nota fiscal |
Retorno
Em caso de sucesso será retornado um objeto cobrança com os dados atualizados.
Gerar nota fiscal
O endpoint abaixo permite gerar nota fiscal para uma cobrança.
curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices/[ID]/tax-invoice" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
{
"id": "MVKLDOZJYK6Y0WXR8PQ2",
"status": "processing",
"created_at": "09/12/2022",
"url": "https://api.cobrefacil.com.br/nota-fiscal/MVKLDOZJYK6Y0WXR8PQ2"
},
[...]
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/invoices/[ID]/tax-invoice
Retorno
Em caso de sucesso será retornado um array com informações básicas das notas fiscais geradas para essa cobrança.
| Parâmetro | Tipo | Descrição |
|---|---|---|
id |
String | Identificador da cobrança |
status |
String | Status da nota fiscal |
created_at |
String | Data de criação da nota fiscal |
url |
String | URL da nota fiscal |
Split de pagamentos
O split de pagamentos é utilizado para dividir o recebimento de uma cobrança em até mais dois recebedores, que também possuam uma conta Cobre Fácil ativa, tudo isso de forma automática.
Os endpoints para esse serviço são criar, atualizar, remover e listar split de pagamentos.
Quando a cobrança for paga o valor do líquido é dividido entre os recebedores, seguindo as regras cadastradas.
O objeto split de pagamento
Exemplo de JSON do objeto split de pagamento:
{
"id": "O0QTKY8VNNOR5GXW7DLZ",
"mode": "fixed",
"amount": 10,
"status": "pending",
"document": "58267712080152"
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do split de pagamento |
mode |
String | Modo que split de pagamento será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo. Para cada cobrança só será aceito uma modalidade. |
amount |
Float | Porcentagem ou valor do split de pagamento |
status |
String | Status do split de pagamento, pode ser:pending o split de pagamento ainda não foi pagopaid o split de pagamento foi pago |
document |
String | CPF ou CNPJ do recebedor do split de pagamento |
Criar split de pagamento
Ao criar uma regra de split de pagamento você estará adicionando um novo recebedor à cobrança já existente, lembrando que essa cobrança deve estar com status pendente para que possa ser adicionado a regra. Uma cobrança pode ter no máximo duas regras de split de pagamentos.
curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices/[ID_INVOICE]/splits" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"document\": \"58267712080152\",
\"mode\": \"fixed\",
\"amount\": 1000
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "A41W8X23N78P3DZXJV974",
"mode": "fixed",
"document": "58267712080152",
"amount": "10.00",
"status": "pending"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/invoices/[ID_INVOICE]/splits
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
document |
String | Sim | CPF ou CNPJ do recebedor do split de pagamento, devendo ser uma conta ativa na Cobre Fácil |
mode |
String | Sim | Modo que split de pagamento será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo. Para cada cobrança só será aceito uma modalidade. |
amount |
Integer | Sim | Porcentagem ou valor do split de pagamento, exemplo: 10,5% deve ser informado como 1050 ou quando valor R$ 10,90 deve ser informado como 1090 |
Retorno
Em caso de sucesso será retornado um o objeto split de pagamento.
Atualizar split de pagamento
Ao atualizar uma regra de split de pagamento são necessários todos os campos da criação mais o ID a ser informado no endpoint.
Serão possíveis 20 atualizações por cobrança e somente serão aceitas se o status da cobrança for pendente pending.
curl --location --request PUT "https://api.cobrefacil.com.br/v1/invoices/[ID]/splits/[SPLIT_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
\"document\": \"58267712080152\",
\"mode\": \"fixed\",
\"amount\": 2000
}"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "A41W8X23N78P3DZXJV974",
"mode": "fixed",
"document": "58267712080152",
"amount": "20.00",
"status": "pending"
}
}
HTTP Request
PUT https://api.cobrefacil.com.br/v1/invoices/[ID]/splits/[SPLIT_ID]
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
document |
String | Sim | CPF ou CNPJ do recebedor do split de pagamento, devendo ser uma conta ativa na Cobre Fácil |
mode |
String | Sim | Modo que split de pagamento será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo. Para cada cobrança só será aceito uma modalidade. |
amount |
Integer | Sim | Porcentagem ou valor do split de pagamento, exemplo: 10,5% deve ser informado como 1050 ou quando valor R$ 10,90 deve ser informado como 1090 |
Retorno
Em caso de sucesso será retornado um objeto split de pagamento.
Remover split de pagamento
A remoção da regra de split de pagamento deve ser feita somente informando o ID.
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/invoices/[ID]/splits/[SPLIT_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
Exemplo de JSON retornado:
{
"success": true,
"data": {
"message": "Split removido com sucesso"
}
}
HTTP Request
DELETE https://api.cobrefacil.com.br/v1/invoices/[ID]/splits/[SPLIT_ID
Retorno
Em caso de sucesso será retornada uma mensagem de split removido com sucesso.
Listar split de pagamento
curl --location --request GET "https://api.cobrefacil.com.br/v1/invoices/[ID]/splits" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "105RK688N9OCZGXWQALZ",
"mode": "fixed",
"amount": "10.00",
"document": "58267712080152"
},
{
"id": "B0CW8XGLN75PADPQVV74",
"mode": "fixed",
"amount": "20.00",
"document": "37673788250"
}
]
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/invoices/[ID]/splits
Retorno
Em caso de sucesso será retornado um array de objetos split de pagamento.
Carnês de pagamento
Nossa API permite criar e cancelar seus carnês de pagamentos.
Você também pode detalhar carnês de pagamento individualmente ou listar carnês de pagamentos filtrando os atributos desejados.
Em imprimir carnê de pagamento é gerado um pdf com todos os boletos de um carnê.
O objeto carnê de pagamento
Exemplo de JSON do objeto carnê de pagamento:
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"customer": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"address": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"city": "São Paulo",
"complement": "A813 CJ 2315",
"description": "Endereço principal",
"neighborhood": "Bela Vista",
"number": "807",
"state": "SP",
"street": "Rua A",
"zipcode": "01311000",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
},
"email_cc": "maria@cobrefacil.com.br",
"cellular": "11988887777",
"company_name": null,
"document": "12345678909",
"ein": null,
"email": "joao@cobrefacil.com.br",
"full_name": "João da Silva",
"person_type": 1,
"personal_name": "João da Silva",
"taxpayer_id": "12345678909",
"telephone": "11988887777",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
},
"reference": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": "2022-01-01",
"invoices": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"barcode": null,
"barcode_data": null,
"document_number": null,
"due_date": "2022-01-01",
"reference": "XXXXXXXXXXXXXXXXXXXX",
"installment_number": 1,
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paid_at": null,
"payable_with": "bankslip",
"payment_method": null,
"price": "100.00",
"sequencial_number": "COB00000001",
"status": "pending",
"total_paid": null,
"url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX/boleto-impressao",
"url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
"url_receipt": null,
"url_tax_invoice": null,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
...
],
"items": [
{
"description": "Produto 1",
"price": "100.00",
"quantity": 1
},
],
"last_due_date": "2022-04-01",
"mode_installment": "installment_total",
"number_installments": 4,
"price_installments": "25.00",
"price_total": "100.00",
"sequencial_number": "CARNE00000001",
"settings": {
"discount": {
"mode": "fixed",
"limit_date": 1,
"amount": "10.00"
},
"interest": {
"mode": "monthly_percentage",
"amount": "10.00"
},
"late_fee": {
"mode": "percentage",
"amount": "20.00"
},
"send_tax_invoice": 0,
"warning": "Description"
},
"status": "pending",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do carnê de pagamento |
customer |
Object | Objeto cliente do carnê |
reference |
String | Código de referência utilizado para identificar o carnê no seu sistema |
first_due_date |
Date | Data da primeira cobrança do carnê de pagamento |
invoices |
Array | Array de objetos de cobrança |
items |
Array | Produtos ou serviços que estão sendo cobrados |
items[].description |
String | Descrição do item |
items[].quantity |
String | Quantidade cobrada do item |
items[].price |
Float | Valor unitário do item |
last_due_date |
Date | Data da última cobrança do carnê de pagamento |
mode_installment |
String | Quando informado installment_value o valor de cada parcela será valor total dos items informados, já no caso installment_total valor total dos items será dividido pelo número de parcelas |
number_installments |
Integer | Número de parcelas |
price_installments |
Float | Valor total de cada parcela |
price_total |
Float | Valor total somando todas as parcelas |
settings |
Object | Configurações da cobrança. OBS: utilizado apenas por cobranças do tipo bankslip e all |
settings.late_fee |
Object | Multa por atraso |
settings.late_fee.mode |
String | Modo que a multa por atraso será calculada, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.late_fee.amount |
Float | Porcentagem ou valor da multa cobrada após o vencimento |
settings.interest |
Object | Juros |
settings.interest.mode |
String | Modo que o juros será calculado, pode ser:monthly_percentage porcentagem mensal sobre o valor totaldaily_percentage porcentagem diária sobre o valor totaldaily_amount valor fixo diário |
settings.interest.amount |
Float | Porcentagem ou valor dos juros cobrados após o vencimento |
settings.discount |
Object | Desconto |
settings.discount.mode |
String | Modo que o desconto será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.discount.amount |
Float | Porcentagem ou valor do desconto |
settings.discount.limit_date |
Integer | Limite de dias antes do vencimento para poder aplicar o desconto |
settings.warning |
String | Mensagem exibida no campo instruções do boleto |
settings.max_installments |
Integer | Máximo de parcelas que o cliente pode escolher ao realizar um pagamento via cartão de crédito |
settings.send_tax_invoice |
Integer | Momento em que a nota fiscal deve ser gerada:0 não deve gerar nota fiscal1 a nota fiscal deve ser gerada após confirmação do pagamento2 a nota fiscal deve ser gerada após a criação da cobrançaOBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal |
status |
String | Status do carnê podendo ser: pending, paid ou canceled |
created_at |
DateTime | Data que o carnê de pagamento foi criado |
updated_at |
DateTime | Data que o carnê de pagamento foi atualizado |
Criar carnê de pagamento
Endpoint destinado a criação de carnê de pagamento via parâmetros. Caso o valor total dividido pelo número de parcelas não for exato, exemplo R$ 100,00 em 3 parcelas (resultado 100/3 = 33,3333..), a primeira parcela fará o compensamento da divisão para acerto do valor, ficando primeira parcela de R$ 33,34 e as outras duas de R$ 33,33 totalizando os R$ 100,00.
curl --location --request POST "https://api.cobrefacil.com.br/v1/payment-booklets" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
{
\"customer_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"customer_address_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"reference\": \"XXXXXXXXXXXXXXXXXXXX\"
\"first_due_date\" : \"2022-01-01\",
\"items\" : [
{
\"price\" : 10000,
\"description\" : \"Produto 1\"
},
{
\"price\" : 2060,
\"description\" : \"Produto 2\"
}
],
\"notification_rule_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
\"number_installments\" : 6,
\"mode_installment\" : \"installment_total\",
\"settings\" : {
\"late_fee\" : {
\"mode\" : \"percentage\",
\"amount\" : 500
},
\"interest\" : {
\"mode\" : \"monthly_percentage\",
\"amount\" : 520
},
\"discount\" : {
\"mode\" : \"percentage\",
\"amount\" : 1020,
\"limit_date\" : 1
},
\"warning\" : {
\"description\" : \"Description\"
}
}
}
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"customer": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"address": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"city": "São Paulo",
"complement": "A813 CJ 2315",
"description": "Endereço principal",
"neighborhood": "Bela Vista",
"number": "807",
"state": "SP",
"street": "Rua A",
"zipcode": "01311000",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
},
"email_cc": "maria@cobrefacil.com.br",
"cellular": "11988887777",
"company_name": null,
"document": "12345678909",
"ein": null,
"email": "joao@cobrefacil.com.br",
"full_name": "João da Silva",
"person_type": 1,
"personal_name": "João da Silva",
"taxpayer_id": "12345678909",
"telephone": "11988887777",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
},
"reference": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": "2022-01-01",
"invoices": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"barcode": null,
"barcode_data": null,
"document_number": null,
"due_date": "2022-01-01",
"reference": "XXXXXXXXXXXXXXXXXXXX",
"installment_number": 1,
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paid_at": null,
"payable_with": "bankslip",
"payment_method": null,
"price": "100.00",
"sequencial_number": "COB00000001",
"status": "pending",
"total_paid": null,
"url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX/boleto-impressao",
"url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
"url_receipt": null,
"url_tax_invoice": null,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
...
],
"items": [
{
"description": "Produto 1",
"price": "100.00",
"quantity": 1
},
],
"last_due_date": "2022-04-01",
"mode_installment": "installment_total",
"number_installments": 4,
"price_installments": "25.00",
"price_total": "100.00",
"sequencial_number": "CARNE00000001",
"settings": {
"discount": {
"mode": "fixed",
"limit_date": 1,
"amount": "10.20"
},
"interest": {
"mode": "monthly_percentage",
"amount": "10.00"
},
"late_fee": {
"mode": "percentage",
"amount": "20.00"
},
"send_tax_invoice": 0,
"warning": "Description"
},
"status": "pending",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
HTTP Request
POST https://api.cobrefacil.com.br/v1/payment-booklets
Body Params
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
customer_id |
String | Sim | Identificador do cliente |
customer_address_id |
String | Não | Identificador do endereço do cliente |
reference |
String | Não | Código de referência utilizado para identificar o carnê no seu sistema |
first_due_date |
Date | Sim | Data da primeira cobrança do carnê de pagamento |
items.*.description |
String | Sim | Descrição do produto ou serviço |
items.*.price |
Integer | Sim | preço do item, lembrando que o formato é inteiro. Exemplo: R$100,00 (cem reais) seria 10000 |
notification_rule_id |
String | Sim | Identificador da régua de cobrança |
number_installments |
Integer | Sim | Número de parcelas do carnê de pagamento |
settings |
Object | Não | Configurações da cobrança |
settings.late_fee |
Object | Não | Multa por atraso |
settings.late_fee.mode |
String | Quando settings.late_fee for informado |
Modo que a multa por atraso será calculada, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.late_fee.amount |
Float | Quando settings.late_fee for informado |
Porcentagem ou valor da multa cobrada após o vencimento |
settings.interest |
Object | Não | Juros |
settings.interest.mode |
String | Quando settings.interest for informado |
Modo que o juros será calculado, pode ser:monthly_percentage porcentagem mensal sobre o valor totaldaily_percentage porcentagem diária sobre o valor totaldaily_amount valor fixo diário |
settings.interest.amount |
Float | Quando settings.interest for informado |
Porcentagem ou valor dos juros cobrados após o vencimento |
settings.discount |
Object | Não | Desconto |
settings.discount.mode |
String | Quando settings.discount for informado |
Modo que o desconto será calculado, pode ser:percentage porcentagem sobre o valor totalfixed valor fixo |
settings.discount.amount |
Float | Quando settings.discount for informado |
Porcentagem ou valor do desconto |
settings.discount.limit_date |
Integer | Quando settings.discount for informado |
Limite de dias antes do vencimento para poder aplicar o desconto |
settings.warning |
Object | Não | Instruções gerais sobre o pagamento |
settings.warning.description |
String | Quando settings.warning for informado |
Mensagem contendo instruções gerais sobre o pagamento |
settings.send_tax_invoice |
Integer | Não | Momento em que a nota fiscal deve ser gerada:0 não deve gerar nota fiscal1 a nota fiscal deve ser gerada após confirmação do pagamento2 a nota fiscal deve ser gerada após a criação da cobrançaOBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal |
Retorno
Em caso de sucesso será retornado um objeto carnê de pagamento.
Detalhar carnê de pagamento
curl --location --request GET "https://api.cobrefacil.com.br/v1/payment-booklets/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"customer": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"address": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"city": "São Paulo",
"complement": "A813 CJ 2315",
"description": "Endereço principal",
"neighborhood": "Bela Vista",
"number": "807",
"state": "SP",
"street": "Rua A",
"zipcode": "01311000",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
},
"email_cc": "maria@cobrefacil.com.br",
"cellular": "11988887777",
"company_name": null,
"document": "12345678909",
"ein": null,
"email": "joao@cobrefacil.com.br",
"full_name": "João da Silva",
"person_type": 1,
"personal_name": "João da Silva",
"taxpayer_id": "12345678909",
"telephone": "11988887777",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
},
"reference": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": "2022-01-01",
"invoices": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"barcode": null,
"barcode_data": null,
"document_number": null,
"due_date": "2022-01-01",
"reference": "XXXXXXXXXXXXXXXXXXXX",
"installment_number": 1,
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paid_at": null,
"payable_with": "bankslip",
"payment_method": null,
"price": "100.00",
"sequencial_number": "COB00000001",
"status": "pending",
"total_paid": null,
"url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX/boleto-impressao",
"url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
"url_receipt": null,
"url_tax_invoice": null,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
...
],
"items": [
{
"description": "Produto 1",
"price": "100.00",
"quantity": 1
},
],
"last_due_date": "2022-04-01",
"mode_installment": "installment_total",
"number_installments": 4,
"price_installments": "25.00",
"price_total": "100.00",
"sequencial_number": "CARNE00000001",
"settings": {
"discount": {
"mode": "fixed",
"limit_date": 1,
"amount": "10.20"
},
"interest": {
"mode": "monthly_percentage",
"amount": "10.00"
},
"late_fee": {
"mode": "percentage",
"amount": "20.00"
},
"send_tax_invoice": 0,
"warning": "Description"
},
"status": "pending",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
Para detalhar um carnê de pagamento específico basta informar o ID retornado no momento da criação.
HTTP Request
GET https://api.cobrefacil.com.br/v1/payment-booklets/[ID]
Retorno
Em caso de sucesso será retornado um objeto carnê de pagamento.
Listar carnê de pagamentos
curl --location --request GET "https://api.cobrefacil.com.br/v1/payment-booklets" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"customer_address_id": "XXXXXXXXXXXXXXXXXXXX",
"customer_id": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": "2022-01-01",
"last_due_date": "2022-06-01",
"mode_installment": "installment_total",
"number_installments": 6,
"price_installments": 20.1,
"price_total": 120.6,
"status": "pending",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
],
"pagination": {
"total_records": 1,
"display_records": 1
}
}
Retorna uma lista paginada de carnê de pagamentos.
É possível controlar a paginação e realizar buscas através de parâmetros na URL, exemplos:
Buscar carnê-de-pagamento pelo status:
GET https://api.cobrefacil.com.br/v1/payment-booklets?status=pending
Buscar carnê-de-pagamento pelo reference:
GET https://api.cobrefacil.com.br/v1/payment-booklets?reference=XXXXXXXXXXXXXXXXXXXX
Retornar 10 registros pulando os 10 primeiros:
GET https://api.cobrefacil.com.br/v1/payment-booklets?limit=10&offset=10
HTTP Request
GET https://api.cobrefacil.com.br/v1/payment-booklets
URL Parameters
| Parâmetro | Tipo | Descrição |
|---|---|---|
customer_id |
String | Busca pelo ID do cliente |
customer_query |
String | Busca por documento (CPF/CNPJ), email ou nome do cliente |
reference |
String | Busca pelo ID externo do carnê de pagamento |
status |
String | Busca pelo status do carnê de pagamento |
sort_by |
String | Campo a ser utilizado na ordenação, o padrão é created_at |
order_by |
String | Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc |
limit |
Integer | Quantidade máxima de registros que devem ser retornados, o padrão é 100 |
offset |
Integer | Número de registros a serem pulados, o padrão é 0 |
Retorno
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do carnê de pagamento |
customer_id |
String | Identificador do cliente |
customer_address_id |
String | Identificador do endereço do cliente |
reference |
String | Código de referência utilizado para identificar o carnê no seu sistema |
first_due_date |
Date | Data da primeira cobrança do carnê de pagamento |
last_due_date |
Date | Data da última cobrança do carnê de pagamento |
mode_installment |
String | Quando informado installment_value o valor de cada parcela será valor total dos items informados, já no caso installment_total valor total dos items será dividido pelo número de parcelas |
number_installments |
Integer | Número de parcelas |
price_installments |
Float | Valor total de cada parcela |
price_total |
Float | Valor total somando todas as parcelas |
status |
String | Status do carnê podendo ser: pending, paid ou canceled |
created_at |
DateTime | Data que o carnê de pagamento foi criado |
updated_at |
DateTime | Data que o carnê de pagamento foi atualizado |
Cancelar carnê de pagamento
curl --location --req
POST "https://api.cobrefacil.com.br/v1/payment-booklets/[ID]/cancel" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"customer": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"address": {
"id": "XXXXXXXXXXXXXXXXXXXX",
"city": "São Paulo",
"complement": "A813 CJ 2315",
"description": "Endereço principal",
"neighborhood": "Bela Vista",
"number": "807",
"state": "SP",
"street": "Rua A",
"zipcode": "01311000",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
},
"email_cc": "maria@cobrefacil.com.br",
"cellular": "11988887777",
"company_name": null,
"document": "12345678909",
"ein": null,
"email": "joao@cobrefacil.com.br",
"full_name": "João da Silva",
"person_type": 1,
"personal_name": "João da Silva",
"taxpayer_id": "12345678909",
"telephone": "11988887777",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
},
"reference": "XXXXXXXXXXXXXXXXXXXX",
"first_due_date": "2022-01-01",
"invoices": [
{
"id": "XXXXXXXXXXXXXXXXXXXX",
"barcode": null,
"barcode_data": null,
"document_number": null,
"due_date": "2022-01-01",
"reference": "XXXXXXXXXXXXXXXXXXXX",
"installment_number": 1,
"notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
"paid_at": null,
"payable_with": "bankslip",
"payment_method": null,
"price": "100.00",
"sequencial_number": "COB00000001",
"status": "canceled",
"total_paid": null,
"url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX/boleto-impressao",
"url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
"url_receipt": null,
"url_tax_invoice": null,
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
...
],
"items": [
{
"description": "Produto 1",
"price": "100.00",
"quantity": 1
},
],
"last_due_date": "2022-04-01",
"mode_installment": "installment_total",
"number_installments": 4,
"price_installments": "25.00",
"price_total": "100.00",
"sequencial_number": "CARNE00000001",
"settings": {
"discount": {
"mode": "fixed",
"limit_date": 1,
"amount": "10.20"
},
"interest": {
"mode": "monthly_percentage",
"amount": "10.00"
},
"late_fee": {
"mode": "percentage",
"amount": "20.00"
},
"send_tax_invoice": 0,
"warning": "Description"
},
"status": "canceled",
"created_at": "2022-01-01 00:00:00",
"updated_at": "2022-01-01 00:00:00"
}
}
Ao cancelar um carnê de pagamento todas as cobranças em atraso e em aberto seram canceladas.
.
HTTP Request
POST https://api.cobrefacil.com.br/v1/payment-booklets/[ID]/cancel
Retorno
Em caso de sucesso será retornado um objeto carnê de pagamento com os dados atualizados.
Imprimir carnê de pagamento
curl --location --req
POST "https://api.cobrefacil.com.br/v1/payment-booklets/[ID]/cancel" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"
O endpoint é utilizado para fazer o download do PDF contendo os boletos do carnês de pagamento, sendo 3 por página.
.
HTTP Request
GET https://api.cobrefacil.com.br/v1/payment-booklets/[ID]/pdf
Retorno
Em caso de sucesso será retornado arquivo PDF com todos os boletos do carnê solicitado.
Recebíveis
Um recebível é criado quando uma cobrança via cartão de crédito é aprovada, nesse momento é identificado o quanto será recebido pela transação e quando o valor estará disponível no saldo de sua conta.
É possível listar os recebíveis por cobrança ou detalhar individualmente.
O objeto recebível
Exemplo de JSON do objeto recebível:
{
"id": "P28EM9YZL87J4KV6GO0R",
"invoice_id": "K2M5P46E7DJ710LG9ZRJ",
"installment": 1,
"status": "paid",
"amount": "21.76",
"gross_amount": "22.67",
"anticipation_fee": "0.00",
"fee": "0.91",
"expected_on": "2020-08-31",
"paid_at": "2020-07-29",
"canceled_at": null,
"created_at": "2020-07-30T16:21:48-03:00",
"updated_at": "2020-07-30T16:29:31-03:00"
}
| Atributo | Tipo | Descrição |
|---|---|---|
id |
String | Identificador do recebível |
invoice_id |
String | Identificador da cobrança |
installment |
Integer | Número da parcela a ser paga |
status |
String | Status atual do recebível, pode ser:pending o recebível foi agendado para ser pagopaid o recebível foi creditado no saldo da contacanceled o recebível foi cancelado e não será creditado no saldo da contarefunded o recebível foi estornado após o pagamento e o valor líquido será debitado do saldo |
amount |
Float | Valor líquido a receber |
gross_amount |
Float | Valor bruto do recebível |
anticipation_fee |
Float | Tarifa cobrada ao antecipar o recebimento das parcelas |
fee |
Float | Tarifa da Cobre Fácil |
expected_on |
Date | Data esperada de crédito do recebível |
paid_at |
Date | Data que o recebível foi pago |
canceled_at |
Date | Data que o recebível foi cancelado |
created_at |
DateTime | Data que o recebível foi criado |
updated_at |
DateTime | Data que o recebível foi atualizado |
Listar recebíveis por cobrança
Para listar os recebíveis de uma cobrança basta fornecer o identificador da cobrança.
curl --location --request GET "https://api.cobrefacil.com.br/v1/invoices/[ID]/receivables" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Exemplo de JSON retornado:
{
"success": true,
"data": [
{
"id": "P28EM9YZL87J4KV6GO0R",
"invoice_id": "K2M5P46E7DJ710LG9ZRJ",
"installment": 1,
"status": "paid",
"amount": "21.76",
"gross_amount": "22.67",
"anticipation_fee": "0.00",
"fee": "0.91",
"expected_on": "2020-08-31",
"paid_at": "2020-07-29",
"canceled_at": null,
"created_at": "2020-07-30T16:21:48-03:00",
"updated_at": "2020-07-30T16:29:31-03:00"
},
{
"id": "Q2GZX4WYJZ8169VD85P7",
"invoice_id": "K2M5P46E7DJ710LG9ZRJ",
"installment": 2,
"status": "pending",
"amount": "21.76",
"gross_amount": "22.67",
"anticipation_fee": "0.00",
"fee": "0.91",
"expected_on": "2020-09-30",
"paid_at": null,
"canceled_at": null,
"created_at": "2020-07-30T16:21:48-03:00",
"updated_at": "2020-07-30T16:21:48-03:00"
},
{
"id": "GZ4PMN0YJ28JR58D67X2",
"invoice_id": "K2M5P46E7DJ710LG9ZRJ",
"installment": 3,
"status": "pending",
"amount": "21.78",
"gross_amount": "22.67",
"anticipation_fee": "0.00",
"fee": "0.89",
"expected_on": "2020-10-30",
"paid_at": null,
"canceled_at": null,
"created_at": "2020-07-30T16:21:48-03:00",
"updated_at": "2020-07-30T16:21:48-03:00"
}
]
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/invoices/[ID]/receivables
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador da cobrança |
Retorno
Em caso de sucesso será retornado um objeto recebível.
Detalhar recebível
curl --location --request GET "https://api.cobrefacil.com.br/v1/receivables/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]
Para detalhar um recebível basta fornecer o identificador dele.
Exemplo de JSON retornado:
{
"success": true,
"data": {
"id": "P28EM9YZL87J4KV6GO0R",
"invoice_id": "K2M5P46E7DJ710LG9ZRJ",
"installment": 1,
"status": "paid",
"amount": "21.76",
"gross_amount": "22.67",
"anticipation_fee": "0.00",
"fee": "0.91",
"expected_on": "2020-08-31",
"paid_at": "2020-07-29",
"canceled_at": null,
"created_at": "2020-07-30T16:21:48-03:00",
"updated_at": "2020-07-30T16:29:31-03:00"
}
}
HTTP Request
GET https://api.cobrefacil.com.br/v1/receivables/[ID]
URL Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
String | Sim | Identificador do recebível |
Retorno
Em caso de sucesso será retornado um objeto recebível.
Notas fiscais (NFS-e)
A API da Cobre Fácil permite a emissão de NFS-e de forma simples e rápida. Para isso, é necessário que o cliente tenha a configuração de notas fiscais feita corretamente e que o município esteja homologado para emissão de notas fiscais via webservice.
O objeto da nota simplificado
| Atributo | Tipo | Descrição |
|---|---|---|
id |
string |
Identificador da nota |
reference |
string |
Referência da cobrança, exemplo: COB0001 ou Avulsa quando não houver uma cobrança associada |
number |
string |
Número da nota |
customer_name |
string |
Nome do cliente |
status |
string |
Status da nota |
status_cancellation |
string |
Status do cancelamento da nota |
created_at |
string |
Data de criação da nota |
url |
string |
URL para visualização da nota |
O objeto da nota
| Atributo | Tipo | Descrição |
|---|---|---|
id |
Integer | Identificador da nota |
status |
String | Status da nota |
status_cancellation |
String | Status do cancelamento da nota |
amount |
Float | Valor do serviço prestado |
rps_series |
String | Série do RPS |
rps_lot |
Integer | Lote do RPS |
rps_number |
Integer | Número do RPS |
number |
String | Número da nota |
note |
Text | Observação da nota |
cancellation_reason |
Text | Motivo do cancelamento da nota |
error_message |
Text | Mensagem de erro |
customer_id |
String | Identificador do cliente |
invoice_id |
String | Identificador da cobrança |
url_tax_invoice |
String | URL da nota |
services |
Array | Array com os serviços prestados |
services.code |
String | Código do serviço prestado |
services.service_code_taxation |
String | Código de tributação do serviço prestado |
services.description |
String | Descrição do serviço prestado |
services.quantity |
Integer | Quantidade do serviço prestado |
services.price |
Float | Valor do serviço prestado |
services.iss_aliquot |
Float | Alíquota do ISS |
services.cnae |
String | CNAE do serviço prestado |
created_at |
String | Data de criação da nota no formato YYYY-MM-DD |
canceled_at |
String | Data de cancelamento da nota no formato YYYY-MM-DD |
Status da nota
| Status da nota | Descrição |
|---|---|
processing |
A nota está sendo processada |
active |
A nota foi emitida com sucesso |
rejected |
A nota foi rejeitada |
canceled |
A nota foi cancelada |
Status cancelamento da nota
| Status da nota | Descrição |
|---|---|
waiting |
A nota está aguardando o cancelamento |
success |
A nota foi cancelada com sucesso |
rejected |
O cancelamento foi rejeitado pelo provedor, a nota retorna para o status active |
Criar uma NFS-e avulsa
Para criar uma NFS-e avulsa, sem um cobrança atrelada, é necessário informar os dados do tomador, itens, valor e demais informações da nota. O exemplo abaixo mostra como criar uma NFS-e com os dados mínimos necessários.
curl --location --request POST "https://api.cobrefacil.com.br/v1/tax-invoices" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \
HTTP Request
POST https://api.cobrefacil.com.br/v1/tax-invoices
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
note |
String | Não | Descrição da nota fiscal |
customer_id |
String | Sim | ID do cliente |
plans_id |
Integer | Sim* | IDs do plano |
items |
Array | Sim* | Array de itens da nota fiscal |
items[].product_service_id |
String | Sim | ID do produto ou serviço |
items[].description |
String | Não | Quantidade do item |
items[].quantity |
Integer | Não | Quantidade do item, se não informado será 1 |
items[].price |
Integer | Não | Valor unitário do item em centavos exemplo: R$ 42,90 deve ser informado como 4290, caso não informado será considerado o valor do produto ou serviço |
- É necessário informar o
plans_idouitems, não é possível informar os dois ao mesmo tempo.
Retorno
Em caso de sucesso será retornado um o objeto da nota.
Listar notas
curl --location --request GET "https://api.cobrefacil.com.br/v1/tax-invoices" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \
HTTP Request
GET https://api.cobrefacil.com.br/v1/tax-invoices
Retorno
Em caso de sucesso será retornado um array com os objetos das notas (simplificado).
Obter uma nota
curl --location --request GET "https://api.cobrefacil.com.br/v1/tax-invoices/{ID}" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \
HTTP Request
GET https://api.cobrefacil.com.br/v1/tax-invoices/{ID}
Retorno
Em caso de sucesso será retornado um o objeto da nota.
Cancelar uma nota
O cancelamento de uma nota é feito através do endpoint de notas, informando o ID da nota que deseja cancelar. Cada prefeitura possui suas regras para cancelamento de notas, por isso é importante verificar as regras da prefeitura antes de realizar o cancelamento.
curl --location --request DELETE "https://api.cobrefacil.com.br/v1/tax-invoices/{ID}" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \
Body Params
| Atributo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
reason |
String | Não | Motivo do cancelamento |
HTTP Request
DELETE https://api.cobrefacil.com.br/v1/tax-invoices/{ID}
Retorno
Em caso de sucesso será retornado um o objeto da nota.
Reenviar uma nota
O reenvio de uma nota é feito através do endpoint de notas, informando o ID da nota que deseja reenviar. Deve ser utilizado em caso de mudanças nas configurações de envio de notas ou de certificado digital.
curl --location --request POST "https://api.cobrefacil.com.br/v1/tax-invoices/{ID}/retry" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \
HTTP Request
POST https://api.cobrefacil.com.br/v1/tax-invoices/{ID}/retry
Retorno
Em caso de sucesso será retornado uma mensagem Nota fiscal reenviada com sucesso! ou erros se possuir.