NAV
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 utilizá-lo da melhor maneira possível no seu negócio.
Para utilizar nossa API é necessário ter uma conta na Cobre Fácil, caso ainda não tenha clique aqui.

Nesta documentação mostraremos os dados necessários para realizar uma requisição, os valores retornados e exemplos de códigos.
Caso tenha alguma dúvida ou precise de suporte acesse nossa página de ajuda.

Requisições e respostas

Exemplo básico do JSON retornado:

{
    "success": true,
    "data": {
      ...
    } 
}

Nossa API utiliza o padrão REST, todas as requisições e respostas são no formato JSON e os endpoints utilizam como base o endereço:
https://api.cobrefacil.com.br/v1/

Para indicar o sucesso ou falha nas requisições utilizamos códigos HTTP, no caso de requisições bem sucedidas o código é o 201 quando um registro é criado ou 200 para indicar outras operações de sucesso, outros códigos representam algum tipo de erro. Além disso, o JSON retornado contém um campo booleano chamado success que pode ser utilizado no lugar dos códigos para verificar o sucesso da operação.

A segurança no envio e recebimento dos dados é realizada através de autenticação via token.

Observações sobre tipos de campos para data

Tipo Observação
Date utilizam o formato YYYY-MM-DD, exemplo 2020-01-30
DateTime geralmente retornados em created_at, updated_at e deleted_at utilizam o formato ISO 8601, exemplo 2020-01-30T12:34:56+00:00

Erros

Exemplo de retorno contendo o motivo do erro e dados adicionais:

{
    "success": false,
    "message": "Parâmetros inválidos.",
    "errors": [
        "Data de vencimento deve ser uma data maior ou igual a hoje.",
        "O juros não pode ser maior que 3,3% ao dia."
    ]
}

Quando um erro é identificado o retorno da requisição conterá o código HTTP apropriado, que pode ser:

Código Descrição
400 Bad Request Algum parâmetro obrigatório não foi enviado ou é inválido
401 Unauthorized O token não foi enviado ou é inválido
404 Not Found O endpoint ou o registro solicitado não existe
500 Internal Server Error Algum problema no servidor da Cobre Fácil

Além disso, o JSON retornado terá o campo success com o valor false e o campo message descreverá o motivo do erro, em alguns casos também será retornado um array no campo errors contendo detalhes adicionais.

Autenticação

Para autenticar, utilize esse exemplo de código:

curl --location --request POST "https://api.cobrefacil.com.br/v1/authenticate" \
--header "Content-Type: application/json" \
--data "{
    \"app_id\": \"meuapp_5dcae973d82c2\",
    \"secret\": \"eba5893f056d7f0633838c1c475b89391ef72534\"
}"

Exemplo do JSON que será retornado:

{
    "success": true,
    "data": {
        "token": "8c1301b8c246942b195dd4467846e10eb8ac9a18",
        "expiration": 3600
    }
}

A autenticação é feita através do envio de um token no header das requisições, exemplo:

Authorization: Bearer 8c1301b8c246942b195dd4467846e10eb8ac9a18

Para obter o token é necessário fazer uma requisição para o endpoint /authenticate enviando o seu app_id e secret, esses dados estão disponíveis no painel de sua conta na pagina /integrations.
Para ambiente de sandbox é necessario entrar em contato para solicitar as credenciais.

HTTP Request

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

BODY Params

Parâmetro Tipo Obrigatório Descrição
app_id String Sim Identificador da aplicação
secret String Sim Chave secreta da aplicação

Retorno

Atributo Tipo Descrição
token String Token que deve ser utilizado nas requisições
expiration Integer Validade do token em segundos, após esse período será necessário obter um novo token

Webhooks

JSON base de um evento enviado:

{
    "event": "invoice.created",
    "data": {
      ...
    }
}

JSON de um evento referente a cobrança:

{
    "event": "invoice.created",
    "data": {
        "id": "PQ9RDZ2376N7YMGJ8V1K",
        "payable_with": "bankslip",
        "due_date": "2020-12-15",
        "price": 49.9,
        "fine_delay": null,
        "total_paid": null,
        "amount_released": null,
        "fee": null,
        "paid_at": null,
        "payment_method": null,
        "document_number": null,
        "barcode": "34191090570137951893731339210002284700000004990",
        "barcode_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZUAAAAyCAYAAACUNUbZAAACHUlEQVR42u3V2wqAIAwA0P3/Txc9%0ABD6kuGkQcYIIb63W7EREHNfRXu+z126PUf9b657Gs/OycXrPPZo3u/5L93nqH9VDJS+7xnfX2Y78%0AVOq0uu9m5vfijdrV/Zep02q8mbytfJdM/Oy+XHmfal1V/4cr+Q+oQAUqUIEKVKACFahABSpQgQpU%0AoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKAC%0AFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWo%0AQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAF%0AKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQ%0AgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEK%0AVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSg%0AAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIV%0AqEAFKv9G5QSDfSad5j+EigAAAABJRU5ErkJggg==%0A",
        "status": "pending",
        "settings": null,
        "items": [],
        "customer": {
            "id": "Z8J53ROD2JK1PQ47WG0E",
            "person_type": 2,
            "ein": null,
            "company_name": "COBRE FACIL LTDA ME",
            "taxpayer_id": "12345678909",
            "personal_name": null,
            "telephone": "11988887777",
            "cellular": "11988887777",
            "email": "exemplo@cobrefacil.com.br",
            "email_cc": null,
            "full_name": "COBRE FACIL LTDA ME",
            "document": "12345678909",
            "address": {
                "id": "9W2LVGOPRJMR780DEJK1",
                "description": "Endereço principal",
                "zipcode": "01311000",
                "street": "Avenida Paulista",
                "number": "807",
                "complement": "A813 CJ 2315",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "state": "SP",
                "created_at": "2020-04-03T11:31:52+00:00",
                "updated_at": "2020-04-03T11:31:52+00:00",
                "deleted_at": null
            },
            "created_at": "2020-04-03T11:31:52+00:00",
            "updated_at": "2020-04-03T11:31:52+00:00",
            "deleted_at": null
        },
        "created_at": "2020-04-03T13:54:59+00:00",
        "updated_at": "2020-04-03T13:54:59+00:00"
    }
}

O serviço de webhooks permite receber atualizações sobre eventos importantes em tempo real. Através deles é possível montar uma integração assíncrona com a Cobre Fácil, aumentando a escalabilidade da sua plataforma.

Para utilizar a notificação por webhooks é necessário cadastrar no painel da sua conta as URLs responsáveis por realizar o tratamento dos eventos que serão enviados.

Fluxo de retentativas de disparos

Uma vez que a primeira tentativa de entrega não obtém sucesso, será efetuado um novo disparo após 10 minutos. Após um número máximo de 6 tentativas sem sucesso o evento entrará em estado de falha na entrega.

Estrutura base do JSON enviado

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

Eventos disponíveis

Evento Descrição
invoice.created Cobrança criada
invoice.viewed Cobrança visualizada
invoice.reversed Cobrança cancelada por falha de comunicação com a adquirente aprovadora da transação
invoice.declined Pagamento recusado
invoice.pre_authorized Pagamento pré autorizado
invoice.paid Cobrança paga
invoice.refunded Cobrança estornada parcialmente
invoice.canceled Cobrança estornada por completo ou cancelada
invoice.dispute Disputa aberta para uma transação
invoice.dispute_succeeded Vitória da disputa por parte do estabelecimento comercial
invoice.charged_back Vitória da disputa por parte do portador do cartão
------ ---------
subscription.canceled Mensalidade cancelada
subscription.created Mensalidade criada
subscription.paused Mensalidade pausada
subscription.reactivated Mensalidade reativada
subscription.terminated Mensalidade terminada
------ ---------
tax_invoice.created Nota fiscal criada
tax_invoice.rejected Nota fiscal rejeitada
tax_invoice.denied Nota fiscal negada
tax_invoice.actived Nota fiscal ativa
tax_invoice.canceled Nota fiscal cancelada
tax_invoice.cancellation_rejected Nota fiscal solicitação de cancelamento recusada

Clientes

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

O objeto cliente

Exemplo de JSON do objeto cliente:

{
  "id": "Y73MNPGJ18Y18V5KQODX",
  "person_type": 1,
  "ein": null,
  "company_name": null,
  "taxpayer_id": "12345678909",
  "personal_name": "João da Silva",
  "telephone": "11988887777",
  "cellular": "11988887777",
  "email": "joao@cobrefacil.com.br",
  "email_cc": "maria@cobrefacil.com.br",
  "full_name": "João da Silva",
  "document": "12345678909",
  "address": {
    "id": "E1V3649DR48XJQ87OMNL",
    "description": "Endereço principal",
    "zipcode": "01311000",
    "street": "Avenida Paulista",
    "number": "807",
    "complement": "A813 CJ 2315",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "created_at": "2020-06-25T09:52:48-03:00",
    "updated_at": "2020-06-25T09:52:48-03:00",
    "deleted_at": null
  },
  "nfse": {
    "inscricao_estadual": "123456789",
    "iss_retido": true
  },
  "created_at": "2020-06-25T09:52:48-03:00",
  "updated_at": "2020-06-25T09:52:48-03:00",
  "deleted_at": null
}
Atributo Tipo Descrição
id String Identificador do cliente
person_type Integer 1 Pessoa fí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
address.deleted_at DateTime Data que o endereço foi excluído
nfse Object Dados para geração de NFSe
nfse.inscricao_estadual String Inscrição estadual do tomador
nfse.responsavel_retencao Integer Responsável pela retenção, valores:
1 Tomador
2 Intermediário
nfse.iss Object Detalhamento do ISS
nfse.iss.tipo_tributacao Integer Tipo de Tributação do Serviço, valores:
1 Isento de ISS
2 Imune
3 Não Incidência no Município
4 Não Tributável
5 Retido
6 Tributável Dentro do Município
7 Tributável Fora do Município
8 Tributável Dentro do Município pelo tomador
nfse.iss.exigibilidade Integer Exigibilidade do ISS, valores:
1 Exigível
2 Não Incidência
3 Isenção
4 Exportação
5 Imunidade
6 Suspenso por Ação Judicial
7 Suspenso por Ação Administrativa
nfse.iss.retido Boolean Reter ISS
nfse.iss.processo_suspensao String Número do Processo de Suspensão da Exigibilidade
created_at DateTime Data que o cliente foi criado
updated_at DateTime Data que o cliente foi atualizado
deleted_at DateTime Data que o cliente foi excluído

Criar cliente

curl --location --request POST "https://api.cobrefacil.com.br/v1/customers" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"person_type\": 1,
    \"taxpayer_id\": \"12345678909\",
    \"personal_name\": \"João da Silva\",
    \"telephone\": \"11999999999\",
    \"cellular\": \"11888888888\",
    \"email\": \"joao@cobrefacil.com.br\",
    \"email_cc\": \"maria@cobrefacil.com.br\",
    \"address\": {
        \"description\": \"AP\",
        \"zipcode\": \"01311000\",
        \"street\": \"Avenida Paulista\",
        \"number\": \"123\",
        \"complement\": \"Ap 42\",
        \"neighborhood\": \"Bela Vista\",
        \"city\": \"São Paulo\",
        \"state\": \"SP\"
    }
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "Y73MNPGJ18Y18V5KQODX",
    "person_type": 1,
    "ein": null,
    "company_name": null,
    "taxpayer_id": "12345678909",
    "personal_name": "João da Silva",
    "telephone": "11988887777",
    "cellular": "11988887777",
    "email": "joao@cobrefacil.com.br",
    "email_cc": "maria@cobrefacil.com.br",
    "address": {
      "id": "E1V3649DR48XJQ87OMNL",
      "description": "Endereço principal",
      "zipcode": "01311000",
      "street": "Avenida Paulista",
      "number": "807",
      "complement": "A813 CJ 2315",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "created_at": "2020-06-25T09:52:48-03:00",
      "updated_at": "2020-06-25T09:52:48-03:00",
      "deleted_at": null
    },
    "full_name": "João da Silva",
    "document": "12345678909",
    "created_at": "2020-06-25T09:52:48-03:00",
    "updated_at": "2020-06-25T09:52:48-03:00",
    "deleted_at": null
  }
}

HTTP Request

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

Body Params

Parâmetro Tipo Obrigatório Descrição
person_type Integer Sim 1 Pessoa fí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
nfse Object Não Endereço do cliente
nfse.inscricao_estadual String Não Inscrição estadual do tomador
nfse.responsavel_retencao Integer Não Responsável pela retenção, valores:
1 Tomador
2 Intermediário
nfse.iss Object Não Detalhamento do ISS
nfse.iss.tipo_tributacao Integer Não Tipo de Tributação do Serviço, valores:
1 Isento de ISS
2 Imune
3 Não Incidência no Município
4 Não Tributável
5 Retido
6 Tributável Dentro do Município
7 Tributável Fora do Município
8 Tributável Dentro do Município pelo tomador
nfse.iss.exigibilidade Integer Não Exigibilidade do ISS, valores:
1 Exigível
2 Não Incidência
3 Isenção
4 Exportação
5 Imunidade
6 Suspenso por Ação Judicial
7 Suspenso por Ação Administrativa
nfse.iss.retido Boolean Não Reter ISS
nfse.iss.processo_suspensao String Não Número do Processo de Suspensão da Exigibilidade

Retorno

Em caso de sucesso será retornado um objeto cliente.

Atualizar cliente

curl --location --request PUT "https://api.cobrefacil.com.br/v1/customers" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"personal_name\": \"João da Silva Machado\",
    \"email\": \"joaosilva@cobrefacil.com.br\",
    \"address\": {
        \"description\": \"AP 42\"
    }
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "Y73MNPGJ18Y18V5KQODX",
    "person_type": 1,
    "ein": null,
    "company_name": null,
    "taxpayer_id": "12345678909",
    "personal_name": "João da Silva Machado",
    "telephone": "11988887777",
    "cellular": "11988887777",
    "email": "joaosilva@cobrefacil.com.br",
    "email_cc": "maria@cobrefacil.com.br",
    "address": {
      "id": "E1V3649DR48XJQ87OMNL",
      "description": "AP 42",
      "zipcode": "01311000",
      "street": "Avenida Paulista",
      "number": "807",
      "complement": "A813 CJ 2315",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "created_at": "2020-06-25T09:52:48-03:00",
      "updated_at": "2020-06-25T09:55:50-03:00",
      "deleted_at": null
    },
    "full_name": "João da Silva Machado",
    "document": "12345678909",
    "created_at": "2020-06-25T09:52:48-03:00",
    "updated_at": "2020-06-25T09:55:50-03:00",
    "deleted_at": null
  }
}

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

HTTP Request

PUT https://api.cobrefacil.com.br/v1/customers/[ID]

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador do cliente

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
person_type Integer Não 1 Pessoa fí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
nfse Object Não Endereço do cliente
nfse.inscricao_estadual String Não Inscrição estadual do tomador
nfse.responsavel_retencao Integer Não Responsável pela retenção, valores:
1 Tomador
2 Intermediário
nfse.iss Object Não Detalhamento do ISS
nfse.iss.tipo_tributacao Integer Não Tipo de Tributação do Serviço, valores:
1 Isento de ISS
2 Imune
3 Não Incidência no Município
4 Não Tributável
5 Retido
6 Tributável Dentro do Município
7 Tributável Fora do Município
8 Tributável Dentro do Município pelo tomador
nfse.iss.exigibilidade Integer Não Exigibilidade do ISS, valores:
1 Exigível
2 Não Incidência
3 Isenção
4 Exportação
5 Imunidade
6 Suspenso por Ação Judicial
7 Suspenso por Ação Administrativa
nfse.iss.retido Boolean Não Reter ISS
nfse.iss.processo_suspensao String Não Número do Processo de Suspensão da Exigibilidade

Retorno

Em caso de sucesso será retornado um objeto cliente com os dados atualizados.

Detalhar cliente

curl --location --request GET "https://api.cobrefacil.com.br/v1/customers/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "Y73MNPGJ18Y18V5KQODX",
    "person_type": 1,
    "ein": null,
    "company_name": null,
    "taxpayer_id": "12345678909",
    "personal_name": "João da Silva Machado",
    "telephone": "11988887777",
    "cellular": "11988887777",
    "email": "joaosilva@cobrefacil.com.br",
    "email_cc": "maria@cobrefacil.com.br",
    "address": {
      "id": "E1V3649DR48XJQ87OMNL",
      "description": "AP 42",
      "zipcode": "01311000",
      "street": "Avenida Paulista",
      "number": "807",
      "complement": "A813 CJ 2315",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "created_at": "2020-06-25T09:52:48-03:00",
      "updated_at": "2020-06-25T09:55:50-03:00",
      "deleted_at": null
    },
    "full_name": "João da Silva Machado",
    "document": "12345678909",
    "created_at": "2020-06-25T09:52:48-03:00",
    "updated_at": "2020-06-25T09:55:50-03:00",
    "deleted_at": null
  }
}

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

HTTP Request

GET https://api.cobrefacil.com.br/v1/customers/[ID]

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador do cliente

Retorno

Em caso de sucesso será retornado um objeto cliente.

Listar clientes

curl --location --request GET "https://api.cobrefacil.com.br/v1/customers" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
  "success": true,
  "data": [
    {
      "id": "Y73MNPGJ18Y18V5KQODX",
      "person_type": 1,
      "ein": null,
      "company_name": null,
      "taxpayer_id": "12345678909",
      "personal_name": "João da Silva Machado",
      "telephone": "11988887777",
      "cellular": "11988887777",
      "email": "joaosilva@cobrefacil.com.br",
      "email_cc": "maria@cobrefacil.com.br",
      "full_name": "João da Silva Machado",
      "document": "12345678909",
      "address": {
        "id": "E1V3649DR48XJQ87OMNL",
        "description": "AP 42",
        "zipcode": "01311000",
        "street": "Avenida Paulista",
        "number": "807",
        "complement": "A813 CJ 2315",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "created_at": "2020-06-25T09:52:48-03:00",
        "updated_at": "2020-06-25T09:55:50-03:00",
        "deleted_at": null
      },
      "created_at": "2020-06-25T09:52:48-03:00",
      "updated_at": "2020-06-25T09:55:50-03:00",
      "deleted_at": null
    }
  ]
}

Retorna uma lista paginada de clientes e seus respectivos endereços.
É possível controlar a paginação e realizar buscas através de parâmetros na URL, exemplos:

Buscar cliente pelo e-mail:
GET https://api.cobrefacil.com.br/v1/customers?email=joao@cobrefacil.com.br

Retornar 10 registros pulando os 10 primeiros:
GET https://api.cobrefacil.com.br/v1/customers?limit=10&offset=10

HTTP Request

GET https://api.cobrefacil.com.br/v1/customers

URL Parameters

Parâmetro Tipo Descrição
taxpayer_id String Busca pelo CPF do cliente
ein String Busca pelo CNPJ da empresa
email String Busca pelo e-mail do cliente
personal_name String Busca pelo nome do cliente
company_name String Busca pelo nome da empresa
sort_by String Campo a ser utilizado na ordenação, o padrão é created_at
order_by String Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc
limit Integer Quantidade máxima de registros que devem ser retornados, o padrão é 100
offset Integer Número de registros a serem pulados, o padrão é 0

Retorno

Em caso de sucesso será retornado um array de objetos cliente.

Remover cliente

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/customers/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "Y73MNPGJ18Y18V5KQODX",
    "person_type": 1,
    "ein": null,
    "company_name": null,
    "taxpayer_id": "37673788250",
    "personal_name": "João da Silva",
    "telephone": "11988887777",
    "cellular": "11999999999",
    "email": "joao@cobrefacil.com.br",
    "email_cc": "maria@cobrefacil.com.br",
    "address": {
      "id": "E1V3649DR48XJQ87OMNL",
      "description": "Endereço principal",
      "zipcode": "01311000",
      "street": "Avenida Paulista",
      "number": "807",
      "complement": "A813 CJ 2315",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "created_at": "2020-06-25T14:01:40-03:00",
      "updated_at": "2020-06-25T16:41:03-03:00",
      "deleted_at": "2020-06-25T16:41:03-03:00"
    },
    "full_name": "João da Silva",
    "document": "37673788250",
    "created_at": "2020-06-25T14:01:40-03:00",
    "updated_at": "2020-06-25T16:41:03-03:00",
    "deleted_at": "2020-06-25T16:41:03-03:00"
  }
}

Ao remover um cliente as cobranças pertencentes a ele continuarão disponíveis para consulta, mas não será possível criar novas cobranças para ele.

HTTP Request

DELETE https://api.cobrefacil.com.br/v1/customers/[ID]

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador do cliente

Retorno

Em caso de sucesso será retornado um objeto cliente com os dados atualizados.

Cartão de crédito

Oferecemos a possibilidade de armazenar um ou vários cartões de um cliente para que seja realizada a cobrança posteriormente.

Além disso, utilizamos tokenização para proteger os dados dos cartões, cumprindo os padrões de segurança da indústria.

Cartões para teste

Para testar sua integração sem ter que utilizar cartões de crédito verdadeiros em ambiente de produção, você pode utilizar o nosso ambiente de testes e os números que fornecemos para simular determinadas situações.

Número Resultado esperado
4539003370725497 Transação autorizada - Bandeira Visa
5356066320271893 Transação autorizada - Bandeira Mastercard
6011457819940087 Transação negada

Não utilize esses números de cartões no ambiente de produção.

O objeto cartão

Exemplo de JSON do objeto cartão:

{
    "id": "E65OPXNV9D59WM7JL402",
    "customer_id": "Z8J53ROD2JK1PQ47WG0E",
    "default": 1,
    "brand": "visa",
    "first6_digits": "453900",
    "last4_digits": "5497",
    "expiration_year": "2020",
    "expiration_month": "12",
    "created_at": "2020-06-25T10:06:10-03:00",
    "updated_at": "2020-06-25T10:06:17-03:00",
    "deleted_at": null
}
Atributo Tipo Descrição
id String Identificador do cartão
customer_id String Identificador do cliente
default Integer Informa se é o cartão padrão da conta, 1 sim e 0 não
brand String Bandeira do cartão, visa e mastercard
first6_digits String Primeiros 6 dígitos do número do cartão
last4_digits String Últimos 4 dígitos do número do cartão
expiration_month String Mês de expiração do cartão
expiration_year String Ano de expiração do cartão
created_at String Data que o cartão foi cadastrado
updated_at String Data que o cartão foi atualizado
deleted_at String Data que o cartão foi excluído

Criar cartão

curl --location --request POST "https://api.cobrefacil.com.br/v1/cards" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"customer_id\": \"Z8J53ROD2JK1PQ47WG0E\",
    \"default\": 1,
    \"name\": \"João da Silva\",
    \"number\": \"4539003370725497\",
    \"expiration_month\": \"12\",
    \"expiration_year\": \"2020\",
    \"security_code\": \"123\"
}"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "E65OPXNV9D59WM7JL402",
        "customer_id": "Z8J53ROD2JK1PQ47WG0E",
        "default": 1,
        "brand": "visa",
        "first6_digits": "453900",
        "last4_digits": "5497",
        "expiration_year": "2020",
        "expiration_month": "12",
        "created_at": "2020-06-25T10:06:10-03:00",
        "updated_at": "2020-06-25T10:06:17-03:00",
        "deleted_at": null
    }
}

Ao criar um novo cartão de crédito deve ser informado o cliente que poderá utilizar o cartão para pagamentos.
Se o cliente informado não possuir um cartão padrão, o novo cartão cadastrado se tornará o padrão dele.

Caso deseje alterar o cartão padrão de um cliente, utilize a opção definir cartão padrão.

HTTP Request

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

Body Params

Parâmetro Tipo Obrigatório Descrição
customer_id String Sim Identificação do cliente
default Integer Não Define se é o cartão padrão da conta, 1 sim e 0 não
name String Sim Nome do portador do cartão
number String Sim Número do cartão
expiration_month String Sim Mês de expiração do cartão, deve conter 2 dígitos
expiration_year String Sim Ano de expiração do cartão, deve conter 4 dígitos
security_code String Sim Código de segurança do cartão

Retorno

Em caso de sucesso será retornado um objeto cartão.

Definir cartão padrão

O único dado de um cartão que pode ser alterado após o seu cadastro, é o campo default, para isso oferecemos esse endpoint que sempre que for chamado altera o cartão padrão de um usuário para o que foi informado na requisição.

curl --location --request POST "https://api.cobrefacil.com.br/v1/cards/[ID]/default" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "E65OPXNV9D59WM7JL402",
        "customer_id": "Z8J53ROD2JK1PQ47WG0E",
        "default": 0,
        "brand": "visa",
        "first6_digits": "453900",
        "last4_digits": "5497",
        "expiration_year": "2020",
        "expiration_month": "12",
        "created_at": "2020-06-25T10:06:10-03:00",
        "updated_at": "2020-06-25T10:09:01-03:00",
        "deleted_at": null
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/cards/[ID]/default

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador do cartão

Retorno

Em caso de sucesso será retornado um objeto cartão.

Detalhar cartão

curl --location --request GET "https://api.cobrefacil.com.br/v1/cards/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "E65OPXNV9D59WM7JL402",
        "customer_id": "Z8J53ROD2JK1PQ47WG0E",
        "default": 0,
        "brand": "visa",
        "first6_digits": "453900",
        "last4_digits": "5497",
        "expiration_year": "2020",
        "expiration_month": "12",
        "created_at": "2020-06-25T10:06:10-03:00",
        "updated_at": "2020-06-25T10:09:01-03:00",
        "deleted_at": null
    }
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/cards/[ID]

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador do cartão

Retorno

Em caso de sucesso será retornado um objeto cartão.

Listar cartões

curl --location --request GET "https://api.cobrefacil.com.br/v1/cards" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": [
        {
            "id": "E65OPXNV9D59WM7JL402",
            "customer_id": "Z8J53ROD2JK1PQ47WG0E",
            "default": 0,
            "brand": "visa",
            "first6_digits": "453900",
            "last4_digits": "5497",
            "expiration_year": "2020",
            "expiration_month": "12",
            "created_at": "2020-06-25T10:06:10-03:00",
            "updated_at": "2020-06-25T10:09:01-03:00",
            "deleted_at": null
        }
    ]
}

Retorna uma lista paginada de cartões.
É possível controlar a paginação e realizar buscas através de parâmetros na URL, exemplos:

Buscar cartões por cliente:
GET https://api.cobrefacil.com.br/v1/cards?customer_id=Z8J53ROD2JK1PQ47WG0E

Retornar 10 cartões que irão expirar em um período específico:
GET https://api.cobrefacil.com.br/v1/cards?expiration_start=2021-09&expiration_end=2021-10&limit=10

HTTP Request

GET https://api.cobrefacil.com.br/v1/cards

URL Parameters

Parâmetro Tipo Descrição
customer_id String Busca pelo identificador do cliente
brand String Busca pela bandeira do cartão
expiration String Busca pela data de expiração, deve estar no formato YYYY-MM,
quando esse parâmetro é informado expiration_start e expiration_end não devem ser enviados ou serão ignorados
expiration_start String Busca por cartões com data de expiração maior ou igual a informada, deve estar no formato YYYY-MM
expiration_end String Busca por cartões com data de expiração menor ou igual a informada, deve estar no formato YYYY-MM
sort_by String Campo a ser utilizado na ordenação, o padrão é created_at
order_by String Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc
limit Integer Quantidade máxima de registros que devem ser retornados, o padrão é 100
offset Integer Número de registros a serem pulados, o padrão é 0

Retorno

Em caso de sucesso será retornado um array de objetos cartão.

Remover cartão

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/cards/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "E65OPXNV9D59WM7JL402",
        "customer_id": "Z8J53ROD2JK1PQ47WG0E",
        "default": 1,
        "first6_digits": "453900",
        "last4_digits": "5497",
        "brand": "visa",
        "expiration_year": "2021",
        "expiration_month": "12",
        "created_at": "2020-06-25T10:26:02-03:00",
        "updated_at": "2020-06-25T16:58:00-03:00",
        "deleted_at": "2020-06-25T16:58:00-03:00"
    }
}

Ao remover um cartão que é o padrão, caso o cliente possua mais cartões, o novo cartão default será o mais recente cadastrado.

HTTP Request

DELETE https://api.cobrefacil.com.br/v1/cards/[ID]

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador do cartão

Retorno

Em caso de sucesso será retornado um objeto cartão.

Produtos e Serviços

As mensalidades, planos e links de pagamento possuem itens de produtos e serviços, os endpoints são criar, atualizar e remover produtos e serviços.
Você também pode listar filtrando os atributos desejados, detalhar, ativar e desativar produtos e serviços.

O objeto produto serviço

Exemplo de JSON do objeto produto/serviço:

{
    "id": "76JXDLQYEORE0P45WXMO",
    "description": "Produto Especial",
    "fixed_price": 1,
    "price": 42.90,
    "status": "actived",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
}
Atributo Tipo Descrição
id String Identificador do produto/serviço
description String Nome e/ou descrição do produto/serviço
fixed_price Integer Valor é fixo:
1 Sim
0 Não
price Float preço do produto/serviço
status String pode ser:
actived quando ativo
inactived quando desativado
updated_at DateTime Data que o produto/serviço foi atualizado
deleted_at DateTime Data que o produto/serviço foi excluído

Criar produtos / serviços

Ao criar um produto/serviço além da descrição, preço e status, você precisa informar se o preço é fixo ou não em fixed_price, pois quando informado 1 as modificações de valores feitas neste serviço, irão alterar os preços das mensalidades, links de pagamento, planos e itens adicionais que utilizarem este serviço.

curl --location --request POST "https://api.cobrefacil.com.br/v1/product-services" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"description\": \"Produto Especial\",
    \"fixed_price\": 1,
    \"price\": 4290,
    \"status\": \"actived\"
}"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "QG04KL8MED3N7V1XDZYR",
        "description": "Produto Especial",
        "fixed_price": 1,
        "price": 42.90,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/product-services

Body Params

Atributo Tipo Obrigatório Descrição
description String Sim Nome e/ou descrição do produto/serviço
fixed_price Integer Não O valor 1 é para fixo e 0 para não fixo, o padrão é 0
price Integer Sim Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290
status String Não padrão é actived

Retorno

Em caso de sucesso será retornado um objeto produto/serviço.

Atualizar produtos / serviços

Ao atualizar um produto é somente necessário enviar os campos que vão ser alterados.

curl --location --request PUT "https://api.cobrefacil.com.br/v1/product-services/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"description\": \"Produto Especial\",
    \"fixed_price\": 1,
    \"price\": 4290,
    \"status\": \"actived\"
}"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "QG04KL8MED3N7V1XDZYR",
        "description": "Produto Especial",
        "fixed_price": 1,
        "price": 42.90,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

PUT https://api.cobrefacil.com.br/v1/product-services/[ID]

Body Params

Atributo Tipo Obrigatório Descrição
description String Sim Nome e/ou descrição do produto/serviço
fixed_price Integer Não O valor 1 é para fixo e 0 para não fixo, o padrão é 0
price Integer Sim Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290
status String Não padrão é actived

Retorno

Em caso de sucesso será retornado um objeto produto/serviço.

Remover produtos / serviços

A remoção de um produto é feita através do seu identificador, após a sua remoção todas as mensalidades, links de pagamento, planos e itens adicionais planos que utilizam este produto/serviço manterá o preço e descrição em em geração de cobranças, mas não será listado como produto/serviço na criação/edição dos serviços citados.

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/product-services/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
    "success": true,
     "data": {
        "id": "QG04KL8MED3N7V1XDZYR",
        "description": "Produto Especial",
        "fixed_price": 1,
        "price": 42.90,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00",
        "deleted_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

DELETE https://api.cobrefacil.com.br/v1/product-services/[ID]

Retorno

Em caso de sucesso será retornado um objeto produto/serviço com a data de exclusão deleted_at.

Detalhar produtos / serviços

O detalhamento de um produto é feito através do seu identificador.

curl --location --request GET "https://api.cobrefacil.com.br/v1/product-services/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "QG04KL8MED3N7V1XDZYR",
        "description": "Produto Especial",
        "fixed_price": 1,
        "price": 42.90,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/product-services/[ID]

Retorno

Em caso de sucesso será retornado um objeto produto/serviço.

Listar produtos / serviços

curl --location --request GET "https://api.cobrefacil.com.br/v1/product-services" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": [
        {
            "id": "QG04KL8MED3N7V1XDZYR",
            "description": "Produto Especial",
            "fixed_price": 1,
            "price": 42.90,
            "status": "actived",
            "created_at": "2022-01-01 00:00:00",
            "updated_at": "2022-01-01 00:00:00"
        }
    ],
    "pagination": {
        "total_records": 1,
        "display_records": 1
    }
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/product-services

URL Parameters

Parâmetro Tipo Descrição
status String Filtrar pelo status
sort_by String Campo a ser utilizado na ordenação, o padrão é created_at
order_by String Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc
limit Integer Quantidade máxima de registros que devem ser retornados, o padrão é 100
offset Integer Número de registros a serem pulados, o padrão é 0

Retorno

Em caso de sucesso será retornado um array de objetos produtos/serviços.

Ativar produtos / serviços

curl --location --request POST "https://api.cobrefacil.com.br/v1/product-services/[ID]/activate" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
    "success": true,
     "data": {
        "id": "QG04KL8MED3N7V1XDZYR",
        "description": "Produto Especial",
        "fixed_price": 1,
        "price": 42.90,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/product-services/[ID]/activate

Retorno

Em caso de sucesso será retornado um objeto produto/serviço.

Desativar produtos / serviços

Ao desativar um produto o mesmo não será mais listado em mensalidades, links de pagamento, planos e itens adicionais.

curl --location --request POST "https://api.cobrefacil.com.br/v1/product-services/[ID]/inactivate" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
    "success": true,
     "data": {
        "id": "QG04KL8MED3N7V1XDZYR",
        "description": "Produto Especial",
        "fixed_price": 1,
        "price": 42.90,
        "status": "inactived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/product-services/[ID]/inactivate

Retorno

Em caso de sucesso será retornado um objeto produto/serviço com status inactived.

Planos

Planos podem ser utilizados em mensalidades e link de pagamentos, esses são os endpoints para criar, atualizar e remover planos.
Você também pode listar filtrando os atributos desejados, detalhar, habilitar, pausar e cancelar planos.

O objeto plano

Exemplo de JSON do objeto plano:

{
    "success": true,
    "data": {
        "id": "ZCYFP6YXQYZ18NZ4L752",
        "description": "Descrição do Plano",
        "discount": 20,
        "goal": 1,
        "items": [
            {
                "id": "CQXXZQ1NV3K8PLE7KMRB",
                "quantity": 1,
                "price": 999.97,
                "products_services_id": "51MXVCYAQYR53J1YP5X8",
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
        ],
        "name": "Nome do Plano",
        "notify_reactivation_at": null,
        "price": 999.97,
        "price_with_discount": 799.98,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}
Atributo Tipo Descrição
id String Identificador do plano
description String Descrição do plano
discount Integer Percentual de desconto
goal Integer Meta de planos a ser vendidos
items Array Array de objetos do tipo objeto item do plano
name String Nome plano
notify_reactivation_at Date Data para notificações no sistema e via e-mail para reativar o plano
price Float preço do plano
price_with_discount Float preço com atribuição do desconto
status String pode ser:
actived quando ativo
paused quando pausado
canceled quando cancelado
created_at DateTime Data que o plano foi criado
updated_at DateTime Data que o plano foi atualizado

Criar planos

Ao criar um plano com status actived o mesmo já poderá ser atribuído a mensalidades e links de pagamento.

curl --location --request POST "https://api.cobrefacil.com.br/v1/plans" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"description\": \"Descrição do Plano\",
        \"discount\": 20,
        \"goal\": 10,
        \"items\": [
            {
                \"quantity\": 1,
                \"products_services_id\": \"51MXVCYAQYR53J1YP5X8\"
            }
        ],
        \"name\": \"Nome do Plano\",
        \"notify_reactivation_at\": null,
        \"status\": \"actived\" 
    }"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "ZCYFP6YXQYZ18NZ4L752",
        "description": "Description",
        "discount": 20,
        "goal": 1,
        "items": [
            {
                "id": "CQXXZQ1NV3K8PLE7KMRB",
                "products_services_id": "51MXVCYAQYR53J1YP5X8",
                "quantity": 1,
                "price": 999.97,
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
        ],
        "name": "Nome do Plano",
        "notify_reactivation_at": "2022-01-01",
        "price": 999.97,
        "price_with_discount": 799.98,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

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

Body Params

Atributo Tipo Obrigatório Descrição
description String Sim Descrição do plano
discount Integer Não Percentual de desconto
goal Integer Não Meta de planos a ser vendidos
items Array Sim Array de objetos do tipo objeto item do plano
name String Sim Nome plano
notify_reactivation_at Date Não Data para notificações no sistema e via e-mail para reativar o plano
status String Sim pode ser:
actived quando ativo
paused quando pausado
canceled quando cancelado (opcional, default: actived)

Retorno

Em caso de sucesso será retornado um objeto plano.

Atualizar planos

Para editar o plano é necessário somente passar os campos que devem ser alterados.

curl --location --request PUT "https://api.cobrefacil.com.br/v1/plans/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"description\": \"Descrição do Plano Atualizado\",
        \"discount\": 20,
        \"goal\": 10,
        \"items\": [
            {
                \"quantity\": 1,
                \"products_services_id\": \"51MXVCYAQYR53J1YP5X8\"
            }
        ],
        \"name\": \"Nome do Plano Atualizado\",
        \"notify_reactivation_at\": null,
        \"status\": \"actived\"
    }"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "ZCYFP6YXQYZ18NZ4L752",
        "description": "Description",
        "discount": 20,
        "goal": 1,
        "items": [
            {
                "id": "CQXXZQ1NV3K8PLE7KMRB",
                "products_services_id": "51MXVCYAQYR53J1YP5X8",
                "quantity": 1,
                "price": 999.97,
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
        ],
        "name": "Nome do Plano",
        "notify_reactivation_at": "2022-01-01",
        "price": 999.97,
        "price_with_discount": 799.98,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

PUT https://api.cobrefacil.com.br/v1/plans/[ID]

Body Params

Atributo Tipo Obrigatório Descrição
description String Não Descrição do plano
discount Integer Não Percentual de desconto
goal Integer Não Meta de planos a ser vendidos
items Array Não Array de objetos do tipo objeto item do plano
name String Não Nome plano
notify_reactivation_at Date Não Data para notificações no sistema e via e-mail para reativar o plano
status String Não pode ser:
actived quando ativo
paused quando pausado
canceled quando cancelado

Retorno

Em caso de sucesso será retornado um objeto plano.

Remover planos

Ao remover um plano o mesmo não ficará mais como disponível para mensalidades e link de pagamento, porém as cobranças geradas desses items ainda contabilizam o valor total do plano.

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/plans/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "M8YVP5EKDYZ07NZ4L693",
        "description": "Description",
        "discount": 20,
        "goal": 1,
        "name": "Nome do Plano",
        "price": 999.97,
        "price_with_discount": 799.98,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00",
        "deleted_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

DELETE https://api.cobrefacil.com.br/v1/plans/[ID]

Retorno

Em caso de sucesso será retornado um objeto plano com a data de exclusão deleted_at.

Detalhar plano

Informando o ID referenciador é retornado todas as informações do plano.

curl --location --request GET "https://api.cobrefacil.com.br/v1/plans/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "ZCYFP6YXQYZ18NZ4L752",
        "description": "Descrição do Plano",
        "discount": 20,
        "goal": 1,
        "goaled_percentage": 0,
        "items": [
            {
                "id": "CQXXZQ1NV3K8PLE7KMRB",
                "products_services_id": "51MXVCYAQYR53J1YP5X8",
                "quantity": 1,
                "price": 999.97,
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
        ],
        "name": "Nome do Plano",
        "notify_reactivation_at": "2022-01-01",
        "price": 999.97,
        "price_with_discount": 799.98,
        "status": "actived",
        "total_subscriptions": 0,
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/plans/[ID]

Retorno

Atributo Tipo Descrição
id String Identificador do plano
description String Descrição do plano
discount Integer Percentual de desconto
goal Integer Meta de planos a ser vendidos
goaled_percentage Integer Percentual atingido da meta goal
items Array Array de objetos do tipo objeto item do plano
name String Nome plano
notify_reactivation_at Date Data para notificações no sistema e via e-mail para reativar o plano
price Float preço do plano
price_with_discount Float preço com desconto
status String pode ser:
actived quando ativo
paused quando pausado
canceled quando cancelado
total_subscriptions Integer Número de mensalidades com o plano
updated_at DateTime Data que o plano foi atualizado
deleted_at DateTime Data que o plano foi excluído

Listar planos

No endpoint de listar planos é possível filtrar por status, além de limitar a quantidade de itens retornados e ordenação por campo escolhido.

curl --location --request GET "https://api.cobrefacil.com.br/v1/plans" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": [
        {
            "id": "NZM916730PQJLO8KG52X",
            "description": "Descrição do Plano",
            "discount": 20,
            "goal": 1,
            "goaled_percentage": 0,
            "items": [
                {
                    "id": "CQXXZQ1NV3K8PLE7KMRB",
                    "products_services_id": "51MXVCYAQYR53J1YP5X8",
                    "quantity": 1,
                    "price": 999.97,
                    "created_at": "2022-01-01 00:00:00",
                    "updated_at": "2022-01-01 00:00:00"
                }
            ],
            "name": "Nome do Plano",
            "notify_reactivation_at": null,
            "price": 999.97,
            "price_with_discount": 799.98,
            "status": "actived",
            "total_subscriptions": 0,
            "created_at": "2022-01-01 00:00:00",
            "updated_at": "2022-01-01 00:00:00"
        }
    ],
    "pagination": {
        "total_records": 1,
        "display_records": 1
    }
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/plans

URL Parameters

Parâmetro Tipo Descrição
status String Filtrar pelo status do plano, status actived, paused ou canceled, podendo ser enviado mais de um status entre vírgulas, exemplo actived,paused. Caso não seja informado, retorna todos os planos
sort_by String Campo a ser utilizado na ordenação, o padrão é created_at
order_by String Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc
limit Integer Quantidade máxima de registros que devem ser retornados, o padrão é 100
offset Integer Número de registros a serem pulados, o padrão é 0

Retorno

Atributo Tipo Descrição
id String Identificador do plano
description String Descrição do plano
discount Integer Percentual de desconto
goal Integer Meta de planos a ser vendidos
goaled_percentage Integer Percentual atingido da meta goal
items Array Array de objetos do tipo objeto item do plano
name String Nome plano
notify_reactivation_at Date Data para notificações no sistema e via e-mail para reativar o plano
price Float preço do plano
price_with_discount Float preço com atribuição do desconto
status String pode ser:
actived quando ativo
paused quando pausado
canceled quando cancelado
total_subscriptions Integer Número de mensalidades com o plano
updated_at DateTime Data que o plano foi atualizado
deleted_at DateTime Data que o plano foi excluído

Ativar planos

Esse endpoint altera o status do plano para actived.

curl --location --request POST "https://api.cobrefacil.com.br/v1/plans/[ID]/activate" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "ZCYFP6YXQYZ18NZ4L752",
        "description": "Descrição do Plano",
        "discount": 20,
        "goal": 1,
        "items": [
            {
                "id": "CQXXZQ1NV3K8PLE7KMRB",
                "products_services_id": "51MXVCYAQYR53J1YP5X8",
                "quantity": 1,
                "price": 999.97,
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
        ],
        "name": "Nome do Plano",
        "notify_reactivation_at": null,
        "price": 999.97,
        "price_with_discount": 799.98,
        "status": "actived",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/plans/[ID]/activate

Retorno

Em caso de sucesso será retornado um objeto plano.

Pausar planos

Ao pausar um plano o mesmo fica com o status paused e não é exibido na listagem de planos em mensalidades e links de pagamento.

curl --location --request POST "https://api.cobrefacil.com.br/v1/plans/[ID]/pause" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "ZCYFP6YXQYZ18NZ4L752",
        "description": "Descrição do Plano",
        "discount": 20,
        "goal": 1,
        "items": [
            {
                "id": "CQXXZQ1NV3K8PLE7KMRB",
                "products_services_id": "51MXVCYAQYR53J1YP5X8",
                "quantity": 1,
                "price": 999.97,
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
        ],
        "name": "Nome do Plano",
        "notify_reactivation_at": null,
        "price": 999.97,
        "price_with_discount": 799.98,
        "status": "paused",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/plans/[ID]/pause

Retorno

Em caso de sucesso será retornado um objeto plano com status paused.

Cancelar planos

Ao cancelar planos o status do mesmo será canceled e não será exibido na listagem de planos em mensalidades e links de pagamento e não será possível reativá-lo.

curl --location --request POST "https://api.cobrefacil.com.br/v1/plans/[ID]/cancel" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "ZCYFP6YXQYZ18NZ4L752",
        "description": "Descrição do Plano",
        "discount": 20,
        "goal": 1,
        "items": [
            {
                "id": "CQXXZQ1NV3K8PLE7KMRB",
                "products_services_id": "51MXVCYAQYR53J1YP5X8",
                "quantity": 1,
                "price": 999.97,
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
        ],
        "name": "Nome do Plano",
        "notify_reactivation_at": null,
        "price": 999.97,
        "price_with_discount": 799.98,
        "status": "canceled",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/plans/[ID]/cancel

Retorno

Em caso de sucesso será retornado um objeto plano com status canceled.

Cadastrar itens do plano

O cadastro de itens é utilizado para adicionar produtos ou serviços a um plano existente.

curl --location --request POST "https://api.cobrefacil.com.br/v1/plans/[ID]/items" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"quantity\": 1,
        \"product_service_id\": \"K25LRJWON2OE6G5Z37VQ\"
    }"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "CQXXZQ1NV3K8PLE7KMRB",
        "quantity": 1,
        "price": 999.97,
        "products_services_id": "51MXVCYAQYR53J1YP5X8",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/plans/[ID]/items

Body Params

Atributo Tipo Obrigatório Descrição
product_service_id String Sim ID do produto/serviço
quantity Integer Sim Quantidade de items

Retorno

Em caso de sucesso será retornado um objeto item do plano.

Remover itens do plano

Esse endpoint serve para remover itens de produtos/serviços de um plano específico.

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/plans/[ID]/items/[ITEM_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" 

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "data": {
        "id": "CQXXZQ1NV3K8PLE7KMRB",
        "quantity": 1,
        "price": 999.97,
        "products_services_id": "51MXVCYAQYR53J1YP5X8",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00",
        "deleted_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/plans/[ID]/items

Retorno

Em caso de sucesso será retornado um objeto item do plano com deleted_at.

O objeto item do plano

Exemplo de JSON do objeto plano:

{
    "success": true,
    "data": {
        "id": "CQXXZQ1NV3K8PLE7KMRB",
        "quantity": 1,
        "price": 999.97,
        "products_services_id": "51MXVCYAQYR53J1YP5X8",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}
Atributo Tipo Descrição
id String Identificador do plano
quantity Integer Nome plano
price Float preço do plano
product_service Array Objeto do tipo objeto produto/serviço
created_at DateTime Data que o item do plano foi criado
updated_at DateTime Data que o item do plano foi atualizado

Mensalidades

As mensalidades são perfeitas para cobranças recorrentes ou que tenham um período definido, os endpoints para criar, atualizar, renovar, e remover mensalidades.
Você também pode listar filtrando os atributos desejados, detalhar, pausar, cancelar, finalizar, ativar e reativar mensalidades.
As mensalidades possuem itens que são produtos e serviços, os endpoints de criar item, atualizar, remover item da mensalidade e listar.
Existem também a opção de gerar cobrança e ativar para antes ou depois da emissão da nota fiscal.
Os assinantes PRO tem a opção em mensalidades de salvar anexo, remover anexo e exibir link do anexo.

O objeto mensalidade

Exemplo de JSON do objeto mensalidade:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "items": [
      {
        "id": "XXXXXXXXXXXXXXXXXXXX",
        "description": "Produto Especial",
        "price": 500,
        "quantity": 1,
        "type": "service"
      }
    ],
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": null,
    "payable_with": "bankslip,credit,pix",
    "plans_id": null,
    "quantity_generated": 1,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "settings": {
      "discount": {
        "amount": "5.00",
        "limit_date": 1,
        "mode": "percentage"
      },
      "discount_subscription": {
        "amount": "5.00",
        "mode": "percentage",
        "number_installments": 1
      },
      "interest": {
        "amount": "10.00",
        "mode": "monthly_percentage"
      },
      "late_fee": {
        "amount": "10.55",
        "mode": "percentage"
      },
      "send_tax_invoice": 0,
      "warning": {
        "description": "Description"
      },
      "created_at": "2022-01-01 00:00:00",
      "updated_at": "2022-01-01 00:00:00"
    },
    "status": "actived",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}
Atributo Tipo Descrição
contract_number String Número de contrato
create_invoice Date Data de criação da cobrança
customer_id String Id do cliente
due_day Integer Dia da data de vencimento
expires_at Date Data final da mensalidade
first_due_date Date Data de vencimento da primeira cobrança da mensalidade
generate_days Integer Dias antes do vencimento será gerado a cobrança
interval_type String Ciclo de cobrança pode ser diário = day e mensal = month,
interval_size Integer Quantidade de ciclo de cobrança.
exemplo interval_type = month e interval_size = 6 a cobrança será semestral
invoices Array Array de cobranças
items Array Array de objetos - itens de mensalidade
next_expiration Date Data da próxima cobrança
notification_rule_id String Id da régua de cobrança
paused_at Date Data de quando foi pausada a mensalidade
payable_with String Formas aceitas de pagamento, podendo ser: bankslip, credit ou pix
Para mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix
plans_id String Id do plano
quantity_generated Integer Número de cobranças geradas
reactivate_at Date Data de quando será reativada a mensalidade
reference String Referência da mensalidade, podendo ser:
none para "nenhuma"
prev para "Mês anterior"
current para "Mês atual"
next para "Próximo mês"
Exemplo: Vencimento em Setembro, referente ao mês de agosto.
sequencial_number String Número sequencial de mensalidades geradas
settings Object objeto settings
status String Status da mensalidade, a lista completa em status mensalidade
created_at DateTime Data que a mensalidade foi criado
updated_at DateTime Data que a mensalidade foi atualizado
deleted_at DateTime Data que a mensalidade foi deletado

O objeto settings

Atributo Tipo Descrição
discount Json Desconto para pagamento antecipado
discount.mode String Modo de desconto, pode ser: percentage ou fixed
discount.amount Float Valor do desconto em porcentagem ou em reais
discount.limit_date Float Número de dias antes do vencimento para desconto
discount_subscription Json Desconto ao início do contrato
discount_subscription.mode String Modo de desconto no início da mensalidade, pode ser: percentage ou fixed
discount_subscription.amount Float Valor do desconto no início da mensalidade, pode ser em porcentagem ou em reais
discount_subscription.number_installments Float Número de parcelas de desconto no início da mensalidade
interest Json Cobrar juro de mora após vencimento
interest.mode String Modo de juro de mora após vencimento, pode ser: monthly_percentage, daily_percentage e daily_amount
interest.amount Float Valor do juro de mora após vencimento, pode ser em porcentagem ou em reais
late_fee Json Multas para pagamentos após data de vencimento
late_fee.mode String Modo de multas para pagamentos após data de vencimento, pode ser: percentage ou fixed
late_fee.amount Float Valor do multas para pagamentos após data de vencimento, pode ser em porcentagem ou em reais
send_tax_invoice Integer Momento em que a nota fiscal deve ser gerada:
0 não deve gerar nota fiscal
1 a nota fiscal deve ser gerada após confirmação do pagamento
2 a nota fiscal deve ser gerada após a criação da cobrança
OBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal
warning Json Informações de desconto, multas e juros, não terão validade neste campo

O objeto item de mensalidade

Exemplo de JSON do objeto plano:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "description": "Produto Especial",
    "generated_installments": 0,
    "number_installments": 1,
    "price": 500,
    "products_services_id": "XXXXXXXXXXXXXXXXXXXX",
    "quantity": 1,
    "type": "service"
  }
}
Atributo Tipo Descrição
id String Identificador do item
description String Descrição do item
generated_installments Integer Número de cobranças geradas para esse item
number_installments Integer Número de parcelas para esse item
price Float preço do plano
product_service_id Array Objeto do tipo objeto produto/serviço
created_at DateTime Data que o item do plano foi criado
updated_at DateTime Data que o item do plano foi atualizado

Status mensalidades

Status Descrição
actived Mensalidade ativa
canceled Mensalidade cancelada, não são geradas cobranças
finished Mensalidade finalizado de forma manual, não são geradas novas cobranças
inactived Mensalidade inativada, não são geradas novas cobranças
paused Mensalidade pausada, não são geradas novas cobranças
renewed Mensalidade renovada, existe outra mensalidade tendo essa como origem
suspended Mensalidade suspensa, não são geradas novas cobranças
terminated Mensalidade finalizado automática pelo período informado
terminating Mensalidade próxima do tempo de expiração, alerta que não serão geradas novas cobranças

Criar mensalidades

A criação da mensalidade é feita através das informações contratadas pelo cliente como: início de cobrança, planos ou serviços, forma de pagamento, ciclos de pagamento, régua de cobrança, regras de multa, juros e descontos. Depois da mensalidade criada é possível gerar as cobranças através do método gerar cobrança ou aguardar a geração automática.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"customer_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
        \"contract_number\" : \"Número do Contrato\",
        \"first_due_date\" : \"2022-01-01\",
        \"generate_days\" : 1,
        \"interval_type\" : \"month\",
        \"interval_size\" : 1,
        \"items\" : [
                {
                    \"products_services_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
                    \"quantity\" : 1,
                    \"price\": 50000
                }
        ],
        \"notification_rule_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
        \"payable_with\" : \"bankslip,credit,pix\",
        \"plans_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
        \"reference\" : \"none\",
        \"settings\" : {
                \"enable_duplicate\" : 1,
                \"late_fee\"         : {
                        \"mode\"   : \"percentage\",
                        \"amount\" : 10.55
                },
                \"interest\"         : {
                        \"mode\"   : \"monthly_percentage\",
                        \"amount\" : 10.00
                },
                \"discount\"         : {
                        \"mode\"       : \"percentage\",
                        \"amount\"     : 5.00,
                        \"limit_date\" : 1
                },
                \"discount_subscription\" : {
                        \"mode\"       : \"percentage\",
                        \"amount\"     : 5.00,
                        \"number_installments\" : 1
                },
                \"warning\"          : {
                        \"description\" : \"Description\"
                }
        }
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "items": [
      {
        "id": "XXXXXXXXXXXXXXXXXXXX",
        "description": "Produto Especial",
        "price": 500,
        "quantity": 1,
        "type": "service"
      }
    ],
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": null,
    "payable_with": "bankslip,credit,pix",
    "plans_id": null,
    "quantity_generated": 1,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "settings": {
      "discount": {
        "amount": "5.00",
        "limit_date": 1,
        "mode": "percentage"
      },
      "discount_subscription": {
        "amount": "5.00",
        "mode": "percentage",
        "number_installments": 1
      },
      "interest": {
        "amount": "10.00",
        "mode": "monthly_percentage"
      },
      "late_fee": {
        "amount": "10.55",
        "mode": "percentage"
      },
      "send_tax_invoice": 0,
      "warning": {
        "description": "Description"
      }
    },
    "status": "actived",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

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

Body Params

Atributo Tipo Obrigatório Descrição
contract_number String Não Número de contrato
customer_id String Sim Id do cliente
expires_at Date Não Data final da mensalidade
first_due_date Date Sim Data de vencimento da primeira cobrança da mensalidade
generate_days Integer Sim Número de dias antes do vencimento que será gerado a cobrança
interval_type String Não Ciclo de cobrança que pode ser diário = day ou mensal = month, sendo o padrão month
interval_size Integer Sim Quantidade de ciclo de cobrança.
exemplo interval_type = month e interval_size = 6 a cobrança será semestral
items Array Sim* Array de objetos - itens de mensalidade
items.*.products_services_id String Sim Id do produto ou serviço
items.*.quantity Integer Não Quantidade de produtos ou serviços, caso não informado o valor padrão é 1
items.*.price Integer Não Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo
notification_rule_id String Sim Id da régua de cobrança
payable_with String Formas aceitas de pagamento, podendo ser: bankslip, credit ou pix
Para mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix
plans_id String Sim* Id do plano
reference String Sim Referência da mensalidade, podendo ser:
none para "nenhuma"
prev para "Mês anterior"
current para "Mês atual"
next para "Próximo mês"
Exemplo: Vencimento em Setembro, referente ao mês de agosto.
settings Object Não objeto settings

*Lembrando que deve ser escolhido items ou plans_id e não pode ser escolhido os dois ao mesmo tempo.

Retorno

Em caso de sucesso será retornado um objeto mensalidade.

Atualizar mensalidades

A atualização da mensalidade requer somente os dados que vão ser alterados, em caso de produtos/serviços é necessário enviar o id do item para alterá-lo, caso não seja informado o id será criado um novo item.

curl --location --request PUT "https://api.cobrefacil.com.br/v1/subscriptions/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"contract_number\" : \"Número do Contrato\",
        \"next_expiration\" : \"2022-01-01 00:00:00\",
        \"generate_days\" : 1,
        \"interval_type\" : \"month\",
        \"interval_size\" : 1,
        \"items\" : [
                {
                    \"products_services_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
                    \"quantity\" : 1,
                    \"price\": 50000
                }
        ],
        \"notification_rule_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
        \"payable_with\" : \"bankslip,credit,pix\",
        \"plans_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
        \"reference\" : \"none\",
        \"settings\" : {
                \"enable_duplicate\" : 1,
                \"late_fee\"         : {
                        \"mode\"   : \"percentage\",
                        \"amount\" : 10.55
                },
                \"interest\"         : {
                        \"mode\"   : \"monthly_percentage\",
                        \"amount\" : 10.00
                },
                \"discount\"         : {
                        \"mode\"       : \"percentage\",
                        \"amount\"     : 5.00,
                        \"limit_date\" : 1
                },
                \"discount_subscription\" : {
                        \"mode\"       : \"percentage\",
                        \"amount\"     : 5.00,
                        \"number_installments\" : 1
                },
                \"warning\"          : {
                        \"description\" : \"Description\"
                }
        }
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "invoices": [],
    "items": [
      {
        "id": "XXXXXXXXXXXXXXXXXXXX",
        "description": "Produto Especial",
        "price": 500,
        "quantity": 1,
        "type": "service"
      }
    ],
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": null,
    "payable_with": "bankslip,credit,pix",
    "plans_id": null,
    "quantity_generated": 1,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "settings": {
      "discount": {
        "amount": "5.00",
        "limit_date": 1,
        "mode": "percentage"
      },
      "discount_subscription": {
        "amount": "5.00",
        "mode": "percentage",
        "number_installments": 1
      },
      "interest": {
        "amount": "10.00",
        "mode": "monthly_percentage"
      },
      "late_fee": {
        "amount": "10.55",
        "mode": "percentage"
      },
      "send_tax_invoice": 0,
      "warning": {
        "description": "Description"
      }
    },
    "status": "actived",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

PUT https://api.cobrefacil.com.br/v1/subscriptions/[ID]

Body Params

Atributo Tipo Obrigatório Descrição
contract_number String Não Número de contrato
expires_at Date Não Data final da mensalidade
generate_days Integer Não Número de dias antes do vencimento que será gerado a cobrança
interval_type String Não Ciclo de cobrança que pode ser diário = day ou mensal = month, sendo o padrão month
interval_size Integer Não Quantidade de ciclo de cobrança.
exemplo interval_type = month e interval_size = 6 a cobrança será semestral
items Array Não Array de objetos - itens de mensalidade
next_expiration Date Não Data de vencimento da próxima cobrança da mensalidade
notification_rule_id String Não Id da régua de cobrança
payable_with String Formas aceitas de pagamento, podendo ser: bankslip, credit ou pix
Para mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix
plans_id String Não Id do plano
reference String Não Referência da mensalidade, podendo ser:
none para "nenhuma"
prev para "Mês anterior"
current para "Mês atual"
next para "Próximo mês"
Exemplo: Vencimento em Setembro, referente ao mês de agosto.
settings Object Não objeto settings

Retorno

Em caso de sucesso será retornado um objeto mensalidade.

Renovar mensalidades

A renovação de uma mensalidade, é semelhante com o criar mas com a diferença que o status da mensalidade informada será alterado para renewed e criado uma nova mensalidade.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/renew" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"customer_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
        \"contract_number\" : \"Número do Contrato\",
        \"next_expiration\" : \"2022-01-01 00:00:00\",
        \"generate_days\" : 1,
        \"interval_type\" : \"month\",
        \"interval_size\" : 1,
        \"items\" : [
                {
                    \"products_services_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
                    \"quantity\" : 1,
                    \"price\": 50000
                }
        ],
        \"notification_rule_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
        \"payable_with\" : \"bankslip,credit,pix\",
        \"plans_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
        \"reference\" : \"none\",
        \"settings\" : {
                \"enable_duplicate\" : 1,
                \"late_fee\"         : {
                        \"mode\"   : \"percentage\",
                        \"amount\" : 10.55
                },
                \"interest\"         : {
                        \"mode\"   : \"monthly_percentage\",
                        \"amount\" : 10.00
                },
                \"discount\"         : {
                        \"mode\"       : \"percentage\",
                        \"amount\"     : 5.00,
                        \"limit_date\" : 1
                },
                \"discount_subscription\" : {
                        \"mode\"       : \"percentage\",
                        \"amount\"     : 5.00,
                        \"number_installments\" : 1
                },
                \"warning\"          : {
                        \"description\" : \"Description\"
                }
        }
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "invoices": [],
    "items": [
      {
        "id": "XXXXXXXXXXXXXXXXXXXX",
        "description": "Produto Especial",
        "price": 500,
        "quantity": 1,
        "type": "service"
      }
    ],
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": null,
    "payable_with": "bankslip,credit,pix",
    "plans_id": null,
    "quantity_generated": 1,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "settings": {
      "discount": {
        "amount": "5.00",
        "limit_date": 1,
        "mode": "percentage"
      },
      "discount_subscription": {
        "amount": "5.00",
        "mode": "percentage",
        "number_installments": 1
      },
      "interest": {
        "amount": "10.00",
        "mode": "monthly_percentage"
      },
      "late_fee": {
        "amount": "10.55",
        "mode": "percentage"
      },
      "send_tax_invoice": 0,
      "warning": {
        "description": "Description"
      }
    },
    "status": "actived",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

PUT https://api.cobrefacil.com.br/v1/subscriptions/[ID]

Body Params

Atributo Tipo Obrigatório Descrição
contract_number String Não Número de contrato
customer_id String Sim Id do cliente
expires_at Date Não Data final da mensalidade
first_due_date Date Sim Data de vencimento da primeira cobrança da mensalidade
generate_days Integer Sim Número de dias antes do vencimento que será gerado a cobrança
interval_type String Não Ciclo de cobrança que pode ser diário = day ou mensal = month, sendo o padrão month
interval_size Integer Sim Quantidade de ciclo de cobrança.
exemplo interval_type = month e interval_size = 6 a cobrança será semestral
items Array Sim* Array de objetos - itens de mensalidade
notification_rule_id String Sim Id da régua de cobrança
payable_with String Formas aceitas de pagamento, podendo ser: bankslip, credit ou pix
Para mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix
plans_id String Sim* Id do plano
reference String Sim Referência da mensalidade, podendo ser:
none para "nenhuma"
prev para "Mês anterior"
current para "Mês atual"
next para "Próximo mês"
Exemplo: Vencimento em Setembro, referente ao mês de agosto.
settings Object Não objeto settings

Retorno

Em caso de sucesso será retornado um objeto mensalidade.

Remover mensalidades

Para remover uma mensalidade basta enviar um DELETE para com id da mensalidade. Ao remover a mensalidade, todas as cobranças geradas relacionadas a ela continuarão válidas, mas não serão geradas novas cobranças.

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/subscriptions/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "invoices": [],
    "items": [
      {
        "id": "XXXXXXXXXXXXXXXXXXXX",
        "description": "Produto Especial",
        "price": 500,
        "quantity": 1,
        "type": "service"
      }
    ],
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": null,
    "payable_with": "bankslip,credit,pix",
    "plans_id": null,
    "quantity_generated": 1,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "settings": {
      "discount": {
        "amount": "5.00",
        "limit_date": 1,
        "mode": "percentage"
      },
      "discount_subscription": {
        "amount": "5.00",
        "mode": "percentage",
        "number_installments": 1
      },
      "interest": {
        "amount": "10.00",
        "mode": "monthly_percentage"
      },
      "late_fee": {
        "amount": "10.55",
        "mode": "percentage"
      },
      "send_tax_invoice": 0,
      "warning": {
        "description": "Description"
      }
    },
    "status": "actived",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00",
    "deleted_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

DELETE https://api.cobrefacil.com.br/v1/subscriptions/[ID]

Retorno

Em caso de sucesso será retornado um objeto mensalidade com a data de exclusão deleted_at.

Detalhar mensalidades

Para detalhar uma mensalidade é necessário informar o id.

curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "invoices": [],
    "items": [
      {
        "id": "XXXXXXXXXXXXXXXXXXXX",
        "description": "Produto Especial",
        "price": 500,
        "quantity": 1,
        "type": "service"
      }
    ],
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": null,
    "payable_with": "bankslip,credit,pix",
    "plans_id": null,
    "quantity_generated": 1,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "settings": {
      "discount": {
        "amount": "5.00",
        "limit_date": 1,
        "mode": "percentage"
      },
      "discount_subscription": {
        "amount": "5.00",
        "mode": "percentage",
        "number_installments": 1
      },
      "interest": {
        "amount": "10.00",
        "mode": "monthly_percentage"
      },
      "late_fee": {
        "amount": "10.55",
        "mode": "percentage"
      },
      "send_tax_invoice": 0,
      "warning": {
        "description": "Description"
      }
    },
    "status": "actived",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/subscriptions/[ID]

Retorno

Atributo Tipo Descrição
attachment String Url do anexo da mensalidade
contract_number String Número de contrato
create_invoice Date Data de criação da cobrança
customer_id String Id do cliente
due_day Integer Dia da data de vencimento
expires_at Date Data final da mensalidade
first_due_date Date Data de vencimento da primeira cobrança da mensalidade
generate_days Integer Dias antes do vencimento será gerado a cobrança
interval_type String Ciclo de cobrança pode ser diário = day e mensal = month,
interval_size Integer Quantidade de ciclo de cobrança.
exemplo interval_type = month e interval_size = 6 a cobrança será semestral
invoices Array Array de cobranças
items Array Array de objetos - itens de mensalidade
next_expiration Date Data da próxima cobrança
notification_rule_id String Id da régua de cobrança
paused_at Date Data de quando foi pausada a mensalidade
payable_with String Formas aceitas de pagamento, podendo ser: bankslip, credit ou pix
Para mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix
plans_id String Id do plano
quantity_generated Integer Número de cobranças geradas
reactivate_at Date Data de quando será reativada a mensalidade
reference String Referência da mensalidade, podendo ser:
none para "nenhuma"
prev para "Mês anterior"
current para "Mês atual"
next para "Próximo mês"
Exemplo: Vencimento em Setembro, referente ao mês de agosto.
sequencial_number String Número sequencial de mensalidades geradas
settings Object objeto settings
status String Status da mensalidade, a lista completa em status mensalidade
created_at DateTime Data que a mensalidade foi criado
updated_at DateTime Data que a mensalidade foi atualizado

Listar mensalidades

No endpoint de listar mensalidades é possível filtrar por status, além de limitar a quantidade de itens retornados e ordenação por campo escolhido.

curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
  "success": true,
  "data": [
    {
      "id": "XXXXXXXXXXXXXXXXXXXX",
      "attachment": "",
      "contract_number": "",
      "create_invoice": "2022-01-01",
      "customer_id": "XXXXXXXXXXXXXXXXXXXX",
      "due_day": 4,
      "expires_at": null,
      "first_due_date": "2022-01-01",
      "generate_days": 1,
      "interval_size": 1,
      "interval_type": "month",
      "items": [
        {
          "description": "Serviço 1",
          "price": 500,
          "quantity": 1,
          "type": "plan"
        }
      ],
      "next_expiration": "2022-01-01",
      "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
      "paused_at": null,
      "payable_with": "bankslip",
      "plans_id": "XXXXXXXXXXXXXXXXXXXX",
      "price": 500,
      "quantity_generated": 1,
      "reactivate_at": null,
      "reference": "none",
      "sequencial_number": "MENS00000001",
      "settings": {
        "discount": null,
        "discount_subscription": null,
        "interest": null,
        "late_fee": null,
        "send_tax_invoice": 0,
        "warning": {
          "description": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento."
        }
      },
      "status": "actived",
      "created_at": "2022-01-01 00:00:00",
      "updated_at": "2022-01-01 00:00:00"
    }
  ],
  "pagination": {
    "total_records": 1,
    "display_records": 1
  }
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/subscriptions

Retorno

Atributo Tipo Descrição
attachment String Url do anexo da mensalidade
contract_number String Número de contrato
create_invoice Date Data de criação da cobrança
customer_id String Id do cliente
due_day Integer Dia da data de vencimento
expires_at Date Data final da mensalidade
first_due_date Date Data de vencimento da primeira cobrança da mensalidade
generate_days Integer Dias antes do vencimento será gerado a cobrança
interval_type String Ciclo de cobrança pode ser diário = day e mensal = month,
interval_size Integer Quantidade de ciclo de cobrança.
exemplo interval_type = month e interval_size = 6 a cobrança será semestral
invoices Array Array de cobranças
items Array Array de objetos - itens de mensalidade
next_expiration Date Data da próxima cobrança
notification_rule_id String Id da régua de cobrança
paused_at Date Data de quando foi pausada a mensalidade
payable_with String Formas aceitas de pagamento, podendo ser: bankslip, credit ou pix
Para mais de uma forma é só utilizar a , ficando assim bansklisp,credit,pix
plans_id String Id do plano
quantity_generated Integer Número de cobranças geradas
reactivate_at Date Data de quando será reativada a mensalidade
reference String Referência da mensalidade, podendo ser:
none para "nenhuma"
prev para "Mês anterior"
current para "Mês atual"
next para "Próximo mês"
Exemplo: Vencimento em Setembro, referente ao mês de agosto.
sequencial_number String Número sequencial de mensalidades geradas
settings Object objeto settings
status String Status da mensalidade, a lista completa em status mensalidade
created_at DateTime Data que a mensalidade foi criado
updated_at DateTime Data que a mensalidade foi atualizado
total_records Integer Número total de mensalidades cadastrados e filtrados
display_records Integer Número total de mensalidades exibidos

Reativar mensalidades

O endpoint de reativar mensalidade muda o status da mensalidade para actived alterando a data do próximo vencimento e expiração (não obrigatório).

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/reactivate" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"next_expiration\" : \"2022-01-01\",
        \"expires_at\" : \"2022-01-01\"
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "invoices": [],
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": null,
    "payable_with": "bankslip,credit,pix",
    "plans_id": null,
    "quantity_generated": 1,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "settings": {
      "discount": {
        "amount": "5.00",
        "limit_date": 1,
        "mode": "percentage"
      },
      "discount_subscription": {
        "amount": "5.00",
        "mode": "percentage",
        "number_installments": 1
      },
      "interest": {
        "amount": "10.00",
        "mode": "monthly_percentage"
      },
      "late_fee": {
        "amount": "10.55",
        "mode": "percentage"
      },
      "send_tax_invoice": 0,
      "warning": {
        "description": "Description"
      }
    },
    "status": "actived",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/reactivate

Body Params

Atributo Tipo Obrigatório Descrição
next_expiration Date Sim Data de vencimento
expires_at Date Não Data final da mensalidade

Retorno

Em caso de sucesso será retornado um objeto mensalidade.

Pausar mensalidades

O endpoint de pausar mensalidade muda o status da mensalidade para paused e não são geradas novas cobranças.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/pause" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"reactivate_at\" : \"2022-01-01\"
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": "2022-01-01T03:00:00.000000Z",
    "payable_with": "bankslip",
    "plans_id": null,
    "quantity_generated": 0,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "status": "paused",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/pause

Body Params

Atributo Tipo Obrigatório Descrição
reactivate_at Date Não Data para reativar automaticamente a mensalidade

Retorno

Em caso de sucesso será retornado um objeto mensalidade com status paused.

Cancelar mensalidades

O endpoint de pausar mensalidade muda o status da mensalidade para canceled e não são geradas novas cobranças.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/cancel" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": "2022-01-01T03:00:00.000000Z",
    "payable_with": "bankslip",
    "plans_id": null,
    "quantity_generated": 0,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "status": "canceled",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/cancel

Retorno

Em caso de sucesso será retornado um objeto mensalidade com status canceled.

Finalizar mensalidades

Endpoint destinado a finalizar mensalidades para não gerar novas cobranças e indicar o final do contrato.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/finished" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "attachment": null,
    "contract_number": null,
    "create_invoice": "2022-01-01",
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "due_day": 1,
    "expires_at": null,
    "first_due_date": "2022-01-01",
    "generate_days": 1,
    "interval_size": 1,
    "interval_type": "month",
    "next_expiration": "2022-01-01",
    "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
    "paused_at": "2022-01-01T03:00:00.000000Z",
    "payable_with": "bankslip",
    "plans_id": null,
    "quantity_generated": 0,
    "reactivate_at": null,
    "reference": "none",
    "sequencial_number": "MENS00000001",
    "status": "finished",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/finished

Retorno

Em caso de sucesso será retornado um objeto mensalidade com status finished.

Criar item mensalidades

Este endpoint tem como finalidade a criação de itens de mensalidades, sendo utilizado para adicionar produtos ou serviços a uma mensalidade existente.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"quantity\": 1,
        \"product_service_id\": \"K25LRJWON2OE6G5Z37VQ\",
        \"price\": 50000
    }"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "first_due_date": null,
    "number_installments": 1,
    "price": 999.97,
    "products_services_id": "XXXXXXXXXXXXXXXXXXXX",
    "quantity": 1,
    "subscriptions_id": "XXXXXXXXXXXXXXXXXXXX",
    "type": "service",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

Body Params

Atributo Tipo Obrigatório Descrição
products_services_id String Sim Id do produto ou serviço
quantity Integer Não Quantidade de produtos ou serviços, caso não informado o valor padrão é 1
price Integer Não Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items

Retorno

Em caso de sucesso será retornado um objeto item da mensalidade.

Atualizar item mensalidades

Este endpoint tem como finalidade a atualizar itens de mensalidades, sendo utilizado para quantidades, produtos/serviços e preço cobrado de um item.

curl --location --request PUT "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items/[ITEM_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"quantity\": 1,
        \"products_services_id\": \"K25LRJWON2OE6G5Z37VQ\",
        \"price\": 50000
    }"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "first_due_date": null,
    "generated_installments": 0,
    "number_installments": 1,
    "price": 500,
    "products_services_id": "XXXXXXXXXXXXXXXXXXXX",
    "quantity": 1,
    "type": "service",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

PUT https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items

Body Params

Atributo Tipo Obrigatório Descrição
products_services_id String Sim Id do produto ou serviço
quantity Integer Não Quantidade de produtos ou serviços, caso não informado o valor padrão é 1
price Integer Não Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo

Retorno

Em caso de sucesso será retornado um objeto item da mensalidade.

Remover item mensalidades

Remove um item de mensalidade.

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items/[ITEM_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" 

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "first_due_date": null,
    "generated_installments": 0,
    "number_installments": 1,
    "price": 500,
    "products_services_id": "XXXXXXXXXXXXXXXXXXXX",
    "quantity": 1,
    "type": "service",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items

Retorno

Em caso de sucesso será retornado um objeto item da mensalidade com deleted_at.

Listar items mensalidades

Lista todos os itens de mensalidades.

curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" 

Exemplo de JSON retornado:

{
  "success": true,
  "data": [
    {
      "id": "XXXXXXXXXXXXXXXXXXXX",
      "first_due_date": null,
      "generated_installments": 0,
      "number_installments": 1,
      "price": 500,
      "products_services_id": "XXXXXXXXXXXXXXXXXXXX",
      "quantity": 1,
      "type": "service",
      "created_at": "2022-01-01 00:00:00",
      "updated_at": "2022-01-01 00:00:00"
    }
  ]
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/items

Retorno

Em caso de sucesso será retornado um objeto item da mensalidade.

Criar item adicional de mensalidades

Este endpoint tem como finalidade a criação de itens adicionais de mensalidades.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"first_due_date\": \"2022-01-01\",
        \"number_installments\": 10,
        \"product_service_id\": \"K25LRJWON2OE6G5Z37VQ\",
        \"price\": 50000,
        \"quantity\": 1
    }"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "first_due_date": "2022-01-01",
    "number_installments": 1,
    "price": 999.97,
    "products_services_id": "XXXXXXXXXXXXXXXXXXXX",
    "quantity": 1,
    "type": "additional",
    "subscriptions_id": "XXXXXXXXXXXXXXXXXXXX",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

Body Params

Atributo Tipo Obrigatório Descrição
products_services_id String Sim Id do produto ou serviço
quantity Integer Não Quantidade de produtos ou serviços, caso não informado o valor padrão é 1
price Integer Não Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo
number_installments Integer Não Número de parcelas do item adicional, caso não informado o valor padrão é 1
first_due_date Date Não Data de início da cobrança do item adicional, caso não informado o valor padrão é hoje

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals

Retorno

Em caso de sucesso será retornado um objeto item da mensalidade.

Atualizar item adicional de mensalidades

Este endpoint tem como finalidade a atualizar itens adicionais de mensalidades, sendo utilizado para quantidades, produtos/serviços, preço cobrado, data inicial de cobrança e número de parcelas.

curl --location --request PUT "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"first_due_date\": \"2022-01-01\",
        \"number_installments\": 10,
        \"product_service_id\": \"K25LRJWON2OE6G5Z37VQ\",
        \"price\": 50000,
        \"quantity\": 1
    }"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "first_due_date": "2022-01-01",
    "number_installments": 1,
    "price": 999.97,
    "products_services_id": "XXXXXXXXXXXXXXXXXXXX",
    "quantity": 1,
    "type": "additional",
    "subscriptions_id": "XXXXXXXXXXXXXXXXXXXX",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

PUT https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals

Body Params

Atributo Tipo Obrigatório Descrição
products_services_id String Sim Id do produto ou serviço
quantity Integer Não Quantidade de produtos ou serviços, caso não informado o valor padrão é 1
price Integer Não Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290, isso somente em caso do valor do produto/serviço não seja fixo
number_installments Integer Não Número de parcelas do item adicional, caso não informado o valor padrão é 1
first_due_date Date Não Data de início da cobrança do item adicional, caso não informado o valor padrão é hoje

Retorno

Em caso de sucesso será retornado um objeto item da mensalidade.

Remover item adicional de mensalidades

Remove um item adicional de uma mensalidade, mesmo que ele ainda tenha parcelas em aberto.

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals/[ITEM_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" 

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "quantity": 1,
    "price": 999.97,
    "product_service_id": "XXXXXXXXXXXXXXXXXXXX",
    "type": "additional",
    "updated_at": "2022-01-01 00:00:00",
    "created_at": "2022-01-01 00:00:00",
    "deleted_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals

Retorno

Em caso de sucesso será retornado um objeto item da mensalidade com deleted_at.

Listar items adicionais de mensalidades

Lista todos os items adicionais de uma mensalidade.

curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" 

Exemplo de JSON retornado:

{
  "success": true,
  "data": [
    {
      "id": "XXXXXXXXXXXXXXXXXXXX",
      "first_due_date": "2022-01-01",
      "generated_installments": 0,
      "number_installments": 1,
      "price": 500,
      "products_services_id": "XXXXXXXXXXXXXXXXXXXX",
      "quantity": 1,
      "type": "additional",
      "created_at": "2022-01-01 00:00:00",
      "updated_at": "2022-01-01 00:00:00"
    }
  ]
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/additionals

Retorno

Em caso de sucesso será retornado um objeto item da mensalidade.

O objeto item da mensalidade

Exemplo de JSON do objeto mensalidade:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "quantity": 1,
    "price": 999.97,
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00",
    "product_service": "XXXXXXXXXXXXXXXXXXXX"
  }
}
Atributo Tipo Descrição
id String Identificador do mensalidade
first_due_date Date Data de início da cobrança do item mensalidade, em caso de type = additional
number_installments Integer Número de cobranças geradas para esse item, em caso de type = additional
price Float preço do mensalidade
products_services_id Integer Id do produto ou serviço
quantity Integer Nome mensalidade
type String Tipo de item de mensalidade, podendo ser service ou additional
created_at DateTime Data que o item do mensalidade foi criado
updated_at DateTime Data que o item do mensalidade foi atualizado
deleted_at DateTime Data que o item do mensalidade foi deletado

Gerar cobrança mensalidades

Ao executar o endpoint com ID da mensalidade será gerada a próxima cobrança da mensalidade.

curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/generate-invoice" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" 

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "amount": null,
    "amount_released": null,
    "barcode": null,
    "barcode_data": null,
    "booklet": null,
    "customer_id": "XXXXXXXXXXXXXXXXXXXX",
    "discount": null,
    "document_number": null,
    "due_date": "2022-01-01",
    "duedate_reference": null,
    "fine_delay": null,
    "installment": null,
    "installment_number": 1,
    "items": [
      {
        "description": "###Produto Especial",
        "price": "500.00",
        "quantity": 1,
        "type": "service"
      },
      {
        "description": "Desconto Mensalidade",
        "price": "-0.25",
        "quantity": 1,
        "type": "discount_subscription"
      }
    ],
    "paid_at": null,
    "payable_with": "bankslip",
    "payable_with_checkout": 0,
    "payable_with_converted": 0,
    "payment_method": null,
    "pending_reminder_at": null,
    "price": "499.75",
    "price_reference": null,
    "sequencial_number": "COB00000001",
    "settings": {
      "discount": {
        "mode": "percentage",
        "limit_date": 1,
        "amount": "5.00"
      },
      "discount_subscription": {
        "mode": "percentage",
        "amount": "5",
        "number_installments": 1
      },
      "interest": {
        "mode": "monthly_percentage",
        "amount": "10.00"
      },
      "late_fee": {
        "mode": "percentage",
        "amount": "10.55"
      },
      "send_tax_invoice": 0,
      "warning": "Description"
    },
    "status": "pending",
    "tax_invoices_with_status_active": [],
    "total_paid": null,
    "transaction_number": null,
    "url_document": null,
    "url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
    "url_receipt": null,
    "url_tax_invoice": null,
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/generate-invoice

Retorno

Em caso de sucesso será retornado um objeto da cobrança.

Nota fiscal mensalidades

Opção para gerar antes ou depois a nota fiscal para mensalidades. Necessário configuração da empresa para gerar a nota fiscal dentro do sistema.

curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/enable-nf" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
        \"nf_generate\": \"after\"
    }"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "nf_generate": "after"
  }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/enable-nf

Body Parameters

Atributo Tipo Obrigatório Descrição
nf_generate String Sim Geração da Nota-Fiscal antes before ou depois after da geração da cobrança

Retorno

Atributo Tipo Descrição
nf_generate String Geração da Nota-Fiscal antes before ou depois after da geração da cobrança

Salvar anexo

Opção para salvar anexo a uma mensalidade.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
-F "attachment"="@/path/to/a/file.jpg" \

Exemplo de JSON retornado:

{
  "success": true,
  "data": "https://urldaimagem.jpg"
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments

Body Parameters

Atributo Tipo Obrigatório Descrição
attachment File Sim Arquivo anexo de extensão PNG, PDF e DOC com até 2MB de tamanho

Retorno

Atributo Tipo Descrição
data String Url do anexo

Remover anexo

Remove um anexo de uma mensalidade.

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

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

HTTP Request

DELETE https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments

Retorno

Apenas é retornado true se caso o anexo foi removido com sucesso.

Exibe o link temporário de uma mensalidade.

curl --location --request GET "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
  "success": true,
  "data": "https://urldaimagem.jpg"
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/subscriptions/[ID]/attachments

Retorno

Atributo Tipo Descrição
data String Url do anexo

Ativar Cobrança Recorrente

Ativa uma cobrança recorrente. A cobrança recorrente pode ser ativada a qualquer momento após a criação da mensalidade. É necessário que o cliente tenha um cartão de crédito cadastrado como default.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/enable-recurrence" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

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

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/enable-recurrence

Retorno

Atributo Tipo Descrição
data String true se a cobrança recorrente foi ativada com sucesso ou mensagens que impossibilitaram a ativação da cobrança recorrente.

Desativar Cobrança Recorrente

Desativa uma cobrança recorrente.

curl --location --request POST "https://api.cobrefacil.com.br/v1/subscriptions/[ID]/disable-recurrence" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

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

HTTP Request

POST https://api.cobrefacil.com.br/v1/subscriptions/[ID]/disable-recurrence

Retorno

Atributo Tipo Descrição
data String true se a cobrança recorrente foi desativada com sucesso ou mensagem de erro para desativar a cobrança recorrente.

Cobranças

Através da nossa API é possível criar cobranças via Pix , boleto bancário e cartão de crédito utilizando um único endpoint.
Todos os boletos são registrados e para cobranças via cartão de crédito contamos com um sistema de análise de risco para garantir ao máximo a segurança nas transações.

A criação de uma cobrança acontece de forma assíncrona, pela necessidade de realizarmos as ações que garantem a segurança da transação.
Por isso, ao solicitar a criação de uma cobrança, ela ficará com o status processing até que o boleto seja de fato gerado e registrado ou a cobrança via cartão analisada.

Após a cobrança ser processada, o status será atualizado e você será notificado caso tenha configurado um webhook para isso.

Possíveis status

Uma cobrança pode possuir diferentes status e é importante compreender quando cada um deles acontece.

Fluxo dos status para cobranças via Pix e boleto

Ao criar uma cobrança via Pix ou boleto, ela iniciará com o status processing e será atualizado para pending quando a cobrança for gerada e registrada.
Caso a cobrança seja paga o status será alterado para paid e caso seja executada a ação de cancelar o status será alterada para canceled.

Fluxo dos status para cobranças via cartão de crédito

Ao criar uma cobrança via cartão de crédito ela iniciará com o status processing e ficará assim até que a análise da transação seja concluída, após isso, caso a transação seja recusada o status será alterado para declined. Se a transação for sem captura automática e for aprovada o status será alterado para pre_authorized, mas se for com captura automática e for aprovada o status será alterado para paid. No caso de uma captura de transação pré autorizada, caso a captura seja aprovada o status será alterado para paid ou se for recusado para declined.

Durante a comunicação com a adquirente aprovadora caso aconteça algum erro o status será alterado para reversed.

Observação: caso seja utilizada a opção de checkout via cartão, a cobrança ao ser criada ficará com o status pending até o cliente acessar o link de pagamento e informar os dados do cartão de crédito, após isso o fluxo dos status seguirá como explicado anteriormente.

Estorno

Apenas cobranças via cartão de crédito com status paid ou refunded podem ser estornadas, após o estorno o status da cobrança será alterado para refunded.

Fluxo de disputa e charge back

Quando um processo de disputa for iniciado o status da cobrança será alterado para dispute, após a análise da disputa caso o retorno seja favorável ao estabelecimento comercial o status da cobrança voltará a ser paid, mas caso o retorno seja favorável ao comprador o status da cobrança será alterado para charged_back.

Split de pagamentos na cobrança

O split de pagamento é forma ideal para divisão do valor recebido de uma cobrança entre contas Cobre Fácil, isso tudo de forma automática. Ao criar uma cobrança você pode configurar as regras para até 2 recebedores, podendo ser pelo montante fixed que não depende do valor recebido e porcentagem percentage que paga o % sobre o valor recebido. Para mais informações veja na sessão split de pagamentos.

O objeto cobrança

Exemplo de JSON do objeto cobrança:

{
  "id": "ZN8V0PD9W005WLRGQE5K",
  "reference": null,
  "payable_with": "bankslip",
  "due_date": "2020-12-15",
  "price": "89.98",
  "fine_delay": null,
  "total_paid": null,
  "amount_released": null,
  "fee": null,
  "paid_at": null,
  "payment_method": null,
  "document_number": "4604618",
  "url_receipt": null,
  "barcode": "34191090570137951893731339210002284700000008998",
  "barcode_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZUAAAAyCAYAAACUNUbZAAACHUlEQVR42u3V2wqAIAwA0P3/Txc9%0ABD6kuGkQcYIIb63W7EREHNfRXu+z126PUf9b657Gs/OycXrPPZo3u/5L93nqH9VDJS+7xnfX2Y78%0AVOq0uu9m5vfijdrV/Zep02q8mbytfJdM/Oy+XHmfal1V/4cr+Q+oQAUqUIEKVKACFahABSpQgQpU%0AoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKAC%0AFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWo%0AQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAF%0AKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQ%0AgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEK%0AVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSg%0AAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIV%0AqEAFKv9G5QSDfSad5j+EigAAAABJRU5ErkJggg==%0A",
  "status": "pending",
  "settings": {
    "late_fee": null,
    "interest": null,
    "discount": null,
    "warning": null,
    "max_installments": null,
    "send_tax_invoice": 1
  },
  "split_rules": [
    {
      "id": "O0QTKY8VNNOR5GXW7DLZ",
      "payment_method": null,
      "mode": "fixed",
      "amount": 10,
      "status": "pending",
      "document": "58267712080152"
    }
  ],
  "items": [
    {
      "description": "Teclado",
      "quantity": 1,
      "price": "49.99"
    },
    {
      "description": "Mouse",
      "quantity": 1,
      "price": "39.99"
    }
  ],
  "customer": {
    "id": "Y73MNPGJ18Y18V5KQODX",
    "person_type": 1,
    "ein": null,
    "company_name": null,
    "taxpayer_id": "37673788250",
    "personal_name": "João da Silva",
    "telephone": "11988887777",
    "cellular": "11999999999",
    "email": "joao@cobrefacil.com.br",
    "email_cc": "maria@cobrefacil.com.br",
    "address": {
      "id": "E1V3649DR48XJQ87OMNL",
      "description": "Endereço principal",
      "zipcode": "01311000",
      "street": "Avenida Paulista",
      "number": "807",
      "complement": "A813 CJ 2315",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "created_at": "2020-06-25T14:01:40-03:00",
      "updated_at": "2020-06-25T14:01:40-03:00",
      "deleted_at": null
    },
    "full_name": "João da Silva",
    "document": "37673788250",
    "created_at": "2020-06-25T14:01:40-03:00",
    "updated_at": "2020-06-25T14:01:41-03:00",
    "deleted_at": null
  },
  "url": "https://app.cobrefacil.com.br/minha-fatura/ZN8V0PD9W005WLRGQE5K",
  "url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/ZN8V0PD9W005WLRGQE5K/boleto-impressao",
  "pix_br_code": null,
  "pix_emv": null,
  "created_at": "2020-06-25T14:01:52-03:00",
  "updated_at": "2020-06-25T14:01:54-03:00"
}

Este objeto é utilizado tanto para boleto quanto cartão de crédito.

Por este motivo, para facilitar a leitura dos dados retornados alguns atributos são exibidos apenas para determinados tipos de cobrança.

Atributo Tipo Descrição
id String Identificador da cobrança
reference String Código de referência utilizado para identificar a cobrança no seu sistema
status String Situação atual da cobrança, pode ser:
processing o sistema está processando a cobranç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 Formas de pagamento aceitas:
bankslip boleto
credit cartão de crédito
pix Pix
OBS: caso deseje informar mais de uma forma de pagamento, utilize vírgula para separar os valores, exemplo:
bankslip,credit
payment_method String Forma de pagamento, este campo é preenchido apenas quando a cobrança é paga e pode ser:
bankslip boleto
credit cartão de crédito
pix Pix
price Float Valor da cobrança
total_paid Float Valor pago
amount_released Float Valor liberado depois de pago, descontando a tarifa da Cobre Fácil
fee Float Tarifa da Cobre Fácil
paid_at Date Data de pagamento
due_date Date Data de vencimento da cobrança. OBS: utilizado apenas por cobranças via boleto
fine_delay Float Valor da multa da segunda via. OBS: utilizado apenas por cobranças via boleto
document_number String Número do documento. OBS: utilizado apenas por cobranças via boleto
url_receipt String URL do recibo de pagamento
transaction_number String Número de identificação da transação. OBS: utilizado apenas por cobranças via cartão de crédito
barcode String Código de barras. OBS: utilizado apenas por cobranças via boleto
barcode_data String Imagem do código de barras em formato base64. OBS: utilizado apenas por cobranças via boleto
split_rules Array Split de pagamento somente para boleto
split_rules[].id String Identificador do split de pagamento
split_rules[].payment_method String Método de pagamento do split de pagamento
split_rules[].mode String Modo que split de pagamento será calculado, pode ser:
percentage porcentagem sobre o valor total
fixed valor fixo
split_rules[].amount Float Porcentagem ou valor do split de pagamento
split_rules[].status String Status do split de pagamento, pode ser:
pending o split de pagamento ainda não foi pago
paid o split de pagamento foi pago
split_rules[].document String CPF ou CNPJ do recebedor do split de pagamento
items Array Produtos ou serviços que estão sendo cobrados
items[].description String Descrição do item
items[].quantity String Quantidade cobrada do item
items[].price Float Valor unitário do item
settings Object Configurações da cobrança. OBS: utilizado apenas por cobranças do tipo bankslip e all
settings.late_fee Object Multa por atraso
settings.late_fee.mode String Modo que a multa por atraso será calculada, pode ser:
percentage porcentagem sobre o valor 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
settings.warning String Mensagem exibida no campo instruções do boleto
settings.max_installments Integer Máximo de parcelas que o cliente pode escolher ao realizar um pagamento via cartão de crédito
settings.send_tax_invoice Integer Momento em que a nota fiscal deve ser gerada:
0 não deve gerar nota fiscal
1 a nota fiscal deve ser gerada após confirmação do pagamento
2 a nota fiscal deve ser gerada após a criação da cobrança
OBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal
customer Object Cliente da cobrança
credit_card Object Cartão de crédito utilizado
OBS: utilizado apenas por cobranças via cartão de crédito
capture Integer 0 Criar uma pré-autorização para capturar 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
url_bankslip String URL para visualizar apenas o boleto
OBS: utilizado apenas por cobranças via boleto
pix_br_code String Representação do BR Code em formato Base64
(BR Code é o nome do padrão de QR Code para Pix)
OBS: utilizado apenas por cobranças via Pix
pix_emv String Código para realizar o pagamento através da função copia-cola
OBS: utilizado apenas por cobranças via Pix
created_at DateTime Data que a cobrança foi criada
updated_at DateTime Data que a cobrança foi atualizada

Criar cobrança via Pix

curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"reference\": \"100042\",
    \"payable_with\": \"pix\",
    \"customer_id\": \"Y73MNPGJ18Y18V5KQODX\",
    \"due_date\": \"2020-12-15\",
    \"items\": [
        {
            \"description\": \"Teclado\",
            \"quantity\": 1,
            \"price\": 4999
        },
        {
            \"description\": \"Mouse\",
            \"quantity\": 1,
            \"price\": 3999
        }
    ],
    \"settings\": {
        \"late_fee\": {
            \"mode\": \"percentage\",
            \"amount\": 10
        },
        \"interest\": {
            \"mode\": \"daily_percentage\",
            \"amount\": 0.1
        },
        \"discount\": {
            \"mode\": \"fixed\",
            \"amount\": 9.99,
            \"limit_date\": 5
        },
        \"warning\": {
            \"description\": \"- Em caso de dúvidas entre em contato com nossa Central de Atendimento.\"
        },
        \"send_tax_invoice\": 1
    }
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "2KD9LGERW897NZ6JM5V4",
    "reference": "100042",
    "payable_with": "pix",
    "due_date": "2020-12-15",
    "price": "89.98",
    "fine_delay": null,
    "total_paid": null,
    "amount_released": null,
    "fee": null,
    "paid_at": null,
    "payment_method": null,
    "document_number": null,
    "url_receipt": null,
    "barcode": null,
    "barcode_data": null,
    "status": "processing",
    "settings": {
      "late_fee": {
        "mode": "percentage",
        "amount": "10"
      },
      "interest": {
        "mode": "daily_percentage",
        "amount": "0.1"
      },
      "discount": {
        "mode": "fixed",
        "limit_date": 5,
        "amount": "9.99"
      },
      "warning": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento.",
      "max_installments": null,
      "send_tax_invoice": 1
    },
    "items": [
      {
        "description": "Teclado",
        "quantity": 1,
        "price": "49.99"
      },
      {
        "description": "Mouse",
        "quantity": 1,
        "price": "39.99"
      }
    ],
    "customer": {
      "id": "Y73MNPGJ18Y18V5KQODX",
      "person_type": 1,
      "ein": null,
      "company_name": null,
      "taxpayer_id": "12345678909",
      "personal_name": "João da Silva Machado",
      "telephone": "11988887777",
      "cellular": "11988887777",
      "email": "joaosilva@cobrefacil.com.br",
      "email_cc": "maria@cobrefacil.com.br",
      "address": {
        "id": "E1V3649DR48XJQ87OMNL",
        "description": "AP 42",
        "zipcode": "01311000",
        "street": "Avenida Paulista",
        "number": "807",
        "complement": "A813 CJ 2315",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "created_at": "2020-06-25T09:52:48-03:00",
        "updated_at": "2020-06-25T09:55:50-03:00",
        "deleted_at": null
      },
      "full_name": "João da Silva Machado",
      "document": "12345678909",
      "created_at": "2020-06-25T09:52:48-03:00",
      "updated_at": "2020-06-25T09:55:50-03:00",
      "deleted_at": null
    },
    "url": "https://app.cobrefacil.com.br/minha-fatura/2KD9LGERW897NZ6JM5V4",
    "created_at": "2020-06-25T10:14:22-03:00",
    "updated_at": "2020-06-25T10:14:22-03:00"
  }
}

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

Vencimento e valor:

Desconto, juros e multa:

HTTP Request

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

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
reference String Não Código de referência utilizado para identificar a cobrança no seu sistema
payable_with String Sim Informe pix
customer_id String Sim Identificador do cliente
due_date Date Sim Data de vencimento da cobrança
items Array Sim Produtos ou serviços que estão sendo cobrados
items[].description String Sim Descrição do item
items[].quantity Float Sim Quantidade cobrada do item
items[].price Integer Sim Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290
settings Object Não Configurações da cobrança
settings.late_fee Object Não Multa por atraso
settings.late_fee.mode String Quando settings.late_fee for informado Modo que a multa por atraso será calculada, pode ser:
percentage porcentagem sobre o valor 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
settings.warning Object Não Instruções gerais sobre o pagamento
settings.warning.description String Quando settings.warning for informado Mensagem contendo instruções gerais sobre o pagamento
settings.send_tax_invoice Integer Não Momento em que a nota fiscal deve ser gerada:
0 não deve gerar nota fiscal
1 a nota fiscal deve ser gerada após confirmação do pagamento
2 a nota fiscal deve ser gerada após a criação da cobrança
OBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal

Retorno

Em caso de sucesso será retornado um objeto cobrança.

Criar cobrança via boleto

curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"reference\": \"100042\",
    \"payable_with\": \"bankslip\",
    \"customer_id\": \"Y73MNPGJ18Y18V5KQODX\",
    \"due_date\": \"2020-12-15\",
    \"split_rules\": [
        {
            \"document\": \"58267712080152\",
            \"mode\": \"fixed\",
            \"amount\": 1000
        }
    ],
    \"items\": [
        {
            \"description\": \"Teclado\",
            \"quantity\": 1,
            \"price\": 4999
        },
        {
            \"description\": \"Mouse\",
            \"quantity\": 1,
            \"price\": 3999
        }
    ],
    \"settings\": {
        \"late_fee\": {
            \"mode\": \"percentage\",
            \"amount\": 10
        },
        \"interest\": {
            \"mode\": \"daily_percentage\",
            \"amount\": 0.1
        },
        \"discount\": {
            \"mode\": \"fixed\",
            \"amount\": 9.99,
            \"limit_date\": 5
        },
        \"warning\": {
            \"description\": \"- Em caso de dúvidas entre em contato com nossa Central de Atendimento.\"
        },
        \"send_tax_invoice\": 1
    }
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "2KD9LGERW897NZ6JM5V4",
    "reference": "100042",
    "payable_with": "bankslip",
    "due_date": "2020-12-15",
    "price": "89.98",
    "fine_delay": null,
    "total_paid": null,
    "amount_released": null,
    "fee": null,
    "paid_at": null,
    "payment_method": null,
    "document_number": null,
    "url_receipt": null,
    "barcode": "34191090570137951893731339210002284700000008998",
    "barcode_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZUAAAAyCAYAAACUNUbZAAACHUlEQVR42u3V2wqAIAwA0P3/Txc9%0ABD6kuGkQcYIIb63W7EREHNfRXu+z126PUf9b657Gs/OycXrPPZo3u/5L93nqH9VDJS+7xnfX2Y78%0AVOq0uu9m5vfijdrV/Zep02q8mbytfJdM/Oy+XHmfal1V/4cr+Q+oQAUqUIEKVKACFahABSpQgQpU%0AoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKAC%0AFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWo%0AQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAF%0AKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQ%0AgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEK%0AVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSg%0AAhWoQAUqUIEKVKACFahABSpQgQpUoAIVqEAFKlCBClSgAhWoQAUqUIEKVKACFahABSpQgQpUoAIV%0AqEAFKv9G5QSDfSad5j+EigAAAABJRU5ErkJggg==%0A",
    "status": "processing",
    "settings": {
      "late_fee": {
        "mode": "percentage",
        "amount": "10"
      },
      "interest": {
        "mode": "daily_percentage",
        "amount": "0.1"
      },
      "discount": {
        "mode": "fixed",
        "limit_date": 5,
        "amount": "9.99"
      },
      "warning": "- Em caso de dúvidas entre em contato com nossa Central de Atendimento.",
      "max_installments": null,
      "send_tax_invoice": 1
    },
    "split_rules": [
      {
        "id": "O0QTKY8VNNOR5GXW7DLZ",
        "payment_method": null,
        "mode": "fixed",
        "amount": 10,
        "status": "pending",
        "document": "58267712080152"
      }
    ],
    "items": [
      {
        "description": "Teclado",
        "quantity": 1,
        "price": "49.99"
      },
      {
        "description": "Mouse",
        "quantity": 1,
        "price": "39.99"
      }
    ],
    "customer": {
      "id": "Y73MNPGJ18Y18V5KQODX",
      "person_type": 1,
      "ein": null,
      "company_name": null,
      "taxpayer_id": "12345678909",
      "personal_name": "João da Silva Machado",
      "telephone": "11988887777",
      "cellular": "11988887777",
      "email": "joaosilva@cobrefacil.com.br",
      "email_cc": "maria@cobrefacil.com.br",
      "address": {
        "id": "E1V3649DR48XJQ87OMNL",
        "description": "AP 42",
        "zipcode": "01311000",
        "street": "Avenida Paulista",
        "number": "807",
        "complement": "A813 CJ 2315",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "created_at": "2020-06-25T09:52:48-03:00",
        "updated_at": "2020-06-25T09:55:50-03:00",
        "deleted_at": null
      },
      "full_name": "João da Silva Machado",
      "document": "12345678909",
      "created_at": "2020-06-25T09:52:48-03:00",
      "updated_at": "2020-06-25T09:55:50-03:00",
      "deleted_at": null
    },
    "url": "https://app.cobrefacil.com.br/minha-fatura/2KD9LGERW897NZ6JM5V4",
    "created_at": "2020-06-25T10:14:22-03:00",
    "updated_at": "2020-06-25T10:14:22-03:00"
  }
}

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

Vencimento e valor:

Desconto, juros e multa:

HTTP Request

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

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
reference String Não Código de referência utilizado para identificar a cobrança no seu sistema
payable_with String Sim Informe bankslip
customer_id String Sim Identificador do cliente
due_date Date Sim Data de vencimento da cobrança
split_rules Array Não Array de regras de split de pagamento (divisão da cobrança), sendo no máximo duas por cobrança
split_rules[].document String Sim Documento da conta Cobre Fácil, sendo CPF ou CNPJ, lembrando que deve ser uma conta ativa
split_rules[].mode String Sim Modo que split de pagamento será calculado, pode ser:
percentage porcentagem sobre o valor total
fixed valor fixo
split_rules[].amount Integer Sim Porcentagem ou valor do split de pagamento, exemplo: 10,5% deve ser informado como 1050 ou quando valor R$ 10,90 deve ser informado como 1090
items Array Sim Produtos ou serviços que estão sendo cobrados
items[].description String Sim Descrição do item
items[].quantity Float Sim Quantidade cobrada do item
items[].price Integer Sim Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290
settings Object Não Configurações da cobrança
settings.late_fee Object Não Multa por atraso
settings.late_fee.mode String Quando settings.late_fee for informado Modo que a multa por atraso será calculada, pode ser:
percentage porcentagem sobre o valor 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
settings.warning Object Não Instruções do boleto
settings.warning.description String Quando settings.warning for informado Mensagem exibida no campo instruções do boleto
settings.send_tax_invoice Integer Não Momento em que a nota fiscal deve ser gerada:
0 não deve gerar nota fiscal
1 a nota fiscal deve ser gerada após confirmação do pagamento
2 a nota fiscal deve ser gerada após a criação da cobrança
OBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal

Retorno

Em caso de sucesso será retornado um objeto cobrança.

Autorizar cobrança via cartão

curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"payable_with\": \"credit\",
    \"customer_id\": \"Z8J53ROD2JK1PQ47WG0E\",
    \"credit_card_id\": \"E65OPXNV9D59WM7JL402\",
    \"capture\": 0,
    \"session_id\": \"SESSION_CLIENT\",
    \"request_ip\": \"168.190.36.98\",
    \"installment\": {
        \"number\": 3,
        \"mode\": \"with_interest\"
    },
    \"items\": [
        {
            \"description\": \"Teclado\",
            \"quantity\": 1,
            \"price\": 4999
        },
        {
            \"description\": \"Mouse\",
            \"quantity\": 1,
            \"price\": 3999
        }
    ],
    \"settings\": {
        \"send_tax_invoice\": 1
    }
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "OY4Q3NVG7VD759PRLD60",
    "reference": null,
    "payable_with": "credit",
    "due_date": "2020-06-25",
    "price": "89.98",
    "total_paid": null,
    "amount_released": null,
    "fee": null,
    "paid_at": null,
    "payment_method": null,
    "transaction_number": "Z777775-0716a705-b5cb-4ec7-ae13-773dbd378c71",
    "url_receipt": null,
    "status": "processing",
    "request_ip": "168.190.36.98",
    "capture": 0,
    "amount_refunded": 0,
    "installment": {
      "mode": "with_interest",
      "number": 3
    },
    "credit_card": {
      "id": "E65OPXNV9D59WM7JL402",
      "customer_id": "Z8J53ROD2JK1PQ47WG0E",
      "default": 1,
      "first6_digits": "453900",
      "last4_digits": "5497",
      "brand": "visa",
      "expiration_year": "2021",
      "expiration_month": "12",
      "created_at": "2020-06-25T10:26:02-03:00",
      "updated_at": "2020-06-25T10:26:03-03:00",
      "deleted_at": null
    },
    "settings": {
      "send_tax_invoice": 1
    },
    "items": [
      {
        "description": "Teclado",
        "quantity": 1,
        "price": "49.99"
      },
      {
        "description": "Mouse",
        "quantity": 1,
        "price": "39.99"
      }
    ],
    "customer": {
      "id": "Z8J53ROD2JK1PQ47WG0E",
      "person_type": 1,
      "ein": null,
      "company_name": "COBRE FACIL LTDA ME",
      "taxpayer_id": "12345678909",
      "personal_name": "João da Silva",
      "telephone": "11988887777",
      "cellular": "11988887777",
      "email": "joao@cobrefacil.com.br",
      "email_cc": null,
      "address": {
        "id": "9W2LVGOPRJMR780DEJK1",
        "description": "Endereço principal",
        "zipcode": "01311100",
        "street": "Av Paulista",
        "number": "807",
        "complement": "A813 CJ 2315",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "created_at": "2020-06-25T10:26:02-03:00",
        "updated_at": "2020-06-25T10:26:02-03:00",
        "deleted_at": null
      },
      "full_name": "João da Silva",
      "document": "12345678909",
      "created_at": "2020-06-25T10:26:02-03:00",
      "updated_at": "2020-06-25T10:26:02-03:00",
      "deleted_at": null
    },
    "url": null,
    "created_at": "2020-06-25T13:59:40-03:00",
    "updated_at": "2020-06-25T13:59:40-03:00"
  }
}

Na autorização de uma cobrança via cartão de crédito é possível utilizar um cartão cadastrado, informando o id dele ou cadastrar um novo na mesma requisição de criação da cobrança .

Ao criar uma cobrança via cartão de crédito, o sistema primeiro irá fazer uma reserva do valor cobrado e depois uma confirmação de cobrança no saldo do portador do cartão. Estes processos são chamados de autorização e captura e podem ser feitos juntos ou separadamente de acordo com a necessidade.

O session_id é um identificador único da sessão do cliente, ele é utilizado na análise de risco da transação via cartão de crédito. Para funcionamento correto é obrigatório utilizar o script abaixo no seu site:


<form ...>
    <input type="hidden" id="cobrefacil_session_id" value="">
</form>
<script src="https://app.cobrefacil.com.br/assets/js/credit-card-risk.js"></script> 

HTTP Request

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

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
reference String Não Código de referência utilizado para identificar a cobrança no seu sistema
payable_with String Sim Informe credit
customer_id String Sim Identificador do cliente
credit_card_id String Quando credit_card não for informado Identificador do cartão de crédito
credit_card Object Quando credit_card_id não for informado Cartão de crédito
credit_card.name String Quando credit_card for informado Nome do portador do cartão
credit_card.number String Quando credit_card for informado Número do cartão
credit_card.expiration_month String Quando credit_card for informado Mês de expiração do cartão, deve conter 2 dígitos
credit_card.expiration_year String Quando credit_card for informado Ano de expiração do cartão, deve conter 4 dígitos
credit_card.security_code String Quando credit_card for informado Código de segurança do cartão
capture Integer Quando credit_card for informado 0 Criar uma pré-autorização para capturar posteriormente
1 Capturar transação
request_ip String Não Ip do cliente, utilizado na análise de risco
session_id String Não Identificador da sessão do cliente, utilizado na análise de risco
installment Object Quando credit_card for informado Configurações de parcelamento
installment.number Integer Quando installment for informado Número de parcelas, informe entre 1 e 12
installment.mode String Quando installment for informado Modo de parcelamento:
with_interest com juros no 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
settings.send_tax_invoice Integer Não Momento em que a nota fiscal deve ser gerada:
0 não deve gerar nota fiscal
1 a nota fiscal deve ser gerada após confirmação do pagamento
2 a nota fiscal deve ser gerada após a criação da cobrança
OBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal

Retorno

Em caso de sucesso será retornado um objeto cobrança.

Capturar cobrança via cartão

curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices/[ID]/capture" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"amount\": 6998
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "OY4Q3NVG7VD759PRLD60",
    "reference": null,
    "payable_with": "credit",
    "due_date": "2020-06-25",
    "price": "89.98",
    "total_paid": "89.98",
    "amount_released": null,
    "fee": "3.85",
    "paid_at": "2020-06-25",
    "payment_method": "credit",
    "transaction_number": "Z777775-0716a705-b5cb-4ec7-ae13-773dbd378c71",
    "url_receipt": null,
    "status": "paid",
    "request_ip": "168.190.36.98",
    "capture": 0,
    "amount_refunded": 0,
    "installment": {
      "mode": "with_interest",
      "number": 3
    },
    "credit_card": {
      "id": "E65OPXNV9D59WM7JL402",
      "customer_id": "Z8J53ROD2JK1PQ47WG0E",
      "default": 1,
      "first6_digits": "453900",
      "last4_digits": "5497",
      "brand": "visa",
      "expiration_year": "2021",
      "expiration_month": "12",
      "created_at": "2020-06-25T10:26:02-03:00",
      "updated_at": "2020-06-25T10:26:03-03:00",
      "deleted_at": null
    },
    "settings": {
      "send_tax_invoice": 1
    },
    "items": [
      {
        "description": "Teclado",
        "quantity": 1,
        "price": "49.99"
      },
      {
        "description": "Mouse",
        "quantity": 1,
        "price": "39.99"
      }
    ],
    "customer": {
      "id": "Z8J53ROD2JK1PQ47WG0E",
      "person_type": 1,
      "ein": null,
      "company_name": "COBRE FACIL LTDA ME",
      "taxpayer_id": "12345678909",
      "personal_name": "João da Silva",
      "telephone": "11988887777",
      "cellular": "11988887777",
      "email": "joao@cobrefacil.com.br",
      "email_cc": null,
      "address": {
        "id": "9W2LVGOPRJMR780DEJK1",
        "description": "Endereço principal",
        "zipcode": "01311100",
        "street": "Av Paulista",
        "number": "807",
        "complement": "A813 CJ 2315",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "created_at": "2020-06-25T10:26:02-03:00",
        "updated_at": "2020-06-25T10:26:02-03:00",
        "deleted_at": null
      },
      "full_name": "João da Silva",
      "document": "12345678909",
      "created_at": "2020-06-25T10:26:02-03:00",
      "updated_at": "2020-06-25T10:26:02-03:00",
      "deleted_at": null
    },
    "url": null,
    "created_at": "2020-06-25T13:59:40-03:00",
    "updated_at": "2020-06-25T14:00:44-03:00"
  }
}

Utilize essa opção para capturar uma transação pré autorizada, utilizando ID da cobrança.

É possível capturar apenas um valor menor ou igual ao valor total da cobrança.

HTTP Request

POST https://api.cobrefacil.com.br/v1/invoices/[ID]/capture

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador da cobrança

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
amount Integer Não Valor a ser capturado em centavos, exemplo: R$ 42,90 deve ser informado como 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
        }
    ],
    \"settings\": {
        \"late_fee\": {
            \"mode\": \"percentage\",
            \"amount\": 10
        },
        \"interest\": {
            \"mode\": \"daily_percentage\",
            \"amount\": 0.1
        },
        \"discount\": {
            \"mode\": \"fixed\",
            \"amount\": 9.99,
            \"limit_date\": 5
        },
        \"max_installments\": 3,
        \"send_tax_invoice\": 1
    }
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "OY4Q3NVG7VD759PRLD60",
    "reference": null,
    "payable_with": "credit",
    "due_date": "2020-06-25",
    "price": "89.98",
    "total_paid": null,
    "amount_released": null,
    "fee": null,
    "paid_at": null,
    "payment_method": null,
    "transaction_number": null,
    "url_receipt": null,
    "status": "pending",
    "request_ip": "168.190.36.98",
    "capture": 0,
    "amount_refunded": 0,
    "items": [
      {
        "description": "Teclado",
        "quantity": 1,
        "price": "49.99"
      },
      {
        "description": "Mouse",
        "quantity": 1,
        "price": "39.99"
      }
    ],
    "customer": {
      "id": "Z8J53ROD2JK1PQ47WG0E",
      "person_type": 1,
      "ein": null,
      "company_name": "COBRE FACIL LTDA ME",
      "taxpayer_id": "12345678909",
      "personal_name": "João da Silva",
      "telephone": "11988887777",
      "cellular": "11988887777",
      "email": "joao@cobrefacil.com.br",
      "email_cc": null,
      "address": {
        "id": "9W2LVGOPRJMR780DEJK1",
        "description": "Endereço principal",
        "zipcode": "01311100",
        "street": "Av Paulista",
        "number": "807",
        "complement": "A813 CJ 2315",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "created_at": "2020-06-25T10:26:02-03:00",
        "updated_at": "2020-06-25T10:26:02-03:00",
        "deleted_at": null
      },
      "full_name": "João da Silva",
      "document": "12345678909",
      "created_at": "2020-06-25T10:26:02-03:00",
      "updated_at": "2020-06-25T10:26:02-03:00",
      "deleted_at": null
    },
    "settings": {
      "late_fee": {
        "mode": "percentage",
        "amount": "10"
      },
      "interest": {
        "mode": "daily_percentage",
        "amount": "0.1"
      },
      "discount": {
        "mode": "fixed",
        "limit_date": 5,
        "amount": "9.99"
      },
      "max_installments": 3,
      "send_tax_invoice": 1
    },
    "url": null,
    "created_at": "2020-06-25T13:59:40-03:00",
    "updated_at": "2020-06-25T14:00:44-03:00"
  }
}

HTTP Request

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

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
payable_with String Sim Informe credit
customer_id String Sim Identificador do cliente
due_date Date Sim Prazo máximo para pagamento da cobrança
items Array Sim Produtos ou serviços que estão sendo cobrados
items[].description String Sim Descrição do item
items[].quantity Float Sim Quantidade cobrada do item
items[].price Integer Sim Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290
settings Object Não Configurações da cobrança
settings.late_fee Object Não Multa por atraso
settings.late_fee.mode String Quando settings.late_fee for informado Modo que a multa por atraso será calculada, pode ser:
percentage porcentagem sobre o valor 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
settings.max_installments Integer Não Máximo de parcelas que o cliente pode escolher ao realizar o pagamento
settings.send_tax_invoice Integer Não Momento em que a nota fiscal deve ser gerada:
0 não deve gerar nota fiscal
1 a nota fiscal deve ser gerada após confirmação do pagamento
2 a nota fiscal deve ser gerada após a criação da cobrança
OBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal

Retorno

Em caso de sucesso será retornado um objeto cobrança.

Detalhar cobrança

curl --location --request GET "https://api.cobrefacil.com.br/v1/invoices/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Para detalhar uma cobrança específica basta fornecer o identificador retornado na criação dela.

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "ZN8V0PD9W005WLRGQE5K",
    "reference": null,
    "payable_with": "bankslip",
    "due_date": "2020-12-15",
    "price": "89.98",
    "fine_delay": null,
    "total_paid": null,
    "amount_released": null,
    "fee": null,
    "paid_at": null,
    "payment_method": null,
    "document_number": null,
    "url_receipt": null,
    "barcode": null,
    "barcode_data": null,
    "status": "processing",
    "settings": {
      "late_fee": null,
      "interest": null,
      "discount": null,
      "warning": null,
      "max_installments": null,
      "send_tax_invoice": 1
    },
    "items": [
      {
        "description": "Teclado",
        "quantity": 1,
        "price": "49.99"
      },
      {
        "description": "Mouse",
        "quantity": 1,
        "price": "39.99"
      }
    ],
    "customer": {
      "id": "Y73MNPGJ18Y18V5KQODX",
      "person_type": 1,
      "ein": null,
      "company_name": null,
      "taxpayer_id": "37673788250",
      "personal_name": "João da Silva",
      "telephone": "11988887777",
      "cellular": "11999999999",
      "email": "joao@cobrefacil.com.br",
      "email_cc": "maria@cobrefacil.com.br",
      "address": {
        "id": "E1V3649DR48XJQ87OMNL",
        "description": "Endereço principal",
        "zipcode": "01311000",
        "street": "Avenida Paulista",
        "number": "807",
        "complement": "A813 CJ 2315",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "created_at": "2020-06-25T14:01:40-03:00",
        "updated_at": "2020-06-25T14:01:40-03:00",
        "deleted_at": null
      },
      "full_name": "João da Silva",
      "document": "37673788250",
      "created_at": "2020-06-25T14:01:40-03:00",
      "updated_at": "2020-06-25T14:01:41-03:00",
      "deleted_at": null
    },
    "url": "https://app.cobrefacil.com.br/minha-fatura/ZN8V0PD9W005WLRGQE5K",
    "created_at": "2020-06-25T14:01:52-03:00",
    "updated_at": "2020-06-25T14:01:52-03:00"
  }
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/invoices/[ID]

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador da cobrança

Retorno

Em caso de sucesso será retornado um objeto cobrança.

Listar cobranças

curl --location --request GET "https://api.cobrefacil.com.br/v1/invoices" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
  "success": true,
  "data": [
    {
      "id": "ZN8V0PD9W005WLRGQE5K",
      "reference": null,
      "payable_with": "bankslip",
      "due_date": "2020-12-15",
      "price": "89.98",
      "fine_delay": null,
      "total_paid": null,
      "amount_released": null,
      "fee": null,
      "paid_at": null,
      "payment_method": null,
      "document_number": "4604618",
      "url_receipt": null,
      "barcode": "34191090406046183893431339210002484700000008998",
      "barcode_data": null,
      "status": "pending",
      "customer": {
        "id": "Y73MNPGJ18Y18V5KQODX",
        "person_type": 1,
        "ein": null,
        "company_name": null,
        "taxpayer_id": "37673788250",
        "personal_name": "João da Silva",
        "telephone": "11988887777",
        "cellular": "11999999999",
        "email": "joao@cobrefacil.com.br",
        "email_cc": "maria@cobrefacil.com.br",
        "full_name": "João da Silva",
        "document": "37673788250",
        "created_at": "2020-06-25T14:01:40-03:00",
        "updated_at": "2020-06-25T14:01:41-03:00",
        "deleted_at": null
      },
      "settings": {
        "late_fee": null,
        "interest": null,
        "discount": null,
        "warning": null,
        "max_installments": null,
        "send_tax_invoice": 1
      },
      "url": "https://app.cobrefacil.com.br/minha-fatura/ZN8V0PD9W005WLRGQE5K",
      "created_at": "2020-06-25T14:01:52-03:00",
      "updated_at": "2020-06-25T14:01:54-03:00"
    }
  ]
}

Retorna uma lista paginada das cobranças existentes e os respectivos clientes.
É possível controlar a paginação e realizar buscas através de parâmetros na URL, exemplos:

Cobranças pagas em determinado período:
GET https://api.cobrefacil.com.br/v1/invoices?paid_at_start=2022-01-15&paid_at_end=2022-01-15

Cobranças com vencimento em determinado período:
GET https://api.cobrefacil.com.br/v1/invoices?due_date_start=2022-01-15&due_date_end=2022-01-15

Cobranças criadas em determinado período:
GET https://api.cobrefacil.com.br/v1/invoices?created_at_start=2022-01-15&created_at_end=2022-01-15

Cobranças atualizadas em determinado período:
GET https://api.cobrefacil.com.br/v1/invoices?updated_at_start=2022-01-15&updated_at_end=2022-01-15

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

HTTP Request

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

URL Parameters

Parâmetro Tipo Descrição
status String Informe os status que você deseja filtrar separados por ,
reference String Busca pelo código de referência utilizado para identificar a cobrança no seu sistema
payable_with String Busca pela forma de cobrança
payment_method String Busca pela forma de pagamento
due_date_start Date Retorna resultados quando due_date for igual ou maior a data informada
due_date_end Date Retorna resultados quando due_date for igual ou menor a data informada
paid_at_start Date Retorna resultados quando paid_at for igual ou maior a data informada
paid_at_end Date Retorna resultados quando paid_at for igual ou menor a data informada
created_at_start Date Retorna resultados quando created_at for igual ou maior a data informada, a data deve estar no formato YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
created_at_end Date Retorna resultados quando created_at for igual ou menor a data informada, a data deve estar no formato YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
taxpayer_id String Busca pelo CPF do cliente
ein String Busca pelo CNPJ da empresa
email String Busca pelo e-mail do cliente
personal_name String Busca pelo nome do cliente
company_name String Busca pelo nome da empresa
bad_credit Integer Define se devem ser retornados registros com ou sem negativação:
0 Cobranças sem negativação
1 Cobranças negativadas
sort_by String Campo a ser utilizado na ordenação, o padrão é created_at
order_by String Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc
limit Integer Quantidade máxima de registros que devem ser retornados, o padrão é 100
offset Integer Número de registros a serem pulados, o padrão é 0

Retorno

Em caso de sucesso será retornado um array de objetos cobrança.

Estornar cobrança via cartão

curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices/[ID]/refund" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
    \"amount\": 1000
}"

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
    "id": "OY4Q3NVG7VD759PRLD60",
    "reference": null,
    "payable_with": "credit",
    "due_date": "2020-06-25",
    "price": "89.98",
    "total_paid": "89.98",
    "amount_released": null,
    "fee": "3.85",
    "paid_at": "2020-06-25",
    "payment_method": "credit",
    "transaction_number": "Z133937-000260004",
    "url_receipt": null,
    "status": "refunded",
    "request_ip": "168.190.36.98",
    "capture": 0,
    "amount_refunded": "10.00",
    "installment": {
      "mode": "with_interest",
      "number": 3
    },
    "credit_card": {
      "id": "E65OPXNV9D59WM7JL402",
      "customer_id": "Z8J53ROD2JK1PQ47WG0E",
      "default": 1,
      "first6_digits": "453900",
      "last4_digits": "5497",
      "brand": "visa",
      "created_at": "2020-06-25T10:26:02-03:00",
      "updated_at": "2020-06-25T10:26:03-03:00",
      "deleted_at": null
    },
    "settings": {
      "send_tax_invoice": 1
    },
    "items": [
      {
        "description": "Teclado",
        "quantity": 1,
        "price": "49.99"
      },
      {
        "description": "Mouse",
        "quantity": 1,
        "price": "39.99"
      }
    ],
    "customer": {
      "id": "Z8J53ROD2JK1PQ47WG0E",
      "person_type": 1,
      "ein": null,
      "company_name": "COBRE FACIL LTDA ME",
      "taxpayer_id": "12345678909",
      "personal_name": "João da Silva",
      "telephone": "11988887777",
      "cellular": "11988887777",
      "email": "joao@cobrefacil.com.br",
      "email_cc": null,
      "address": {
        "id": "9W2LVGOPRJMR780DEJK1",
        "description": "Endereço principal",
        "zipcode": "01311100",
        "street": "Av Paulista",
        "number": "807",
        "complement": "A813 CJ 2315",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "created_at": "2020-06-25T10:26:02-03:00",
        "updated_at": "2020-06-25T10:26:02-03:00",
        "deleted_at": null
      },
      "full_name": "João da Silva",
      "document": "12345678909",
      "created_at": "2020-06-25T10:26:02-03:00",
      "updated_at": "2020-06-25T10:26:02-03:00",
      "deleted_at": null
    },
    "url": null,
    "created_at": "2020-06-25T13:59:40-03:00",
    "updated_at": "2020-06-25T14:06:19-03:00"
  }
}

É possível estornar o valor total de uma cobrança ou apenas parte dele. Quando uma cobrança é estornada seu status é alterado para refunded.

HTTP Request

POST https://api.cobrefacil.com.br/v1/invoices/[ID]/refund

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador da cobrança

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
amount Integer Não Valor a ser estornado em centavos, exemplo: R$ 42,90 deve ser informado como 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",
    "reference": null,
    "payable_with": "credit",
    "due_date": "2020-06-25",
    "price": "89.98",
    "total_paid": "89.98",
    "amount_released": null,
    "fee": "3.85",
    "paid_at": "2020-06-25",
    "payment_method": "credit",
    "transaction_number": "Z133937-000260004",
    "url_receipt": null,
    "status": "canceled",
    "request_ip": "168.190.36.98",
    "capture": 0,
    "amount_refunded": 10,
    "installment": {
      "mode": "with_interest",
      "number": 3
    },
    "credit_card": {
      "id": "E65OPXNV9D59WM7JL402",
      "customer_id": "Z8J53ROD2JK1PQ47WG0E",
      "default": 1,
      "first6_digits": "453900",
      "last4_digits": "5497",
      "brand": "visa",
      "expiration_year": "2021",
      "expiration_month": "12",
      "created_at": "2020-06-25T10:26:02-03:00",
      "updated_at": "2020-06-25T10:26:03-03:00",
      "deleted_at": null
    },
    "settings": {
      "send_tax_invoice": 1
    },
    "items": [
      {
        "description": "Teclado",
        "quantity": 1,
        "price": "49.99"
      },
      {
        "description": "Mouse",
        "quantity": 1,
        "price": "39.99"
      }
    ],
    "customer": {
      "id": "Z8J53ROD2JK1PQ47WG0E",
      "person_type": 1,
      "ein": null,
      "company_name": "COBRE FACIL LTDA ME",
      "taxpayer_id": "12345678909",
      "personal_name": "João da Silva",
      "telephone": "11988887777",
      "cellular": "11988887777",
      "email": "joao@cobrefacil.com.br",
      "email_cc": null,
      "address": {
        "id": "9W2LVGOPRJMR780DEJK1",
        "description": "Endereço principal",
        "zipcode": "01311100",
        "street": "Av Paulista",
        "number": "807",
        "complement": "A813 CJ 2315",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "created_at": "2020-06-25T10:26:02-03:00",
        "updated_at": "2020-06-25T10:26:02-03:00",
        "deleted_at": null
      },
      "full_name": "João da Silva",
      "document": "12345678909",
      "created_at": "2020-06-25T10:26:02-03:00",
      "updated_at": "2020-06-25T10:26:02-03:00",
      "deleted_at": null
    },
    "url": null,
    "created_at": "2020-06-25T13:59:40-03:00",
    "updated_at": "2020-06-25T14:08:55-03:00"
  }
}

Ao cancelar uma cobrança o status é alterado para canceled e a ação não pode ser desfeita.

No caso de cobranças via boleto, apenas as cobranças com status pending podem ser canceladas.
Cobranças via cartão podem ser canceladas quando tiver o status pending ou pre_authorized.

HTTP Request

DELETE https://api.cobrefacil.com.br/v1/invoices/[ID]

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador da cobrança

BODY Parameters

Parâmetro Tipo Obrigatório Descrição
cancel_tax_invoice Integer Não Cancela a nota fiscal relacionada à cobrança caso exista:
0 Não
1 Sim
O padrão é 0
cancel_tax_invoice_reason String Não Motivo do cancelamento da nota fiscal

Retorno

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

Gerar nota fiscal

O endpoint abaixo permite gerar nota fiscal para uma cobrança.

curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices/[ID]/tax-invoice" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
  "success": true,
  "data": {
{
  "id": "MVKLDOZJYK6Y0WXR8PQ2",
  "status": "processing",
  "created_at": "09/12/2022",
  "url": "https://api.cobrefacil.com.br/nota-fiscal/MVKLDOZJYK6Y0WXR8PQ2"
},
[...]
}
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/invoices/[ID]/tax-invoice

Retorno

Em caso de sucesso será retornado um array com informações básicas das notas fiscais geradas para essa cobrança.

Parâmetro Tipo Descrição
id String Identificador da cobrança
status String Status da nota fiscal
created_at String Data de criação da nota fiscal
url String URL da nota fiscal

Split de pagamentos

O split de pagamentos é utilizado para dividir o recebimento de uma cobrança em até mais dois recebedores, que também possuam uma conta Cobre Fácil ativa, tudo isso de forma automática.
Os endpoints para esse serviço são criar, atualizar, remover e listar split de pagamentos.
Quando a cobrança for paga o valor do líquido é dividido entre os recebedores, seguindo as regras cadastradas.

O objeto split de pagamento

Exemplo de JSON do objeto split de pagamento:

{
   "id": "O0QTKY8VNNOR5GXW7DLZ",
   "mode": "fixed",
   "amount": 10,
   "status": "pending",
   "document": "58267712080152" 
}
Atributo Tipo Descrição
id String Identificador do split de pagamento
mode String Modo que split de pagamento será calculado, pode ser:
percentage porcentagem sobre o valor total
fixed valor fixo. Para cada cobrança só será aceito uma modalidade.
amount Float Porcentagem ou valor do split de pagamento
status String Status do split de pagamento, pode ser:
pending o split de pagamento ainda não foi pago
paid o split de pagamento foi pago
document String CPF ou CNPJ do recebedor do split de pagamento

Criar split de pagamento

Ao criar uma regra de split de pagamento você estará adicionando um novo recebedor à cobrança já existente, lembrando que essa cobrança deve estar com status pendente para que possa ser adicionado a regra. Uma cobrança pode ter no máximo duas regras de split de pagamentos.

curl --location --request POST "https://api.cobrefacil.com.br/v1/invoices/[ID_INVOICE]/splits" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
   \"document\": \"58267712080152\",
   \"mode\": \"fixed\",
   \"amount\": 1000
}"

Exemplo de JSON retornado:

{
   "success": true,
   "data": {
       "id": "A41W8X23N78P3DZXJV974",
       "mode": "fixed",
       "document": "58267712080152",
       "amount": "10.00",
       "status": "pending"
   }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/invoices/[ID_INVOICE]/splits

Body Params

Atributo Tipo Obrigatório Descrição
document String Sim CPF ou CNPJ do recebedor do split de pagamento, devendo ser uma conta ativa na Cobre Fácil
mode String Sim Modo que split de pagamento será calculado, pode ser:
percentage porcentagem sobre o valor total
fixed valor fixo. Para cada cobrança só será aceito uma modalidade.
amount Integer Sim Porcentagem ou valor do split de pagamento, exemplo: 10,5% deve ser informado como 1050 ou quando valor R$ 10,90 deve ser informado como 1090

Retorno

Em caso de sucesso será retornado um o objeto split de pagamento.

Atualizar split de pagamento

Ao atualizar uma regra de split de pagamento são necessários todos os campos da criação mais o ID a ser informado no endpoint. Serão possíveis 20 atualizações por cobrança e somente serão aceitas se o status da cobrança for pendente pending.

curl --location --request PUT "https://api.cobrefacil.com.br/v1/invoices/[ID]/splits/[SPLIT_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
   \"document\": \"58267712080152\",
   \"mode\": \"fixed\",
   \"amount\": 2000
}"

Exemplo de JSON retornado:

{
   "success": true,
   "data": {
       "id": "A41W8X23N78P3DZXJV974",
       "mode": "fixed",
       "document": "58267712080152",
       "amount": "20.00",
       "status": "pending"
   }
}

HTTP Request

PUT https://api.cobrefacil.com.br/v1/invoices/[ID]/splits/[SPLIT_ID]

Body Params

Atributo Tipo Obrigatório Descrição
document String Sim CPF ou CNPJ do recebedor do split de pagamento, devendo ser uma conta ativa na Cobre Fácil
mode String Sim Modo que split de pagamento será calculado, pode ser:
percentage porcentagem sobre o valor total
fixed valor fixo. Para cada cobrança só será aceito uma modalidade.
amount Integer Sim Porcentagem ou valor do split de pagamento, exemplo: 10,5% deve ser informado como 1050 ou quando valor R$ 10,90 deve ser informado como 1090

Retorno

Em caso de sucesso será retornado um objeto split de pagamento.

Remover split de pagamento

A remoção da regra de split de pagamento deve ser feita somente informando o ID.

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/invoices/[ID]/splits/[SPLIT_ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \

Exemplo de JSON retornado:

{
   "success": true,
   "data": {
       "message": "Split removido com sucesso"
   }
}

HTTP Request

DELETE https://api.cobrefacil.com.br/v1/invoices/[ID]/splits/[SPLIT_ID

Retorno

Em caso de sucesso será retornada uma mensagem de split removido com sucesso.

Listar split de pagamento

curl --location --request GET "https://api.cobrefacil.com.br/v1/invoices/[ID]/splits" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
   "success": true,
   "data": [
       {
           "id": "105RK688N9OCZGXWQALZ",
           "mode": "fixed",
           "amount": "10.00",
           "document": "58267712080152"
       },
       {
           "id": "B0CW8XGLN75PADPQVV74",
           "mode": "fixed",
           "amount": "20.00",
           "document": "37673788250"
       }
   ]
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/invoices/[ID]/splits

Retorno

Em caso de sucesso será retornado um array de objetos split de pagamento.

Carnês de pagamento

Nossa API permite criar e cancelar seus carnês de pagamentos.
Você também pode detalhar carnês de pagamento individualmente ou listar carnês de pagamentos filtrando os atributos desejados. Em imprimir carnê de pagamento é gerado um pdf com todos os boletos de um carnê.

O objeto carnê de pagamento

Exemplo de JSON do objeto carnê de pagamento:

{
  "id": "XXXXXXXXXXXXXXXXXXXX",
  "customer": {
    "id": "XXXXXXXXXXXXXXXXXXXX",
    "address": {
      "id": "XXXXXXXXXXXXXXXXXXXX",
      "city": "São Paulo",
      "complement": "A813 CJ 2315",
      "description": "Endereço principal",
      "neighborhood": "Bela Vista",
      "number": "807",
      "state": "SP",
      "street": "Rua A",
      "zipcode": "01311000",
      "created_at": "2022-01-01 00:00:00",
      "updated_at": "2022-01-01 00:00:00"
    },
    "email_cc": "maria@cobrefacil.com.br",
    "cellular": "11988887777",
    "company_name": null,
    "document": "12345678909",
    "ein": null,
    "email": "joao@cobrefacil.com.br",
    "full_name": "João da Silva",
    "person_type": 1,
    "personal_name": "João da Silva",
    "taxpayer_id": "12345678909",
    "telephone": "11988887777",
    "created_at": "2022-01-01 00:00:00",
    "updated_at": "2022-01-01 00:00:00"
  },
  "reference": "XXXXXXXXXXXXXXXXXXXX",
  "first_due_date": "2022-01-01",
  "invoices": [
    {
      "id": "XXXXXXXXXXXXXXXXXXXX",
      "barcode": null,
      "barcode_data": null,
      "document_number": null,
      "due_date": "2022-01-01",
      "reference": "XXXXXXXXXXXXXXXXXXXX",
      "installment_number": 1,
      "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
      "paid_at": null,
      "payable_with": "bankslip",
      "payment_method": null,
      "price": "100.00",
      "sequencial_number": "COB00000001",
      "status": "pending",
      "total_paid": null,
      "url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX/boleto-impressao",
      "url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
      "url_receipt": null,
      "url_tax_invoice": null,
      "created_at": "2022-01-01 00:00:00",
      "updated_at": "2022-01-01 00:00:00"
    }
    ...
  ],
  "items": [
    {
      "description": "Produto 1",
      "price": "100.00",
      "quantity": 1
    },
  ],
  "last_due_date": "2022-04-01",
  "mode_installment": "installment_total",
  "number_installments": 4,
  "price_installments": "25.00",
  "price_total": "100.00",
  "sequencial_number": "CARNE00000001",
  "settings": {
    "discount": {
      "mode": "fixed",
      "limit_date": 1,
      "amount": "10.00"
    },
    "interest": {
      "mode": "monthly_percentage",
      "amount": "10.00"
    },
    "late_fee": {
      "mode": "percentage",
      "amount": "20.00"
    },
    "send_tax_invoice": 0,
    "warning": "Description"
  },
  "status": "pending",
  "created_at": "2022-01-01 00:00:00",
  "updated_at": "2022-01-01 00:00:00"
}
Atributo Tipo Descrição
id String Identificador do carnê de pagamento
customer Object Objeto cliente do carnê
reference String Código de referência utilizado para identificar o carnê no seu sistema
first_due_date Date Data da primeira cobrança do carnê de pagamento
invoices Array Array de objetos de cobrança
items Array Produtos ou serviços que estão sendo cobrados
items[].description String Descrição do item
items[].quantity String Quantidade cobrada do item
items[].price Float Valor unitário do item
last_due_date Date Data da última cobrança do carnê de pagamento
mode_installment String Quando informado installment_value o valor de cada parcela será valor total dos items informados, já no caso installment_total valor total dos items será dividido pelo número de parcelas
number_installments Integer Número de parcelas
price_installments Float Valor total de cada parcela
price_total Float Valor total somando todas as parcelas
settings Object Configurações da cobrança. OBS: utilizado apenas por cobranças do tipo bankslip e all
settings.late_fee Object Multa por atraso
settings.late_fee.mode String Modo que a multa por atraso será calculada, pode ser:
percentage porcentagem sobre o valor 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
settings.warning String Mensagem exibida no campo instruções do boleto
settings.max_installments Integer Máximo de parcelas que o cliente pode escolher ao realizar um pagamento via cartão de crédito
settings.send_tax_invoice Integer Momento em que a nota fiscal deve ser gerada:
0 não deve gerar nota fiscal
1 a nota fiscal deve ser gerada após confirmação do pagamento
2 a nota fiscal deve ser gerada após a criação da cobrança
OBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal
status String Status do carnê podendo ser: pending, paid ou canceled
created_at DateTime Data que o carnê de pagamento foi criado
updated_at DateTime Data que o carnê de pagamento foi atualizado

Criar carnê de pagamento

Endpoint destinado a criação de carnê de pagamento via parâmetros. Caso o valor total dividido pelo número de parcelas não for exato, exemplo R$ 100,00 em 3 parcelas (resultado 100/3 = 33,3333..), a primeira parcela fará o compensamento da divisão para acerto do valor, ficando primeira parcela de R$ 33,34 e as outras duas de R$ 33,33 totalizando os R$ 100,00.

curl --location --request POST "https://api.cobrefacil.com.br/v1/payment-booklets" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]" \
--data "{
{
  \"customer_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
  \"customer_address_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
  \"reference\": \"XXXXXXXXXXXXXXXXXXXX\"
  \"first_due_date\" : \"2022-01-01\",
  \"items\" : [
      {
          \"price\" : 10000,
          \"description\" : \"Produto 1\"
      },
      {
          \"price\" : 2060,
          \"description\" : \"Produto 2\"
      }
  ],
  \"notification_rule_id\" : \"XXXXXXXXXXXXXXXXXXXX\",
  \"number_installments\" : 6,
  \"mode_installment\" : \"installment_total\",
  \"settings\" : {
        \"late_fee\"         : {
            \"mode\"   : \"percentage\",
            \"amount\" : 500
        },
        \"interest\"         : {
            \"mode\"   : \"monthly_percentage\",
            \"amount\" : 520
        },
        \"discount\"         : {
            \"mode\"       : \"percentage\",
            \"amount\"     : 1020,
            \"limit_date\" : 1
        },
        \"warning\"          : {
            \"description\" : \"Description\"
        }
    }
}

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "XXXXXXXXXXXXXXXXXXXX",
        "customer": {
            "id": "XXXXXXXXXXXXXXXXXXXX",
            "address": {
                "id": "XXXXXXXXXXXXXXXXXXXX",
                "city": "São Paulo",
                "complement": "A813 CJ 2315",
                "description": "Endereço principal",
                "neighborhood": "Bela Vista",
                "number": "807",
                "state": "SP",
                "street": "Rua A",
                "zipcode": "01311000",
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            },
      "email_cc": "maria@cobrefacil.com.br",
      "cellular": "11988887777",
      "company_name": null,
      "document": "12345678909",
      "ein": null,
      "email": "joao@cobrefacil.com.br",
      "full_name": "João da Silva",
      "person_type": 1,
      "personal_name": "João da Silva",
      "taxpayer_id": "12345678909",
      "telephone": "11988887777",
            "created_at": "2022-01-01 00:00:00",
            "updated_at": "2022-01-01 00:00:00"
        },
        "reference": "XXXXXXXXXXXXXXXXXXXX",
        "first_due_date": "2022-01-01",
        "invoices": [
            {
                "id": "XXXXXXXXXXXXXXXXXXXX",
                "barcode": null,
                "barcode_data": null,
                "document_number": null,
                "due_date": "2022-01-01",
                "reference": "XXXXXXXXXXXXXXXXXXXX",
                "installment_number": 1,
                "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
                "paid_at": null,
                "payable_with": "bankslip",
                "payment_method": null,
                "price": "100.00",
                "sequencial_number": "COB00000001",
                "status": "pending",
                "total_paid": null,
                "url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX/boleto-impressao",
                "url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
                "url_receipt": null,
                "url_tax_invoice": null,
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
      ...
    ],
        "items": [
            {
                "description": "Produto 1",
                "price": "100.00",
                "quantity": 1
            },
        ],
        "last_due_date": "2022-04-01",
        "mode_installment": "installment_total",
        "number_installments": 4,
        "price_installments": "25.00",
        "price_total": "100.00",
        "sequencial_number": "CARNE00000001",
    "settings": {
      "discount": {
        "mode": "fixed",
        "limit_date": 1,
        "amount": "10.20"
      },
      "interest": {
        "mode": "monthly_percentage",
        "amount": "10.00"
      },
      "late_fee": {
        "mode": "percentage",
        "amount": "20.00"
      },
      "send_tax_invoice": 0,
      "warning": "Description"
    },
        "status": "pending",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

HTTP Request

POST https://api.cobrefacil.com.br/v1/payment-booklets

Body Params

Parâmetro Tipo Obrigatório Descrição
customer_id String Sim Identificador do cliente
customer_address_id String Não Identificador do endereço do cliente
reference String Não Código de referência utilizado para identificar o carnê no seu sistema
first_due_date Date Sim Data da primeira cobrança do carnê de pagamento
items.*.description String Sim Descrição do produto ou serviço
items.*.price Integer Sim preço do item, lembrando que o formato é inteiro. Exemplo: R$100,00 (cem reais) seria 10000
notification_rule_id String Sim Identificador da régua de cobrança
number_installments Integer Sim Número de parcelas do carnê de pagamento
settings Object Não Configurações da cobrança
settings.late_fee Object Não Multa por atraso
settings.late_fee.mode String Quando settings.late_fee for informado Modo que a multa por atraso será calculada, pode ser:
percentage porcentagem sobre o valor 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
settings.warning Object Não Instruções gerais sobre o pagamento
settings.warning.description String Quando settings.warning for informado Mensagem contendo instruções gerais sobre o pagamento
settings.send_tax_invoice Integer Não Momento em que a nota fiscal deve ser gerada:
0 não deve gerar nota fiscal
1 a nota fiscal deve ser gerada após confirmação do pagamento
2 a nota fiscal deve ser gerada após a criação da cobrança
OBS: a função de nota fiscal deve estar habilitada, se nenhum valor for informado será utilizado o definido na tela de configuração da nota fiscal

Retorno

Em caso de sucesso será retornado um objeto carnê de pagamento.

Detalhar carnê de pagamento

curl --location --request GET "https://api.cobrefacil.com.br/v1/payment-booklets/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "XXXXXXXXXXXXXXXXXXXX",
        "customer": {
            "id": "XXXXXXXXXXXXXXXXXXXX",
            "address": {
                "id": "XXXXXXXXXXXXXXXXXXXX",
                "city": "São Paulo",
                "complement": "A813 CJ 2315",
                "description": "Endereço principal",
                "neighborhood": "Bela Vista",
                "number": "807",
                "state": "SP",
                "street": "Rua A",
                "zipcode": "01311000",
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            },
      "email_cc": "maria@cobrefacil.com.br",
      "cellular": "11988887777",
      "company_name": null,
      "document": "12345678909",
      "ein": null,
      "email": "joao@cobrefacil.com.br",
      "full_name": "João da Silva",
      "person_type": 1,
      "personal_name": "João da Silva",
      "taxpayer_id": "12345678909",
      "telephone": "11988887777",
            "created_at": "2022-01-01 00:00:00",
            "updated_at": "2022-01-01 00:00:00"
        },
        "reference": "XXXXXXXXXXXXXXXXXXXX",
        "first_due_date": "2022-01-01",
        "invoices": [
            {
                "id": "XXXXXXXXXXXXXXXXXXXX",
                "barcode": null,
                "barcode_data": null,
                "document_number": null,
                "due_date": "2022-01-01",
                "reference": "XXXXXXXXXXXXXXXXXXXX",
                "installment_number": 1,
                "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
                "paid_at": null,
                "payable_with": "bankslip",
                "payment_method": null,
                "price": "100.00",
                "sequencial_number": "COB00000001",
                "status": "pending",
                "total_paid": null,
                "url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX/boleto-impressao",
                "url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
                "url_receipt": null,
                "url_tax_invoice": null,
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
      ...
    ],
        "items": [
            {
                "description": "Produto 1",
                "price": "100.00",
                "quantity": 1
            },
        ],
        "last_due_date": "2022-04-01",
        "mode_installment": "installment_total",
        "number_installments": 4,
        "price_installments": "25.00",
        "price_total": "100.00",
        "sequencial_number": "CARNE00000001",
    "settings": {
      "discount": {
        "mode": "fixed",
        "limit_date": 1,
        "amount": "10.20"
      },
      "interest": {
        "mode": "monthly_percentage",
        "amount": "10.00"
      },
      "late_fee": {
        "mode": "percentage",
        "amount": "20.00"
      },
      "send_tax_invoice": 0,
      "warning": "Description"
    },
        "status": "pending",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

Para detalhar um carnê de pagamento específico basta informar o ID retornado no momento da criação.

HTTP Request

GET https://api.cobrefacil.com.br/v1/payment-booklets/[ID]

Retorno

Em caso de sucesso será retornado um objeto carnê de pagamento.

Listar carnê de pagamentos

curl --location --request GET "https://api.cobrefacil.com.br/v1/payment-booklets" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": [
        {
            "id": "XXXXXXXXXXXXXXXXXXXX",
            "customer_address_id": "XXXXXXXXXXXXXXXXXXXX",
            "customer_id": "XXXXXXXXXXXXXXXXXXXX",
            "first_due_date": "2022-01-01",
            "last_due_date": "2022-06-01",
            "mode_installment": "installment_total",
            "number_installments": 6,
            "price_installments": 20.1,
            "price_total": 120.6,
            "status": "pending",
      "created_at": "2022-01-01 00:00:00",
            "updated_at": "2022-01-01 00:00:00"
        }
    ],
    "pagination": {
        "total_records": 1,
        "display_records": 1
    }
}

Retorna uma lista paginada de carnê de pagamentos.
É possível controlar a paginação e realizar buscas através de parâmetros na URL, exemplos:

Buscar carnê-de-pagamento pelo status:
GET https://api.cobrefacil.com.br/v1/payment-booklets?status=pending

Buscar carnê-de-pagamento pelo reference:
GET https://api.cobrefacil.com.br/v1/payment-booklets?reference=XXXXXXXXXXXXXXXXXXXX

Retornar 10 registros pulando os 10 primeiros:
GET https://api.cobrefacil.com.br/v1/payment-booklets?limit=10&offset=10

HTTP Request

GET https://api.cobrefacil.com.br/v1/payment-booklets

URL Parameters

Parâmetro Tipo Descrição
customer_id String Busca pelo ID do cliente
customer_query String Busca por documento (CPF/CNPJ), email ou nome do cliente
reference String Busca pelo ID externo do carnê de pagamento
status String Busca pelo status do carnê de pagamento
sort_by String Campo a ser utilizado na ordenação, o padrão é created_at
order_by String Define se a listagem será retornada de forma crescente ou decrescente asc ou desc, o padrão é desc
limit Integer Quantidade máxima de registros que devem ser retornados, o padrão é 100
offset Integer Número de registros a serem pulados, o padrão é 0

Retorno

Atributo Tipo Descrição
id String Identificador do carnê de pagamento
customer_id String Identificador do cliente
customer_address_id String Identificador do endereço do cliente
reference String Código de referência utilizado para identificar o carnê no seu sistema
first_due_date Date Data da primeira cobrança do carnê de pagamento
last_due_date Date Data da última cobrança do carnê de pagamento
mode_installment String Quando informado installment_value o valor de cada parcela será valor total dos items informados, já no caso installment_total valor total dos items será dividido pelo número de parcelas
number_installments Integer Número de parcelas
price_installments Float Valor total de cada parcela
price_total Float Valor total somando todas as parcelas
status String Status do carnê podendo ser: pending, paid ou canceled
created_at DateTime Data que o carnê de pagamento foi criado
updated_at DateTime Data que o carnê de pagamento foi atualizado

Cancelar carnê de pagamento

curl --location --req
POST "https://api.cobrefacil.com.br/v1/payment-booklets/[ID]/cancel" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "XXXXXXXXXXXXXXXXXXXX",
        "customer": {
            "id": "XXXXXXXXXXXXXXXXXXXX",
            "address": {
                "id": "XXXXXXXXXXXXXXXXXXXX",
                "city": "São Paulo",
                "complement": "A813 CJ 2315",
                "description": "Endereço principal",
                "neighborhood": "Bela Vista",
                "number": "807",
                "state": "SP",
                "street": "Rua A",
                "zipcode": "01311000",
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            },
      "email_cc": "maria@cobrefacil.com.br",
      "cellular": "11988887777",
      "company_name": null,
      "document": "12345678909",
      "ein": null,
      "email": "joao@cobrefacil.com.br",
      "full_name": "João da Silva",
      "person_type": 1,
      "personal_name": "João da Silva",
      "taxpayer_id": "12345678909",
      "telephone": "11988887777",
            "created_at": "2022-01-01 00:00:00",
            "updated_at": "2022-01-01 00:00:00"
        },
        "reference": "XXXXXXXXXXXXXXXXXXXX",
        "first_due_date": "2022-01-01",
        "invoices": [
            {
                "id": "XXXXXXXXXXXXXXXXXXXX",
                "barcode": null,
                "barcode_data": null,
                "document_number": null,
                "due_date": "2022-01-01",
                "reference": "XXXXXXXXXXXXXXXXXXXX",
                "installment_number": 1,
                "notification_rule_id": "XXXXXXXXXXXXXXXXXXXX",
                "paid_at": null,
                "payable_with": "bankslip",
                "payment_method": null,
                "price": "100.00",
                "sequencial_number": "COB00000001",
                "status": "canceled",
                "total_paid": null,
                "url_bankslip": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX/boleto-impressao",
                "url_invoice": "https://app.cobrefacil.com.br/minha-fatura/XXXXXXXXXXXXXXXXXXXX",
                "url_receipt": null,
                "url_tax_invoice": null,
                "created_at": "2022-01-01 00:00:00",
                "updated_at": "2022-01-01 00:00:00"
            }
      ...
    ],
        "items": [
            {
                "description": "Produto 1",
                "price": "100.00",
                "quantity": 1
            },
        ],
        "last_due_date": "2022-04-01",
        "mode_installment": "installment_total",
        "number_installments": 4,
        "price_installments": "25.00",
        "price_total": "100.00",
        "sequencial_number": "CARNE00000001",
    "settings": {
      "discount": {
        "mode": "fixed",
        "limit_date": 1,
        "amount": "10.20"
      },
      "interest": {
        "mode": "monthly_percentage",
        "amount": "10.00"
      },
      "late_fee": {
        "mode": "percentage",
        "amount": "20.00"
      },
      "send_tax_invoice": 0,
      "warning": "Description"
    },
        "status": "canceled",
        "created_at": "2022-01-01 00:00:00",
        "updated_at": "2022-01-01 00:00:00"
    }
}

Ao cancelar um carnê de pagamento todas as cobranças em atraso e em aberto seram canceladas. .

HTTP Request

POST https://api.cobrefacil.com.br/v1/payment-booklets/[ID]/cancel

Retorno

Em caso de sucesso será retornado um objeto carnê de pagamento com os dados atualizados.

Imprimir carnê de pagamento

curl --location --req
POST "https://api.cobrefacil.com.br/v1/payment-booklets/[ID]/cancel" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]"

O endpoint é utilizado para fazer o download do PDF contendo os boletos do carnês de pagamento, sendo 3 por página. .

HTTP Request

GET https://api.cobrefacil.com.br/v1/payment-booklets/[ID]/pdf

Retorno

Em caso de sucesso será retornado arquivo PDF com todos os boletos do carnê solicitado.

Recebíveis

Um recebível é criado quando uma cobrança via cartão de crédito é aprovada, nesse momento é identificado o quanto será recebido pela transação e quando o valor estará disponível no saldo de sua conta.

É possível listar os recebíveis por cobrança ou detalhar individualmente.

O objeto recebível

Exemplo de JSON do objeto recebível:

{
    "id": "P28EM9YZL87J4KV6GO0R",
    "invoice_id": "K2M5P46E7DJ710LG9ZRJ",
    "installment": 1,
    "status": "paid",
    "amount": "21.76",
    "gross_amount": "22.67",
    "anticipation_fee": "0.00",
    "fee": "0.91",
    "expected_on": "2020-08-31",
    "paid_at": "2020-07-29",
    "canceled_at": null,
    "created_at": "2020-07-30T16:21:48-03:00",
    "updated_at": "2020-07-30T16:29:31-03:00"
}
Atributo Tipo Descrição
id String Identificador do recebível
invoice_id String Identificador da cobrança
installment Integer Número da parcela a ser paga
status String Status atual do recebível, pode ser:
pending o recebível foi agendado para ser pago
paid o recebível foi creditado no saldo da conta
canceled o recebível foi cancelado e não será creditado no saldo da conta
refunded o recebível foi estornado após o pagamento e o valor líquido será debitado do saldo
amount Float Valor líquido a receber
gross_amount Float Valor bruto do recebível
anticipation_fee Float Tarifa cobrada ao antecipar o recebimento das parcelas
fee Float Tarifa da Cobre Fácil
expected_on Date Data esperada de crédito do recebível
paid_at Date Data que o recebível foi pago
canceled_at Date Data que o recebível foi cancelado
created_at DateTime Data que o recebível foi criado
updated_at DateTime Data que o recebível foi atualizado

Listar recebíveis por cobrança

Para listar os recebíveis de uma cobrança basta fornecer o identificador da cobrança.

curl --location --request GET "https://api.cobrefacil.com.br/v1/invoices/[ID]/receivables" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Exemplo de JSON retornado:

{
    "success": true,
    "data": [
        {
            "id": "P28EM9YZL87J4KV6GO0R",
            "invoice_id": "K2M5P46E7DJ710LG9ZRJ",
            "installment": 1,
            "status": "paid",
            "amount": "21.76",
            "gross_amount": "22.67",
            "anticipation_fee": "0.00",
            "fee": "0.91",
            "expected_on": "2020-08-31",
            "paid_at": "2020-07-29",
            "canceled_at": null,
            "created_at": "2020-07-30T16:21:48-03:00",
            "updated_at": "2020-07-30T16:29:31-03:00"
        },
        {
            "id": "Q2GZX4WYJZ8169VD85P7",
            "invoice_id": "K2M5P46E7DJ710LG9ZRJ",
            "installment": 2,
            "status": "pending",
            "amount": "21.76",
            "gross_amount": "22.67",
            "anticipation_fee": "0.00",
            "fee": "0.91",
            "expected_on": "2020-09-30",
            "paid_at": null,
            "canceled_at": null,
            "created_at": "2020-07-30T16:21:48-03:00",
            "updated_at": "2020-07-30T16:21:48-03:00"
        },
        {
            "id": "GZ4PMN0YJ28JR58D67X2",
            "invoice_id": "K2M5P46E7DJ710LG9ZRJ",
            "installment": 3,
            "status": "pending",
            "amount": "21.78",
            "gross_amount": "22.67",
            "anticipation_fee": "0.00",
            "fee": "0.89",
            "expected_on": "2020-10-30",
            "paid_at": null,
            "canceled_at": null,
            "created_at": "2020-07-30T16:21:48-03:00",
            "updated_at": "2020-07-30T16:21:48-03:00"
        }
    ]
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/invoices/[ID]/receivables

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador da cobrança

Retorno

Em caso de sucesso será retornado um objeto recebível.

Detalhar recebível

curl --location --request GET "https://api.cobrefacil.com.br/v1/receivables/[ID]" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [TOKEN]

Para detalhar um recebível basta fornecer o identificador dele.

Exemplo de JSON retornado:

{
    "success": true,
    "data": {
        "id": "P28EM9YZL87J4KV6GO0R",
        "invoice_id": "K2M5P46E7DJ710LG9ZRJ",
        "installment": 1,
        "status": "paid",
        "amount": "21.76",
        "gross_amount": "22.67",
        "anticipation_fee": "0.00",
        "fee": "0.91",
        "expected_on": "2020-08-31",
        "paid_at": "2020-07-29",
        "canceled_at": null,
        "created_at": "2020-07-30T16:21:48-03:00",
        "updated_at": "2020-07-30T16:29:31-03:00"
    }
}

HTTP Request

GET https://api.cobrefacil.com.br/v1/receivables/[ID]

URL Parameters

Parâmetro Tipo Obrigatório Descrição
id String Sim Identificador do recebível

Retorno

Em caso de sucesso será retornado um objeto recebível.

Notas fiscais (NFS-e)

A API da Cobre Fácil permite a emissão de NFS-e de forma simples e rápida. Para isso, é necessário que o cliente tenha a configuração de notas fiscais feita corretamente e que o município esteja homologado para emissão de notas fiscais via webservice.

O objeto da nota simplificado

Atributo Tipo Descrição
id string Identificador da nota
reference string Referência da cobrança, exemplo: COB0001 ou Avulsa quando não houver uma cobrança associada
number string Número da nota
customer_name string Nome do cliente
status string Status da nota
status_cancellation string Status do cancelamento da nota
created_at string Data de criação da nota
url string URL para visualização da nota

O objeto da nota

Atributo Tipo Descrição
id Integer Identificador da nota
status String Status da nota
status_cancellation String Status do cancelamento da nota
amount Float Valor do serviço prestado
rps_series String Série do RPS
rps_lot Integer Lote do RPS
rps_number Integer Número do RPS
number String Número da nota
note Text Observação da nota
cancellation_reason Text Motivo do cancelamento da nota
error_message Text Mensagem de erro
customer_id String Identificador do cliente
invoice_id String Identificador da cobrança
url_tax_invoice String URL da nota
services Array Array com os serviços prestados
services.code String Código do serviço prestado
services.service_code_taxation String Código de tributação do serviço prestado
services.description String Descrição do serviço prestado
services.quantity Integer Quantidade do serviço prestado
services.price Float Valor do serviço prestado
services.iss_aliquot Float Alíquota do ISS
services.cnae String CNAE do serviço prestado
created_at String Data de criação da nota no formato YYYY-MM-DD
canceled_at String Data de cancelamento da nota no formato YYYY-MM-DD

Status da nota

Status da nota Descrição
processing A nota está sendo processada
active A nota foi emitida com sucesso
rejected A nota foi rejeitada
canceled A nota foi cancelada

Status cancelamento da nota

Status da nota Descrição
waiting A nota está aguardando o cancelamento
success A nota foi cancelada com sucesso
rejected O cancelamento foi rejeitado pelo provedor, a nota retorna para o status active

Criar uma NFS-e avulsa

Para criar uma NFS-e avulsa, sem um cobrança atrelada, é necessário informar os dados do tomador, itens, valor e demais informações da nota. O exemplo abaixo mostra como criar uma NFS-e com os dados mínimos necessários.

curl --location --request POST "https://api.cobrefacil.com.br/v1/tax-invoices" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \

HTTP Request

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

Body Params

Atributo Tipo Obrigatório Descrição
note String Não Descrição da nota fiscal
customer_id String Sim ID do cliente
plans_id Integer Sim* IDs do plano
items Array Sim* Array de itens da nota fiscal
items[].product_service_id String Sim ID do produto ou serviço
items[].description String Não Quantidade do item
items[].quantity Integer Não Quantidade do item, se não informado será 1
items[].price Integer Não Valor unitário do item em centavos
exemplo: R$ 42,90 deve ser informado como 4290, caso não informado será considerado o valor do produto ou serviço

Retorno

Em caso de sucesso será retornado um o objeto da nota.

Listar notas

curl --location --request GET "https://api.cobrefacil.com.br/v1/tax-invoices" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \

HTTP Request

GET https://api.cobrefacil.com.br/v1/tax-invoices

Retorno

Em caso de sucesso será retornado um array com os objetos das notas (simplificado).

Obter uma nota

curl --location --request GET "https://api.cobrefacil.com.br/v1/tax-invoices/{ID}" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \

HTTP Request

GET https://api.cobrefacil.com.br/v1/tax-invoices/{ID}

Retorno

Em caso de sucesso será retornado um o objeto da nota.

Cancelar uma nota

O cancelamento de uma nota é feito através do endpoint de notas, informando o ID da nota que deseja cancelar. Cada prefeitura possui suas regras para cancelamento de notas, por isso é importante verificar as regras da prefeitura antes de realizar o cancelamento.

curl --location --request DELETE "https://api.cobrefacil.com.br/v1/tax-invoices/{ID}" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \

Body Params

Atributo Tipo Obrigatório Descrição
reason String Não Motivo do cancelamento

HTTP Request

DELETE https://api.cobrefacil.com.br/v1/tax-invoices/{ID}

Retorno

Em caso de sucesso será retornado um o objeto da nota.

Reenviar uma nota

O reenvio de uma nota é feito através do endpoint de notas, informando o ID da nota que deseja reenviar. Deve ser utilizado em caso de mudanças nas configurações de envio de notas ou de certificado digital.

curl --location --request POST "https://api.cobrefacil.com.br/v1/tax-invoices/{ID}/retry" \
--header "Content-Type: application" \
--header "Authorization: Bearer [TOKEN]" \

HTTP Request

POST https://api.cobrefacil.com.br/v1/tax-invoices/{ID}/retry

Retorno

Em caso de sucesso será retornado uma mensagem Nota fiscal reenviada com sucesso! ou erros se possuir.