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\"
}"

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 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",
        "price": 49.9,
        "fine_delay": null,
        "total_paid": null,
        "amount_released": null,
        "paid_at": null,
        "payment_method": null,
        "document_number": null,
        "barcode": null,
        "status": "pending",
        "settings": null,
        "items": [],
        "customer": {
            "id": "Z8J53ROD2JK1PQ47WG0E",
            "person_type": 1,
            "ein": null,
            "company_name": "COBRE FACIL LTDA ME",
            "taxpayer_id": "12345678909",
            "personal_name": "João da Silva",
            "telephone": "1199999999999",
            "cellular": "17997324082",
            "email": "joao@cobrefacil.com.br",
            "email_cc": null,
            "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"
            },
            "created_at": "2020-04-03T11:31:52+00:00",
            "updated_at": "2020-04-03T11:31:52+00:00"
        },
        "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 de eventos por webhooks você precisa cadastrar no painel da sua conta as URLs do seu sistema 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 10 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çõpes
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

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:

{
    "id": "Y73MNPGJ18Y18V5KQODX",
    "person_type": 1,
    "ein": null,
    "company_name": null,
    "taxpayer_id": "12345678909",
    "personal_name": "João da Silva",
    "telephone": "11999999999",
    "cellular": "11888888888",
    "email": "joao@cobrefacil.com.br",
    "email_cc": "maria@cobrefacil.com.br",
    "full_name": "João da Silva",
    "document": "12345678909",
    "address": {
        "id": "E1V3649DR48XJQ87OMNL",
        "description": "AP",
        "zipcode": "01311000",
        "street": "Avenida Paulista",
        "number": "123",
        "complement": "Ap 42",
        "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"
    },
    "created_at": "2020-06-25T09:52:48-03:00",
    "updated_at": "2020-06-25T09:52:48-03:00"
}
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
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
created_at DateTime Data que o cliente foi criado
updated_at DateTime Data que o cliente 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\": \"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": "11999999999",
        "cellular": "11888888888",
        "email": "joao@cobrefacil.com.br",
        "email_cc": "maria@cobrefacil.com.br",
        "address": {
            "id": "E1V3649DR48XJQ87OMNL",
            "description": "AP",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "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"
        },
        "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"
    }
}

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í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\": \"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": "11999999999",
        "cellular": "11888888888",
        "email": "joaosilva@cobrefacil.com.br",
        "email_cc": "maria@cobrefacil.com.br",
        "address": {
            "id": "E1V3649DR48XJQ87OMNL",
            "description": "AP 42",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "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"
        },
        "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"
    }
}

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í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": "Y73MNPGJ18Y18V5KQODX",
        "person_type": 1,
        "ein": null,
        "company_name": null,
        "taxpayer_id": "12345678909",
        "personal_name": "João da Silva Machado",
        "telephone": "11999999999",
        "cellular": "11888888888",
        "email": "joaosilva@cobrefacil.com.br",
        "email_cc": "maria@cobrefacil.com.br",
        "address": {
            "id": "E1V3649DR48XJQ87OMNL",
            "description": "AP 42",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "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"
        },
        "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"
    }
}

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": "11999999999",
            "cellular": "11888888888",
            "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": "123",
                "complement": "Ap 42",
                "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"
            },
            "created_at": "2020-06-25T09:52:48-03:00",
            "updated_at": "2020-06-25T09:55:50-03: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=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": "11999999999",
        "cellular": "11999999999",
        "email": "joao@cobrefacil.com.br",
        "email_cc": "maria@cobrefacil.com.br",
        "address": {
            "id": "E1V3649DR48XJQ87OMNL",
            "description": "AP",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "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"
        },
        "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"
    }
}

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 em 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"
}
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

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"
    }
}

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"
    }
}

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"
    }
}

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"
        }
    ]
}

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 especifico:
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"
    }
}

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.

Cobranças

Através da nossa API é possível criar cobranças via 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 boleto

Ao criar uma cobrança via boleto ela iniciará com o status processing e será atualizado para pending quando o boleto for gerado e registrado. Caso o boleto seja pago o status será alterado para paid e caso seja executada a ação de cancelar o status será alterado 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. Caso seja um estorno parcial o status será atualizado para refunded e caso o estorno seja igual ao valor total da cobrança o novo status será canceled.

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.

O objeto cobrança

Exemplo de JSON do objeto cobrança:

{
    "id": "ZN8V0PD9W005WLRGQE5K",
    "payable_with": "bankslip",
    "due_date": "2020-12-15",
    "price": "89.98",
    "fine_delay": null,
    "total_paid": null,
    "amount_released": null,
    "paid_at": null,
    "payment_method": null,
    "document_number": "4604618",
    "barcode": "34191090406046183893431339210002484700000008998",
    "barcode_data": null,
    "status": "pending",
    "settings": {
        "late_fee": null,
        "interest": null,
        "discount": null,
        "warning": null
    },
    "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": "11999999999",
        "cellular": "11999999999",
        "email": "joao@cobrefacil.com.br",
        "email_cc": "maria@cobrefacil.com.br",
        "address": {
            "id": "E1V3649DR48XJQ87OMNL",
            "description": "AP",
            "zipcode": "01311000",
            "street": "Avenida Paulista",
            "number": "123",
            "complement": "Ap 42",
            "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"
        },
        "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"
    },
    "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"
}

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
status String Situação atual da cobrança, pode ser:
processing o sistema está processando a cobrança
pending a cobrança aguarda pagamento
reversed a cobrança foi cancelada por falha de comunicação com a adquirente aprovadora da transação
pre_authorized a cobrança foi pré autorizada (apenas cartão)
paid a cobrança foi paga
declined 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 cancelada
dispute contestação da transação em análise
charged_back contestação aprovada e dinheiro devolvido
payable_with String Forma de cobrança, pode ser:
bankslip boleto
credit cartão de crédito
all gera um boleto e permite que o cliente pague também com cartão de crédito
payment_method String Forma de pagamento, este campo é preenchido apenas quando a cobrança é paga e pode ser:
bankslip boleto
credit cartão de crédito
price Float Valor da cobrança
total_paid Float Valor pago
amount_released Float Valor liberado depois de pago, descontando a taxa 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
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
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 via boleto
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
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 posteriormente
1 Capturar transação após a autorização
OBS: 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
created_at DateTime Data que a cobrança foi criada
updated_at DateTime Data que a cobrança foi atualizada

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 "{
    \"payable_with\": \"bankslip\",
    \"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.\"
        }
    }
}"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "2KD9LGERW897NZ6JM5V4",
        "payable_with": "bankslip",
        "due_date": "2020-12-15",
        "price": "89.98",
        "fine_delay": null,
        "total_paid": null,
        "amount_released": null,
        "paid_at": null,
        "payment_method": null,
        "document_number": 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": null,
            "interest": null,
            "discount": null,
            "warning": null
        },
        "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": "11999999999",
            "cellular": "11888888888",
            "email": "joaosilva@cobrefacil.com.br",
            "email_cc": "maria@cobrefacil.com.br",
            "address": {
                "id": "E1V3649DR48XJQ87OMNL",
                "description": "AP 42",
                "zipcode": "01311000",
                "street": "Avenida Paulista",
                "number": "123",
                "complement": "Ap 42",
                "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"
            },
            "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"
        },
        "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:

Desconto, juros e multa:

HTTP Request

POST https://api.cobrefacil.com.br/v1/invoices

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
payable_with String Sim Informe bankslip
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 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 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,
    \"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
        }
    ]
}"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "OY4Q3NVG7VD759PRLD60",
        "payable_with": "credit",
        "due_date": "2020-06-25",
        "price": "89.98",
        "fine_delay": null,
        "total_paid": null,
        "amount_released": null,
        "paid_at": null,
        "payment_method": null,
        "document_number": null,
        "barcode": null,
        "barcode_data": null,
        "status": "processing",
        "capture": 0,
        "request_ip": "168.190.36.98",
        "installment": {
            "mode": "with_interest",
            "number": 3
        },
        "amount_refunded": 0,
        "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"
        },
        "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": "1199999999999",
            "cellular": "17997324082",
            "email": "joao@cobrefacil.com.br",
            "email_cc": null,
            "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-06-25T10:26:02-03:00",
                "updated_at": "2020-06-25T10:26:02-03:00"
            },
            "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"
        },
        "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.

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
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.customer_id String Quando credit_card for informado Identificador do cliente
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 posteriormente
1 Capturar transação
request_ip String Não Ip 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 emissor
interest_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

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",
        "payable_with": "credit",
        "due_date": "2020-06-25",
        "price": "89.98",
        "fine_delay": null,
        "total_paid": "89.98",
        "amount_released": null,
        "paid_at": "2020-06-25",
        "payment_method": "credit",
        "document_number": null,
        "barcode": null,
        "barcode_data": null,
        "status": "paid",
        "capture": 0,
        "request_ip": "168.190.36.98",
        "installment": {
            "mode": "with_interest",
            "number": 3
        },
        "amount_refunded": 0,
        "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"
        },
        "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": "1199999999999",
            "cellular": "17997324082",
            "email": "joao@cobrefacil.com.br",
            "email_cc": null,
            "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-06-25T10:26:02-03:00",
                "updated_at": "2020-06-25T10:26:02-03:00"
            },
            "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"
        },
        "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 4290
quando 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
        }
    ]
}"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "OY4Q3NVG7VD759PRLD60",
        "payable_with": "credit",
        "due_date": "2020-06-25",
        "price": "89.98",
        "total_paid": null,
        "amount_released": null,
        "paid_at": null,
        "payment_method": null,
        "status": "pending",
        "capture": 0,
        "request_ip": "168.190.36.98",
        "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": "1199999999999",
            "cellular": "17997324082",
            "email": "joao@cobrefacil.com.br",
            "email_cc": null,
            "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-06-25T10:26:02-03:00",
                "updated_at": "2020-06-25T10:26:02-03:00"
            },
            "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"
        },
        "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

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",
        "payable_with": "bankslip",
        "due_date": "2020-12-15",
        "price": "89.98",
        "fine_delay": null,
        "total_paid": null,
        "amount_released": null,
        "paid_at": null,
        "payment_method": null,
        "document_number": null,
        "barcode": null,
        "barcode_data": null,
        "status": "processing",
        "settings": {
            "late_fee": null,
            "interest": null,
            "discount": null,
            "warning": null
        },
        "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": "11999999999",
            "cellular": "11999999999",
            "email": "joao@cobrefacil.com.br",
            "email_cc": "maria@cobrefacil.com.br",
            "address": {
                "id": "E1V3649DR48XJQ87OMNL",
                "description": "AP",
                "zipcode": "01311000",
                "street": "Avenida Paulista",
                "number": "123",
                "complement": "Ap 42",
                "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"
            },
            "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"
        },
        "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",
            "payable_with": "bankslip",
            "due_date": "2020-12-15",
            "price": "89.98",
            "fine_delay": null,
            "total_paid": null,
            "amount_released": null,
            "paid_at": null,
            "payment_method": null,
            "document_number": "4604618",
            "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": "11999999999",
                "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"
            },
            "settings": {
                "late_fee": null,
                "interest": null,
                "discount": null,
                "warning": 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: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?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 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 ,
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
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",
        "payable_with": "credit",
        "due_date": "2020-06-25",
        "price": "89.98",
        "fine_delay": null,
        "total_paid": "89.98",
        "amount_released": null,
        "paid_at": "2020-06-25",
        "payment_method": "credit",
        "document_number": null,
        "barcode": null,
        "barcode_data": null,
        "status": "refunded",
        "capture": 0,
        "request_ip": "168.190.36.98",
        "installment": {
            "mode": "with_interest",
            "number": 3
        },
        "amount_refunded": 10,
        "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",
            "expiration_year": "2021",
            "expiration_month": "12"
        },
        "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": "1199999999999",
            "cellular": "17997324082",
            "email": "joao@cobrefacil.com.br",
            "email_cc": null,
            "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-06-25T10:26:02-03:00",
                "updated_at": "2020-06-25T10:26:02-03:00"
            },
            "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"
        },
        "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. Quanto é estornado apenas parte do valor, o status da cobrança será alterado para refunded e caso seja estornado o valor total o novo status será canceled.

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 4290
quando 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",
        "payable_with": "credit",
        "due_date": "2020-06-25",
        "price": "89.98",
        "fine_delay": null,
        "total_paid": "89.98",
        "amount_released": null,
        "paid_at": "2020-06-25",
        "payment_method": "credit",
        "document_number": null,
        "barcode": null,
        "barcode_data": null,
        "status": "canceled",
        "capture": 0,
        "request_ip": "168.190.36.98",
        "installment": {
            "mode": "with_interest",
            "number": 3
        },
        "amount_refunded": 10,
        "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"
        },
        "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": "1199999999999",
            "cellular": "17997324082",
            "email": "joao@cobrefacil.com.br",
            "email_cc": null,
            "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-06-25T10:26:02-03:00",
                "updated_at": "2020-06-25T10:26:02-03:00"
            },
            "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"
        },
        "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, pre_authorized, paid ou refunded.

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

Retorno

Em caso de sucesso será retornado um objeto cobrança com os dados atualizados.