NAV Navbar
cURL

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 utilizar 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 200, 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 e updated_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\"
}"
<?php

use cobrefacil\sdkphp\Client;

$client = new Client('APP_ID', 'SECRET');

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.

HTTP Request

POST /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",
        "price": 49.9,
        "fine_delay": null,
        "reference_duedate": "2020-04-13",
        "reference_price": 49.9,
        "total_paid": null,
        "amount_released": null,
        "paid_at": null,
        "payment_method": null,
        "document_number": null,
        "barcode": null,
        "status": "pending",
        "created_at": "2020-04-03T13:54:59+00:00",
        "updated_at": "2020-04-03T13:54:59+00:00",
        "settings": null,
        "items": [],
        "customer": {
            "id": "Z8J53ROD2JK1PQ47WG0E",
            "person_type": 1,
            "ein": null,
            "company_name": "COBRE FACIL LTDA ME",
            "taxpayer_id": "12345678909",
            "personal_name": "Fulano da Silva",
            "telephone": "1199999999999",
            "cellular": "17997324082",
            "email": "fulano@cobrefacil.com.br",
            "email_cc": null,
            "created_at": "2020-04-03T11:31:52+00:00",
            "updated_at": "2020-04-03T11:31:52+00:00",
            "address": {
                "id": "9W2LVGOPRJMR780DEJK1",
                "description": "AP",
                "zipcode": "15084060",
                "street": "Rua Chaim José Elias",
                "number": "930",
                "complement": "Ap 33",
                "neighborhood": "Vila Sinibaldi",
                "city": "São José do Rio Preto",
                "state": "SP",
                "created_at": "2020-04-03T11:31:52+00:00",
                "updated_at": "2020-04-03T11:31:52+00:00"
            }
        }
    }
}

Para facilitar a notificação de seu sistema quando algum evento importante acontece, nós disponibilizamos a funcionalidade de webhooks.

A url utilizada no envio desses eventos deve ser informada no painel de sua conta.

Estrutura base do JSON enviado

Atributo Tipo Descrição
event String Evento que disparou o envio das informaçõpes
data Object O objeto atualizado referente ao evento

Eventos disponíveis

Evento Descrição
invoice.created Cobrança criada
invoice.paid Cobrança paga
invoice.canceled Cobrança cancelada
invoice.viewed Cobrança visualizada

Clientes

Nossa API permite criar, atualizar e remover seus clientes.
Você também pode detalhar clientes individualmente ou listar clientes filtrando pelos atributos desejados.

O objeto cliente

Exemplo de JSON do objeto cliente:

{
    "success": true,
    "data": {
        "id": "YOM7EKJV9D89WP6DL0G5",
        "person_type": 1,
        "ein": null,
        "company_name": null,
        "taxpayer_id": "12345678909",
        "personal_name": "Fulano da Silva",
        "telephone": "11999999999",
        "cellular": "11888888888",
        "email": "fulano@cobrefacil.com.br",
        "email_cc": "ciclano@cobrefacil.com.br",
        "created_at": "2019-12-20T10:30:52+00:00",
        "updated_at": "2019-12-20T10:30:52+00:00",
        "address": {
            "id": "1NMK7EVOR60RDJ958046",
            "description": "AP",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "neighborhood": "Bela Vista",
            "city": "São Paulo",
            "state": "SP",
            "created_at": "2019-12-20T10:30:52+00:00",
            "updated_at": "2019-12-20T10:30:52+00:00"
        }
    }
}
Atributo Tipo Descrição
id String Identificação do cliente
person_type Integer 1 Pessoa física
2 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
created_at DateTime Data que o cliente foi criado
updated_at DateTime Data que o cliente foi atualizado
address Object 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

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\": \"Fulano da Silva\",
    \"telephone\": \"11999999999\",
    \"cellular\": \"11888888888\",
    \"email\": \"fulano@cobrefacil.com.br\",
    \"email_cc\": \"ciclano@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": "YOM7EKJV9D89WP6DL0G5",
        "person_type": 1,
        "ein": null,
        "company_name": null,
        "taxpayer_id": "12345678909",
        "personal_name": "Fulano da Silva",
        "telephone": "11999999999",
        "cellular": "11888888888",
        "email": "fulano@cobrefacil.com.br",
        "email_cc": "ciclano@cobrefacil.com.br",
        "created_at": "2019-12-20T10:30:52+00:00",
        "updated_at": "2019-12-20T10:30:52+00:00",
        "address": {
            "id": "1NMK7EVOR60RDJ958046",
            "description": "AP",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "neighborhood": "Bela Vista",
            "city": "São Paulo",
            "state": "SP",
            "created_at": "2019-12-20T10:30:52+00:00",
            "updated_at": "2019-12-20T10:30:52+00:00"
        }
    }
}

HTTP Request

POST /customers

Body Params

Parâmetro Tipo Obrigatório Descrição
person_type Integer Sim 1 Pessoa física
2 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

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\": \"Fulano da Silva Machado\",
    \"email\": \"fulanosilva@cobrefacil.com.br\",
    \"address\": {
        \"description\": \"AP 42\"
    }
}"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "YOM7EKJV9D89WP6DL0G5",
        "person_type": 1,
        "ein": null,
        "company_name": null,
        "taxpayer_id": "12345678909",
        "personal_name": "Fulano da Silva Machado",
        "telephone": "11999999999",
        "cellular": "11888888888",
        "email": "fulanosilva@cobrefacil.com.br",
        "email_cc": "ciclano@cobrefacil.com.br",
        "created_at": "2019-12-20T10:30:52+00:00",
        "updated_at": "2019-12-21T13:50:11+00:00",
        "address": {
            "id": "1NMK7EVOR60RDJ958046",
            "description": "AP 42",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "neighborhood": "Bela Vista",
            "city": "São Paulo",
            "state": "SP",
            "created_at": "2019-12-20T10:30:52+00:00",
            "updated_at": "2019-12-21T13:50:11+00:00"
        }
    }
}

Ao atualizar um cliente é necessário enviar apenas os dados que deseja alterar.

HTTP Request

PUT /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ísica
2 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

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": "YOM7EKJV9D89WP6DL0G5",
        "person_type": 1,
        "ein": null,
        "company_name": null,
        "taxpayer_id": "12345678909",
        "personal_name": "Fulano da Silva",
        "telephone": "11999999999",
        "cellular": "11888888888",
        "email": "fulano@cobrefacil.com.br",
        "email_cc": "ciclano@cobrefacil.com.br",
        "created_at": "2019-12-20T10:30:52+00:00",
        "updated_at": "2019-12-20T10:30:52+00:00",
        "address": {
            "id": "1NMK7EVOR60RDJ958046",
            "description": "AP",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "neighborhood": "Bela Vista",
            "city": "São Paulo",
            "state": "SP",
            "created_at": "2019-12-20T10:30:52+00:00",
            "updated_at": "2019-12-20T10:30:52+00:00"
        }
    }
}

Para detalhar um cliente específico basta informar o ID retornado no momento da criação.

HTTP Request

GET /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": "YOM7EKJV9D89WP6DL0G5",
            "person_type": 1,
            "ein": null,
            "company_name": null,
            "taxpayer_id": "12345678909",
            "personal_name": "Fulano da Silva",
            "telephone": "11999999999",
            "cellular": "11888888888",
            "email": "fulano@cobrefacil.com.br",
            "email_cc": "ciclano@cobrefacil.com.br",
            "created_at": "2019-12-20T10:30:52+00:00",
            "updated_at": "2019-12-20T10:30:52+00:00",
            "address": {
                "id": "1NMK7EVOR60RDJ958046",
                "description": "AP",
                "zipcode": "01311000",
                "street": "Avenida Paulista",
                "number": "123",
                "complement": "Ap 42",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "state": "SP",
                "created_at": "2019-12-20T10:30:52+00:00",
                "updated_at": "2019-12-20T10:30:52+00:00"
            }
        }
    ]
}

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=fulano@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 /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 é id
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 clientes com os atributos:

Atributo Tipo Descrição
id String Identificador do cliente
person_type Integer 1 Pessoa física
2 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
created_at DateTime Data que o cliente foi criado
updated_at DateTime Data que o cliente foi atualizado
address Object 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

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": "YOM7EKJV9D89WP6DL0G5",
        "person_type": 1,
        "ein": null,
        "company_name": null,
        "taxpayer_id": "12345678909",
        "personal_name": "Fulano da Silva",
        "telephone": "11999999999",
        "cellular": "11888888888",
        "email": "fulano@cobrefacil.com.br",
        "email_cc": "ciclano@cobrefacil.com.br",
        "created_at": "2019-12-20T10:30:52+00:00",
        "updated_at": "2020-01-31T15:44:32+00:00",
        "address": {
            "id": "1NMK7EVOR60RDJ958046",
            "description": "AP",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "neighborhood": "Bela Vista",
            "city": "São Paulo",
            "state": "SP",
            "created_at": "2019-12-20T10:30:52+00:00",
            "updated_at": "2020-01-31T15:44:32+00: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 /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.

Cobranças

Nossa API permite criar e cancelar suas cobranças.
Você também pode detalhar cobranças individualmente ou listar cobranças filtrando pelos atributos desejados.

O objeto cobrança

JSON do objeto cobrança:

{
    "success": true,
    "data": {
        "id": "K3DNR024WO9XQ1ZO6LM8",
        "due_date": "2020-03-15",
        "price": 69.98,
        "fine_delay": null,
        "reference_duedate": null,
        "reference_price": null,
        "total_paid": null,
        "amount_released": null,
        "paid_at": null,
        "payment_method": null,
        "document_number": null,
        "barcode": null,
        "status": "pending",
        "created_at": "2020-01-15T16:37:52+00:00",
        "updated_at": "2020-01-15T16:37:52+00:00",
        "items": [
            {
                "description": "Teclado",
                "quantity": 1,
                "price": 39.99
            },
            {
                "description": "Mouse",
                "quantity": 1,
                "price": 29.99
            }
        ],
        "settings": {
            "late_fee": {
                "mode": "percentage",
                "amount": 10
            },
            "interest": {
                "mode": "daily_percentage",
                "amount": 0.1
            },
            "discount": {
                "mode": "fixed",
                "amount": 9.99,
                "limit_date": 5
            },
            "warning": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento.",
            "payable_with": "bankslip"
        },
        "customer": {
            "id": "YOM7EKJV9D89WP6DL0G5",
            "person_type": 1,
            "ein": null,
            "company_name": null,
            "taxpayer_id": "12345678909",
            "personal_name": "Fulano da Silva",
            "telephone": "11999999999",
            "cellular": "11888888888",
            "email": "fulano@cobrefacil.com.br",
            "email_cc": "ciclano@cobrefacil.com.br",
            "created_at": "2019-12-20T10:30:52+00:00",
            "updated_at": "2019-12-20T10:30:52+00:00",
            "address": {
                "id": "1NMK7EVOR60RDJ958046",
                "description": "AP",
                "zipcode": "01311000",
                "street": "Avenida Paulista",
                "number": "123",
                "complement": "Ap 42",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "state": "SP",
                "created_at": "2019-12-20T10:30:52+00:00",
                "updated_at": "2019-12-20T10:30:52+00:00"
            }
        },
        "url": "https://app.cobrefacil.com.br/minha-fatura/2926cee6-8565-430f-af27-e75c08eca0fa"
    }
}
Atributo Tipo Descrição
id String Identificação da cobrança
due_date Date Data de vencimento da cobrança
price Float Valor da cobrança
fine_delay Float Valor da multa da segunda via
reference_duedate Date Data de referência da segunda via
reference_price Float Valor de referência da segunda via
total_paid Float Valor pago
amount_released Float Valor liberado depois de pago, descontando a taxa da Cobre Fácil
paid_at Date Date de pagamento
payment_method String Forma de pagamento
document_number String Número do documento
barcode String Código de barras
status String Possíveis status processing, pending, paid e canceled
created_at DateTime Data que a cobrança foi criada
updated_at DateTime Data que a cobrança foi atualizada
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
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 total
fixed 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 total
daily_percentage porcentagem diária sobre o valor total
daily_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 total
fixed 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
customer Object Cliente da cobrança
url String URL para visualizar a 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 "{
    \"customer_id\": \"YOM7EKJV9D89WP6DL0G5\",
    \"due_date\": \"2020-03-15\",
    \"items\": [
        {
            \"description\": \"Teclado\",
            \"quantity\": 1,
            \"price\": 3999
        },
        {
            \"description\": \"Mouse\",
            \"quantity\": 1,
            \"price\": 2999
        }
    ],
    \"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.\",
        }
    }
}"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "K3DNR024WO9XQ1ZO6LM8"
    }
}

Este endpoint criará uma nova cobrança para o cliente informado.

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.
Após isso, a cobrança ficará com o status pending e o webhook será executado, enviando o evento invoice.created e os dados completos da cobrança.

Para que a cobrança possa ser criada é necessário respeitar algumas regras sobre:

Vencimento e valor:

Desconto, juros e multa:

HTTP Request

POST /invoices

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
customer_id String Sim Identificação 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 total
fixed 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 total
daily_percentage porcentagem diária sobre o valor total
daily_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 total
fixed 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
warning Object Não Instruções do boleto
warning.description String Quando settings.warning for informado Mensagem exibida no campo instruções do boleto

Retorno

Em caso de sucesso será retornado um JSON contendo o id da cobrança criada.
Para obter os dados completos é necessário aguardar o envio dos dados via webhook.

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": "K3DNR024WO9XQ1ZO6LM8",
        "due_date": "2020-03-15",
        "price": 69.98,
        "fine_delay": null,
        "reference_duedate": null,
        "reference_price": null,
        "total_paid": null,
        "amount_released": null,
        "paid_at": null,
        "payment_method": null,
        "document_number": null,
        "barcode": null,
        "status": "pending",
        "created_at": "2020-01-15T16:37:52+00:00",
        "updated_at": "2020-01-15T16:37:52+00:00",
        "url": "https://app.cobrefacil.com.br/minha-fatura/2926cee6-8565-430f-af27-e75c08eca0fa",
        "items": [
            {
                "description": "Teclado",
                "quantity": 1,
                "price": 39.99
            },
            {
                "description": "Mouse",
                "quantity": 1,
                "price": 29.99
            }
        ],
        "settings": {
            "late_fee": {
                "mode": "percentage",
                "amount": 10
            },
            "interest": {
                "mode": "daily_percentage",
                "amount": 0.1
            },
            "discount": {
                "mode": "fixed",
                "amount": 9.99,
                "limit_date": 5
            },
            "warning": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento.",
            "payable_with": "bankslip"
        },
        "customer": {
            "id": "YOM7EKJV9D89WP6DL0G5",
            "person_type": 1,
            "ein": null,
            "company_name": null,
            "taxpayer_id": "12345678909",
            "personal_name": "Fulano da Silva",
            "telephone": "11999999999",
            "cellular": "11888888888",
            "email": "fulano@cobrefacil.com.br",
            "email_cc": "ciclano@cobrefacil.com.br",
            "created_at": "2019-12-20T10:30:52+00:00",
            "updated_at": "2019-12-20T10:30:52+00:00",
            "address": {
                "id": "1NMK7EVOR60RDJ958046",
                "description": "AP",
                "zipcode": "01311000",
                "street": "Avenida Paulista",
                "number": "123",
                "complement": "Ap 42",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "state": "SP",
                "created_at": "2019-12-20T10:30:52+00:00",
                "updated_at": "2019-12-20T10:30:52+00:00"
            }
        }
    }
}

HTTP Request

GET /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": "K5M3JG9ZWNVX2L4YOEQP",
            "due_date": "2020-03-15",
            "price": 69.98,
            "fine_delay": null,
            "reference_duedate": null,
            "reference_price": null,
            "total_paid": null,
            "amount_released": null,
            "paid_at": null,
            "payment_method": null,
            "document_number": null,
            "barcode": null,
            "status": "pending",
            "created_at": "2020-01-30T19:42:14+00:00",
            "updated_at": "2020-01-30T19:42:14+00:00",
            "customer": {
                "id": "YOM7EKJV9D89WP6DL0G5",
                "person_type": 1,
                "ein": null,
                "company_name": null,
                "taxpayer_id": "12345678909",
                "personal_name": "Fulano da Silva",
                "telephone": "11999999999",
                "cellular": "11888888888",
                "email": "fulano@cobrefacil.com.br",
                "email_cc": "ciclano@cobrefacil.com.br",
                "created_at": "2019-12-20T10:30:52+00:00",
                "updated_at": "2019-12-20T10:30:52+00:00"
            },
            "settings": {
                "late_fee": {
                    "mode": "percentage",
                    "amount": 10
                },
                "interest": {
                    "mode": "daily_percentage",
                    "amount": 0.1
                },
                "discount": {
                    "mode": "fixed",
                    "amount": 9.99,
                    "limit_date": 5
                },
                "warning": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento.",
                "payable_with": "bankslip"
            },
            "url": "https://app.cobrefacil.com.br/minha-fatura/2926cee6-8565-430f-af27-e75c08eca0fa"
        }
    ]
}

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?field_by=paid_at&start_date=2020-01-15&final_date=2020-01-15

Cobranças criadas recentemente:
GET https://api.cobrefacil.com.br/v1/invoices?sort_by=created_at&order_by=desc

HTTP Request

GET /invoices

URL Parameters

Parâmetro Tipo Descrição
status String Informe os status que você deseja filtrar separados por ,
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
sort_by String Campo a ser utilizado na ordenação, o padrão é id
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 cobranças com os atributos:

Atributo Tipo Descrição
id String Identificação da cobrança
due_date Date Vencimento da cobrança
price Float Valor da cobrança
fine_delay Float Valor que foi gerado de multa quando é segunda via
reference_duedate Date Data de referência da segunda via
reference_price Float Valor de referência da segunda via
total_paid Float Valor pago
amount_released Float Valor liberado depois de pago, descontando a taxa da Cobre Fácil
paid_at Date Data que a cobrança foi paga
payment_method String Forma de pagamento
document_number String Número do documento
barcode String Código de barras
status String Status atual da cobrança
created_at DateTime Data que a cobrança foi criada
updated_at DateTime Data que a cobrança foi atualizada
customer Object Cliente da cobrança
customer.id String Identificador do cliente
customer.person_type Integer Tipo de pessoa, física ou jurídica
customer.ein String CNPJ da empresa
customer.company_name String Nome da empresa
customer.taxpayer_id String CPF do cliente
personal_name String Nome do cliente
customer.telephone String Telefone fixo
customer.cellular String Telefone celular
customer.email String E-mail do cliente
customer.email_cc String E-mail que receberá cópias das mensagens enviadas
customer.created_at DateTime Data que o cliente foi criado
customer.updated_at DateTime Data que o cliente foi atualizado
settings Object Configurações da cobrança
settings.late_fee Object Multa por atraso
settings.late_fee.mode String Modo que a multa por atraso será calculada, pode ser percentage ou fixed
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, daily_percentage ou daily_amount
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 ou fixed
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
url String URL para visualizar a 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": "K3DNR024WO9XQ1ZO6LM8",
        "due_date": "2020-03-15",
        "price": 69.98,
        "fine_delay": null,
        "reference_duedate": null,
        "reference_price": null,
        "total_paid": null,
        "amount_released": null,
        "paid_at": null,
        "payment_method": null,
        "document_number": null,
        "barcode": null,
        "status": "canceled",
        "created_at": "2020-01-15T16:37:52+00:00",
        "updated_at": "2020-01-15T16:43:11+00:00",
        "items": [
            {
                "description": "Teclado",
                "quantity": 1,
                "price": 39.99
            },
            {
                "description": "Mouse",
                "quantity": 1,
                "price": 29.99
            }
        ],
        "settings": {
            "late_fee": {
                "mode": "percentage",
                "amount": 10
            },
            "interest": {
                "mode": "daily_percentage",
                "amount": 0.1
            },
            "discount": {
                "mode": "fixed",
                "amount": 9.99,
                "limit_date": 5
            },
            "warning": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento.",
            "payable_with": "bankslip"
        },
        "customer": {
            "id": "YOM7EKJV9D89WP6DL0G5",
            "person_type": 1,
            "ein": null,
            "company_name": null,
            "taxpayer_id": "12345678909",
            "personal_name": "Fulano da Silva",
            "telephone": "11999999999",
            "cellular": "11888888888",
            "email": "fulano@cobrefacil.com.br",
            "email_cc": "ciclano@cobrefacil.com.br",
            "created_at": "2019-12-20T10:30:52+00:00",
            "updated_at": "2019-12-20T10:30:52+00:00",
            "address": {
                "id": "1NMK7EVOR60RDJ958046",
                "description": "AP",
                "zipcode": "01311000",
                "street": "Avenida Paulista",
                "number": "123",
                "complement": "Ap 42",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "state": "SP",
                "created_at": "2019-12-20T10:30:52+00:00",
                "updated_at": "2019-12-20T10:30:52+00:00"
            }
        },
        "url": "https://app.cobrefacil.com.br/minha-fatura/2926cee6-8565-430f-af27-e75c08eca0fa"
    }
}

Apenas cobranças com status pending podem ser canceladas e essa ação não pode ser desfeita.

HTTP Request

DELETE /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 com os dados atualizados.