Documentação API Cobrando

Introdução Documentation Api Version 1.0

Aqui você encontra todas as requisições necessárias para interegir com o Cobrando via API. Podendo conectar seus sistemas e soluções a tecnologia Cobrando.

A nossas API/WebHook adota a especificação RESTFul (Representational State Tranfer), o que significa que elas não armazenam estado. Sendo assim, cada chamada é completamente independente das demais. Uma API REST, na prática, detém vantagens sobre as metodologias definidas pelo protocolo HTTP, como por exemplo, a utilização dos verbos já especificados para a representação das ações a serem executadas sobre os recursos.

Tecnologias e Padrões

REST

Arquitetura para a disponibilização de recursos através de sistemas distribuídos, popularmente utilizado sobre o protocolo HTTP. Mais detalhes em: https://www.w3.org/2001/sw/wiki/REST.

JSON

Padrão para descrição de dados utilizado para intercâmbio de informações entre sistemas, é mais simples e leve do que algumas alternativas de mercado, como XML. Mais detalhes em: https://www.w3.org/TR/html-json-forms/#introduction.

HTTP 1.1

Protocolo de transporte padrão, amplamente utilizado. Mais detalhes em: http://www.w3.org/Protocols/rfc2616/rfc2616.html ou http://www.ietf.org/rfc/rfc2616.txt.

UTF-8

Conjunto de caracteres padrão para comunicação entre sistemas distribuidos. Mais detalhes em: https://www.w3.org/International/questions/qa-choosing-encodings.

Endpoint

Para ter acesso a nossa api, utilize o endpoint abaixo:

https:// https://api.cobrando.com.br

Autenticação

Para autenticar na api, deverá ser enviado por no body, os dados configurados no seu painel de controle Cobrando, para o endpoint de Gerar Token, você receberá o Response do token no parâmetro access_token que deverá ser utilizado para as demais requisições da API.

Para ter acesso às credenciais de geração do access_token, acesse as configurações no seu painel Cobrando.

Todas as informações trafegadas pelas APIs deverão realizadas através do protocolo HTTPS, que garante um canal é seguro e dispensa a criptografia dos tokens de forma manual.


O que é Autenticação Bearer?

A Autenticação Bearer é um mecanismo simples e eficiente para autenticar solicitações HTTP. Neste método, o token de acesso (também conhecido como token Bearer) é incluído no cabeçalho da solicitação HTTP. Esse token serve como uma credencial de acesso, permitindo que o servidor autentique o usuário ou aplicativo que está fazendo a solicitação.

Como Utilizar a Autenticação Bearer

Para autenticar suas solicitações à nossa API usando o método Bearer, siga estas etapas:

  • Obtenha um Token de Acesso:
    • Faça uma solicitação de autenticação ao endpoint apropriado, fornecendo suas credenciais. O servidor retornará um token de acesso válido que terá validade de 25 horas. Inclua o Token no Cabeçalho da Solicitação:
  • Adicione o token de acesso ao cabeçalho Authorization de suas solicitações HTTP.
    • O formato do cabeçalho é: Authorization: Bearer SeuTokenAqui.
  • Envie a Solicitação:
    • Com o token incluído no cabeçalho, envie sua solicitação normalmente.

Controle de acesso

Aqui você poderá gerar o access_token, que terá a finalidade de autenticação nas demais requisições da API.

Gegar Token (access_token)

Request (body){
	"username": "[email protected]",
	"password": "sua_senha",
	"token_generate": "$tkn_token_gerado_no_painel"
}


								
Código 200 (Success){
	"status": "success",
	"code": 200,
	"message": "Token gerado com sucesso",
	"document": {
		"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvYXBpLmNvYnJhbmRv...",
		"expires_in_timestamp": 1703088302,
		"expires_in_date": "20/12/2023 13:05:02",
		"token_type": "bearer"
	}
}


Código 400 (BAD_REQUEST){
	"status": "error",
	"code": 400,
	"message": "Erro no sistema, contate o administrador",
	"document": null
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 400,
	"message": "Login ou senha inválidos",
	"document": null
}

Validar Token (access_token)

Request (body)
										Somente autenticação necessária.
									
Código 200 (Success){
	"status": "success",
	"code": 200,
	"message": "Token válido",
	"document": null
}


Código 401 (BAD_REQUEST){
	"status": "error",
	"code": 401,
	"message": "Token inválido",
	"document": "Verifique as configurações de autenticação"
}


Código 403 (UNAUTHORIZED){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}

Clientes

Gestão dos clientes no sistema.

Listar clientes cadastrados

Lista de todos os clientes da conta.

Request (body)
										Somente autenticação necessária.
{paginanumero} (params) - Número da pagina atual, normalmente 1
{porpagina} (params) - Resultados por pagina
									
Código 200 (Success){
	"status": "success",
	"code": 200,
	"message": "Clientes localizados",
	"document": {
		"pageno": "1",
		"pagesize": "30",
		"total_count": "2",
		"clientes": [
			{
				"objeto": "customer",
				"idCliente": "0232569856325",
				"nome": "NOME DO CLIENTE 1",
				"email": "[email protected]",
				"telefone": "119656560000",
				"celular": "119656560000",
				"endereco": "RUA PIAUI",
				"numero": "498",
				"complemento": "Casa",
				"bairro": "JARDIM MINÓPOLIS",
				"cep": "78000000",
				"cpfCnpj": "00000011111",
				"inscricaoMunicipal": "123456",
				"referenciaPropria": "123456",
				"estado": "SP",
				"cidade": "São Paulo",
				"dataInsert": "2023-09-22 12:15:21"
			},
			{
				"objeto": "customer",
				"idCliente": "589658745",
				"nome": "NOME DO CLEINTE 2",
				"email": "[email protected]",
				"telefone": "1196565611111",
				"celular": "1196565611111",
				"endereco": "Rua das Flores",
				"numero": "131",
				"complemento": "Casa",
				"bairro": "Bairro do cliente 2",
				"cep": "78000000",
				"cpfCnpj": "00000000000",
				"inscricaoMunicipal": "123456",
				"referenciaPropria": "pm_656a1cc62ae838",
				"estado": "SP",
				"cidade": "São Paulo",
				"dataInsert": "2023-12-01 14:49:59"
			}
		]
	}
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 404 (NOT_FOUND){
	"status": "error",
	"code": 404,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 405 (METHOD_NOT_ALLOWED){
	"status": "error",
	"code": 405,
	"message": "Método não aceito, utilize GET em vez do método utilizado",
	"document": null
}

Buscar clientes

A busca pelo cliente é efetuada pelo id, nome, e-mail, telefone, endereço, bairro, cep ou CPF/CNPJ. 

Request (body)
									Somente autenticação necessária.
{termo_de_busca} (params) - termo de busca
								
Código 200 (Success){
	"status": "success",
	"code": 1,
	"message": "clientes localizados",
	"document": {
		"pageno": "1",
		"pagesize": "30",
		"total_count": "2",
		"clientes": [
			{
				"objeto": "cliente",
				"idCliente": 0232569856325,
				"nome": "NOME DO CLIENTE",
				"email": "[email protected]",
				"telefone": "119656560000",
				"celular": "119656560000",
				"endereco": "RUA PIAUI",
				"numero": "498",
				"complemento": "Casa",
				"bairro": "CENTRO",
				"cep": "78000000",
				"cpfCnpj": "00000011111",
				"inscricaoMunicipal": "123456",
				"referenciaPropria": "pm_6584d8b0467598",
				"estado": "SP",
				"cidade": "São Paulo",
				"tipoPessoa": "FISICA",
				"observacoes": "123456",
				"dataInsert": "2023-09-22"
			},
			{
				"objeto": "cliente",
				"idCliente": 0232569856325,
				"nome": "NOME DO CLIENTE",
				"email": "[email protected]",
				"telefone": "119656560000",
				"celular": "119656560000",
				"endereco": "RUA PIAUI",
				"numero": "498",
				"complemento": "Casa",
				"bairro": "CENTRO",
				"cep": "78000000",
				"cpfCnpj": "00000011111",
				"inscricaoMunicipal": "123456",
				"referenciaPropria": "pm_6584d8b0467598",
				"estado": "SP",
				"cidade": "São Paulo",
				"tipoPessoa": "FISICA",
				"observacoes": "123456",
				"dataInsert": "2023-09-22"
			}
		]
	}
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 404 (NOT_FOUND){
	"status": "error",
	"code": 404,
	"message": "Nenhum cliente localizado",
	"document": null
}


Código 405 (METHOD_NOT_ALLOWED){
	"status": "error",
	"code": 405,
	"message": "Método não aceito, utilize GET em vez do método utilizado",
	"document": null
}

Dados de um único cliente

Request (body)
									Somente autenticação necessária.
{id_cliente} (path) - ID do cliente
								
Código 200 (Success){
	"status": "success",
	"code": 200,
	"message": "cliente localizado",
	"document": {
		"objeto": "cliente",
		"idCliente": 0232569856325,
		"nome": "NOME DO CLIENTE",
		"email": "[email protected]",
		"telefone": "119656560000",
		"celular": "119656560000",
		"endereco": "RUA PIAUI",
		"numero": "498",
		"complemento": "Casa",
		"bairro": "CENTRO",
		"cep": "78000000",
		"cpfCnpj": "00000011111",
		"inscricaoMunicipal": "",
		"referenciaPropria": "pm_6584d8b0467598",
		"estado": "SP",
		"cidade": "São Paulo",
		"tipoPessoa": "FISICA",
		"observacoes": "123456",
		"dataInsert": "2023-09-22"
	}
}
										

Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}


Código 404 (NOT_FOUND){
	"status": "error",
	"code": 404,
	"message": "cliente não localizado",
	"document": ""
}


Código 405 (METHOD_NOT_ALLOWED){
	"status": "error",
	"code": 405,
	"message": "Método não aceito, utilize GET em vez do método utilizado",
	"document": null
}

Inserir cliente

Request (body)
									{
	"nome": "NOME DO CLIENTE",
	"email": "[email protected]",
	"telefone": "119656560000",
	"celular": "119656560000",
	"cpfCnpj": "00000011111",
	"cep": "78000000",
	"complemento": "Casa",
	"inscricaoMunicipal": "",
	"endereco": "RUA PIAUI",
	"numero": "498",
	"bairro": "Centro",
	"referenciaPropria": "123456",
	"observacoes": ""
}
								
Código 201 (CREATED){
	"status": "success",
	"code": 201,
	"message": "Criente adicionado com sucesso",
	"document": {
		"objeto": "cliente",
		"idCliente": 0232569856325,
		"nome": "NOME DO CLIENTE",
		"email": "[email protected]",
		"telefone": "119656560000",
		"celular": "119656560000",
		"endereco": "RUA PIAUI",
		"numero": "498",
		"complemento": "Casa",
		"bairro": "CENTRO",
		"cep": "78000000",
		"cpfCnpj": "00000011111",
		"inscricaoMunicipal": "",
		"referenciaPropria": "pm_6584d8b0467598",
		"estado": "SP",
		"cidade": "São Paulo",
		"tipoPessoa": "FISICA",
		"observacoes": "123456",
		"dataInsert": "2023-09-22"
	}
}
										
Código 400 (BAD_REQUEST){
	"status": "error",
	"code": 400,
	"message": "Mensagens de erro diversas",
	"document": null
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}
										

Código 422 (UNPROCESSABLE ENTITY){
	"status": "error",
	"code": 422,
	"message": "Erro ao adicionar cliente",
	"document": ""
}


Parâmetros

nome string obrigatório 
Nome do cliente

cpfCnpj string obrigatório 
CNPJ ou CPF do cliente - somente números

email string obrigatório 
E-mail do cliente

celular string obrigatório 
Whatsapp do cliente onde ele vai receber as notificações - Formato: 11999990000

telefone string
Telefone do cliente

cep string
CEP do cliente - somente números

complemento string
Complemento do endereço

inscricaoMunicipal string
Utilizada para emissão de NFS

endereco string
Endereço do cliente

numero string
Número da residência

bairro string
Bairro do cliente

cidade string
Cidade do cliente

estado string
Estado do cliente - somente dois carateres. Ex: SP

referenciaPropria string
Identificação externa do cliente

observacoes string
Informações adicionais

Alterar cliente (POST)

Request (body)
									{
	"nome": "NOME DO CLIENTE",
	"email": "[email protected]",
	"telefone": "119656560000",
	"celular": "119656560000",
	"cep": "78000000",
	"complemento": "Casa",
	"inscricaoMunicipal": "",
	"endereco": "RUA PIAUI",
	"numero": "498",
	"bairro": "Centro",
	"cidade": "São Paulo",
	"estado": "SP",
	"referenciaPropria": "123456",
	"observacoes": ""
}
								
Código 200 (SUCCESS){
	"status": "success",
	"code": 200,
	"message": "Cliente alterado com sucesso",
	"document": {
		"objeto": "cliente",
		"idCliente": 0232569856325,
		"nome": "NOME DO CLIENTE",
		"email": "[email protected]",
		"telefone": "119656560000",
		"celular": "119656560000",
		"endereco": "RUA PIAUI",	
		"numero": "498",	
		"complemento": "Casa",
		"bairro": "CENTRO",
		"cep": "78000000",
		"cpfCnpj": "00000011111",
		"inscricaoMunicipal": "123456",
		"referenciaPropria": "pm_6584d8b0467598",
		"estado": "SP",
		"cidade": "São Paulo",
		"tipoPessoa": "FISICA",
		"observacoes": "123456",
		"dataInsert": "2023-12-04"
	}
}
										
Código 400 (BAD_REQUEST){
	"status": "error",
	"code": 400,
	"message": "Mensagens de erro diversas",
	"document": null
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}
										

Código 422 (UNPROCESSABLE ENTITY){
	"status": "error",
	"code": 422,
	"message": "Não foi possível alterar o cliente",
	"document": ""
}

Alterar cliente (PATCH)

Request (body)
									{
	"nome": "NOME DO CLIENTE",
	"email": "[email protected]",
	"telefone": "119656560000",
	"celular": "119656560000",
	"cep": "78000000",
	"complemento": "Casa",
	"inscricaoMunicipal": "",
	"endereco": "RUA PIAUI",
	"numero": "498",
	"bairro": "Centro",
	"cidade": "São Paulo",
	"estado": "SP",
	"referenciaPropria": "123456",
	"observacoes": ""
}
								
Código 200 (SUCCESS){
	"status": "success",
	"code": 200,
	"message": "Cliente alterado com sucesso",
	"document": {
		"objeto": "cliente",
		"idCliente": 0232569856325,
		"nome": "NOME DO CLIENTE",
		"email": "[email protected]",
		"telefone": "119656560000",
		"celular": "119656560000",
		"endereco": "RUA PIAUI",	
		"numero": "498",	
		"complemento": "Casa",
		"bairro": "CENTRO",
		"cep": "78000000",
		"cpfCnpj": "00000011111",
		"inscricaoMunicipal": "123456",
		"referenciaPropria": "pm_6584d8b0467598",
		"estado": "SP",
		"cidade": "São Paulo",
		"tipoPessoa": "FISICA",
		"observacoes": "123456",
		"dataInsert": "2023-12-04"
	}
}
										
Código 400 (BAD_REQUEST){
	"status": "error",
	"code": 400,
	"message": "Mensagens de erro diversas",
	"document": null
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}
										

Código 422 (UNPROCESSABLE ENTITY){
	"status": "error",
	"code": 422,
	"message": "Não foi possível alterar cliente",
	"document": ""
}

Excluir cliente

Request (body)
										Somente autenticação necessária.
{id_cliente} (path) - ID do cliente
									
Código 200 (SUCCESS){
	"status": "success",
	"code": 200,
	"message": "Cliente deletado com sucesso",
	"document": {
		"objeto": "cliente",
		"deletado": true,
		"idCliente": "2563256985632"
	}
}

ou 

{
	"status": "success",
	"code": 200,
	"message": "Cliente deletado com sucesso somente no adquirente, delete o cliente também pelo painel",
	"document": {
		"objeto": "cliente",
		"deletado": true,
		"idCliente": "2563256985632"
	}
}
										
Código 400 (BAD_REQUEST){
	"status": "error",
	"code": 400,
	"message": "Mensagens de erro diversas",
	"document": null
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}
										

Código 422 (UNPROCESSABLE ENTITY){
	"status": "error",
	"code": 422,
	"message": "Não foi possível alterar o cliente",
	"document": ""
}

Cobranças

Gestão dos cobranças no sistema.

Listar cobranças cadastradas

Lista de todas as cobranças da conta.

Request (body)
										Somente autenticação necessária.
{paginanumero} (params) - Número da página atual, normalmente 1
{porpagina} (params) - Resultados por página
									
Código 200 (Success){
	"status": "success",
	"code": 200,
	"message": "Cobrança(s) localizada(s)",
	"document": {
		"pageno": "1",
		"pagesize": "30",
		"total_count": "2",
		"cobrancas": [
			{
				"objeto": "cobranca",
				"idCobranca": "7fy36n4n4cd4p4tv0",
				"dataInsert": "2023-12-20",
				"idCliente": "cus_00333209712",
				"assinatura": "",
				"linkPagamento": "",
				"valor": "338.00",
				"valorOriginal": "0.00",
				"totalJurosMultas": "",
				"descricao": "Descrição do serviço/produto",
				"tipo": "PIX",
				"transacaoPix": "",
				"status": "PENDING",
				"vencimento": "2024-09-12",
				"vencimentoOriginal": "2023-12-20",
				"dataPagamento": "0000-00-00",
				"numerosParcela": "",
				"parcelamento": "",
				"urlFatura": "https://cobrando.com.br/faturas/7fy36n4n4cd4p4tv0",
				"numeroFatura": "346415577",
				"referenciaPropria": "2c548e6caf17c28ad4c8bf9044e0e5b7",
				"deletado": "0",
				"antecipado": "0",
				"dataCredito": "0000-00-00",
				"estimativaCredito": "0000-00-00",
				"reciboUrl": null,
				"nossoNumero": "182414695",
				"boletoUrl": "https://cobrando.com.br/faturas/boletos/7fy36n4n4cd4p4tv0",
				"faturaUltimaVisuzalizacao": "",
				"desconto": {
					"valor": "5.00",
					"dataLimite": "",
					"diasAntesVencimento": "3",
					"tipo": "FIXED"
				},
				"multa": {
					"valor": "1.00",
					"tipo": "FIXED"
				},
				"juros": {
					"valor": "0.00"
				},
				"codigoBarras": "46191110000085000001882414699013298370000033800",
				"estornos": {
					"dataInsert": "",
					"status": "",
					"valor": "0.00",
					"descricao": "",
					"comprovante": null
				}
			},
			{
				"objeto": "cobranca",
				"idCobranca": "802536652877599193",
				"dataInsert": "2023-10-04",
				"idCliente": "cus_0000646661940",
				"assinatura": "",
				"linkPagamento": "",
				"valor": "10.01",
				"valorOriginal": "10.00",
				"totalJurosMultas": "",
				"descricao": "Teste",
				"tipo": "UNDEFINED",
				"transacaoPix": "",
				"status": "RECEIVED_IN_CASH",
				"vencimento": "2023-10-10",
				"vencimentoOriginal": "2023-10-10",
				"dataPagamento": "2023-10-04",
				"numerosParcela": "",
				"parcelamento": "",
				"urlFatura": "https://cobrando.com.br/faturas/802536652877599193",
				"numeroFatura": "290222240",
				"referenciaPropria": "4d933f9473d53d94accaf21c85152dfb",
				"deletado": "1",
				"antecipado": "0",
				"dataCredito": "2023-10-04",
				"estimativaCredito": "0000-00-00",
				"reciboUrl": "https://cobrando.com.br/faturas/recibos/802536652877599193",
				"nossoNumero": "166023879",
				"boletoUrl": "https://cobrando.com.br/faturas/boletos/802536652877599193",
				"faturaUltimaVisuzalizacao": "",
				"desconto": {
					"valor": null,
					"dataLimite": null,
					"diasAntesVencimento": "0",
					"tipo": null
				},
				"multa": {
					"valor": null,
					"tipo": null
				},
				"juros": {
					"valor": null
				},
				"codigoBarras": "",
				"estornos": {
					"dataInsert": null,
					"status": null,
					"valor": null,
					"descricao": null,
					"comprovante": null
				}
			}
		]
	}
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 404 (NOT_FOUND){
	"status": "error",
	"code": 404,
	"message": "Cobrança não localizada",
	"document": null
}



Código 405 (METHOD_NOT_ALLOWED){
	"status": "error",
	"code": 405,
	"message": "Método não aceito, utilize GET em vez do método utilizado",
	"document": null
}

Buscar cobranças

A busca por cobranças, podem ser efetuadas por dois parametros combinados, o key e key2, o key é obrigatório e key2 é opcional, lembrando que os dois forem preenchidos os dados terão que corresponder aos dois valores (AND). A busca por cobranças são efetuadas pelo id da cobrança, id do cliente, id da assinatura, valor, descricao, tipo de pagamento, vencimento, data de pagamento, referência própria, nosso Numero, status ou CPF/CNPJ. 

Request (body)
									Somente autenticação necessária.
{key} (params) - termo de busca 1
{key2} (params) - termo de busca 2
{paginanumero} (params) - Número da página atual, normalmente 1
{porpagina} (params) - Resultados por página
								
Código 200 (Success){
	"status": "success",
	"code": 200,
	"message": "Cobrança localizada",
	"document": {
		"pageno": "1",
		"pagesize": "30",
		"total_count": 0,
		"cobrancas": [
			{
				"objeto": "cobranca",
				"idCobranca": "7fy36n4n4cd4p4tv0",
				"dataInsert": "2023-12-20",
				"idCliente": "cus_00333209712",
				"assinatura": "",
				"linkPagamento": "",
				"valor": "338.00",
				"valorOriginal": "0.00",
				"totalJurosMultas": "",
				"descricao": "Descrição do serviço/produto",
				"tipo": "PIX",
				"transacaoPix": "",
				"status": "PENDING",
				"vencimento": "2024-09-12",
				"vencimentoOriginal": "2023-12-20",
				"dataPagamento": "0000-00-00",
				"numerosParcela": "",
				"parcelamento": "",
				"urlFatura": "https://cobrando.com.br/faturas/7fy36n4n4cd4p4tv0",
				"numeroFatura": "346415577",
				"referenciaPropria": "2c548e6caf17c28ad4c8bf9044e0e5b7",
				"deletado": "0",
				"antecipado": "0",
				"dataCredito": "0000-00-00",
				"estimativaCredito": "0000-00-00",
				"reciboUrl": null,
				"nossoNumero": "182414695",
				"boletoUrl": "https://cobrando.com.br/faturas/boletos/7fy36n4n4cd4p4tv0",
				"faturaUltimaVisuzalizacao": "",
				"desconto": {
					"valor": "5.00",
					"dataLimite": "",
					"diasAntesVencimento": "3",
					"tipo": "FIXED"
				},
				"multa": {
					"valor": "1.00",
					"tipo": "FIXED"
				},
				"juros": {
					"valor": "0.00"
				},
				"codigoBarras": "46191110000085000001882414699013298370000033800",
				"estornos": {
					"dataInsert": "",
					"status": "",
					"valor": "0.00",
					"descricao": "",
					"comprovante": null
				}
			}
		]
	}
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 404 (NOT_FOUND){
	"status": "error",
	"code": 404,
	"message": "Nenhuma cobranca localizada",
	"document": null
}


Código 405 (METHOD_NOT_ALLOWED){
	"status": "error",
	"code": 405,
	"message": "Método não aceito, utilize GET em vez do método utilizado",
	"document": null
}

Dados de uma única cobrança

Request (body)
									Somente autenticação necessária.
{id_cobranca} (path) - ID da fatura
								
Código 200 (Success){
	"status": "success",
	"code": 200,
	"message": "Cobrança localizada",
	"document": {
		"objeto": "cobranca",
		"idCobranca": "7fy36n4n4cd4p4tv0",
		"dataInsert": "2023-12-20",
		"idCliente": "cus_00333209712",
		"assinatura": "",
		"linkPagamento": "",
		"valor": "338.00",
		"valorOriginal": "0.00",
		"totalJurosMultas": "",
		"descricao": "Descrição do serviço/produto",
		"tipo": "PIX",
		"transacaoPix": "",
		"status": "PENDING",
		"vencimento": "2024-09-12",
		"vencimentoOriginal": "2023-12-20",
		"dataPagamento": "0000-00-00",
		"numerosParcela": "",
		"parcelamento": "",
		"urlFatura": "https://cobrando.com.br/faturas/7fy36n4n4cd4p4tv0",
		"numeroFatura": "346415577",
		"referenciaPropria": "2c548e6caf17c28ad4c8bf9044e0e5b7",
		"deletado": "0",
		"antecipado": "0",
		"dataCredito": "0000-00-00",
		"estimativaCredito": "0000-00-00",
		"reciboUrl": null,
		"nossoNumero": "182414695",
		"boletoUrl": "https://cobrando.com.br/faturas/boletos/7fy36n4n4cd4p4tv0",
		"faturaUltimaVisuzalizacao": "",
		"desconto": {
			"valor": "5.00",
			"dataLimite": "",
			"diasAntesVencimento": "3",
			"tipo": "FIXED"
		},
		"multa": {
			"valor": "1.00",
			"tipo": "FIXED"
		},
		"juros": {
			"valor": "0.00"
		},
		"codigoBarras": "46191110000085000001882414699013298370000033800",
		"estornos": {
			"dataInsert": "",
			"status": "",
			"valor": "0.00",
			"descricao": "",
			"comprovante": null
		}
	}
}
										

Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}


Código 404 (NOT_FOUND){
	"status": "error",
	"code": 404,
	"message": "Cobrança não localizada",
	"document": ""
}


Código 405 (METHOD_NOT_ALLOWED){
	"status": "error",
	"code": 405,
	"message": "Método não aceito, utilize GET em vez do método utilizado",
	"document": null
}

Inserir cobrança

Request (body)
									{
	"valor": 15.01,
	"descricao": "Fatura teste alterado 3",
	"tipoPagamento": "PIX",
	"vencimento": "2023-12-26",
	"desconto": {
		"valor": 5,
		"diasAntesVencimento": 2,
		"tipo": "PERCENTAGE"
	},
	"multa": {
		"valor": 1,
		"tipo": "FIXED"
	},
	"juros": {
		"valor": 4
	}
}
								
Código 201 (CREATED){
	"status": "success",
	"code": 200,
	"message": "Cobrança alterada com sucesso",
	"document": {
		"objeto": "cobranca",
		"idCobranca": "7fy36n4n4cd4p4tv0",
		"dataInsert": "2023-12-20",
		"idCliente": "cus_00333209712",
		"assinatura": "",
		"linkPagamento": "",
		"valor": "338.00",
		"valorOriginal": "0.00",
		"totalJurosMultas": "",
		"descricao": "Descrição do serviço/produto",
		"tipo": "PIX",
		"transacaoPix": "",
		"status": "PENDING",
		"vencimento": "2024-09-12",
		"vencimentoOriginal": "2023-12-20",
		"dataPagamento": "0000-00-00",
		"numerosParcela": "",
		"parcelamento": "",
		"urlFatura": "https://cobrando.com.br/faturas/7fy36n4n4cd4p4tv0",
		"numeroFatura": "346415577",
		"referenciaPropria": "2c548e6caf17c28ad4c8bf9044e0e5b7",
		"deletado": "0",
		"antecipado": "0",
		"dataCredito": "0000-00-00",
		"estimativaCredito": "0000-00-00",
		"reciboUrl": null,
		"nossoNumero": "182414695",
		"boletoUrl": "https://cobrando.com.br/faturas/boletos/7fy36n4n4cd4p4tv0",
		"faturaUltimaVisuzalizacao": "",
		"desconto": {
			"valor": "5.00",
			"dataLimite": "",
			"diasAntesVencimento": "3",
			"tipo": "FIXED"
		},
		"multa": {
			"valor": "1.00",
			"tipo": "FIXED"
		},
		"juros": {
			"valor": "0.00"
		},
		"codigoBarras": "46191110000085000001882414699013298370000033800",
		"estornos": {
			"dataInsert": "",
			"status": "",
			"valor": "0.00",
			"descricao": "",
			"comprovante": null
		}
	}
}
										
Código 400 (BAD_REQUEST){
		"status": "error",
		"code": 400,
		"message": "Mensagens de erro diversas",
		"document": null
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}
										

Código 422 (UNPROCESSABLE ENTITY){
	"status": "error",
	"code": 422,
	"message": "Erro ao criar cobrança",
	"document": ""
}

Alterar cobrança (POST)

Request (body)
									{
	"valor": 15.01,
	"descricao": "Fatura teste alterado 3",
	"tipoPagamento": "PIX",
	"vencimento": "2023-12-26",
	"desconto": {
		"valor": 5,
		"diasAntesVencimento": 2,
		"tipo": "PERCENTAGE"
	},
	"multa": {
		"valor": 1,
		"tipo": "FIXED"
	},
	"juros": {
		"valor": 4
	}
}
								
Código 200 (SUCCESS){
	"status": "success",
	"code": 200,
	"message": "Cobrança alterada com sucesso",
	"document": {
		"objeto": "cobranca",
		"idCobranca": "7fy36n4n4cd4p4tv0",
		"dataInsert": "2023-12-20",
		"idCliente": "cus_00333209712",
		"assinatura": "",
		"linkPagamento": "",
		"valor": "338.00",
		"valorOriginal": "0.00",
		"totalJurosMultas": "",
		"descricao": "Descrição do serviço/produto",
		"tipo": "PIX",
		"transacaoPix": "",
		"status": "PENDING",
		"vencimento": "2024-09-12",
		"vencimentoOriginal": "2023-12-20",
		"dataPagamento": "0000-00-00",
		"numerosParcela": "",
		"parcelamento": "",
		"urlFatura": "https://cobrando.com.br/faturas/7fy36n4n4cd4p4tv0",
		"numeroFatura": "346415577",
		"referenciaPropria": "2c548e6caf17c28ad4c8bf9044e0e5b7",
		"deletado": "0",
		"antecipado": "0",
		"dataCredito": "0000-00-00",
		"estimativaCredito": "0000-00-00",
		"reciboUrl": null,
		"nossoNumero": "182414695",
		"boletoUrl": "https://cobrando.com.br/faturas/boletos/7fy36n4n4cd4p4tv0",
		"faturaUltimaVisuzalizacao": "",
		"desconto": {
			"valor": "5.00",
			"dataLimite": "",
			"diasAntesVencimento": "3",
			"tipo": "FIXED"
		},
		"multa": {
			"valor": "1.00",
			"tipo": "FIXED"
		},
		"juros": {
			"valor": "0.00"
		},
		"codigoBarras": "46191110000085000001882414699013298370000033800",
		"estornos": {
			"dataInsert": "",
			"status": "",
			"valor": "0.00",
			"descricao": "",
			"comprovante": null
		}
	}
}
										
Código 400 (BAD_REQUEST){
	"status": "error",
	"code": 400,
	"message": "Mensagens de erro diversas",
	"document": null
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}
										

Código 422 (UNPROCESSABLE ENTITY){
	"status": "error",
	"code": 422,
	"message": "Não foi possível alterar a cobrança",
	"document": ""
}

Alterar cobrança (PATCH)

Request (body)
									{
	"valor": 15.01,
	"descricao": "Descricão da fatura",
	"tipoPagamento": "PIX",
	"vencimento": "2023-12-26",
	"desconto": {
		"valor": 5,
		"diasAntesVencimento": 2,
		"tipo": "PERCENTAGE"
	},
	"multa": {
		"valor": 1,
		"tipo": "FIXED"
	},
	"juros": {
		"valor": 4
	}
}
{id_fatura} (path) - ID da fatura
								
Código 200 (SUCCESS){
	"status": "success",
	"code": 200,
	"message": "Cobrança alterada com sucesso",
	"document": {
		"objeto": "cobranca",
		"idCobranca": "7fy36n4n4cd4p4tv0",
		"dataInsert": "2023-12-20",
		"idCliente": "cus_00333209712",
		"assinatura": "",
		"linkPagamento": "",
		"valor": "338.00",
		"valorOriginal": "0.00",
		"totalJurosMultas": "",
		"descricao": "Descrição do serviço/produto",
		"tipo": "PIX",
		"transacaoPix": "",
		"status": "PENDING",
		"vencimento": "2024-09-12",
		"vencimentoOriginal": "2023-12-20",
		"dataPagamento": "0000-00-00",
		"numerosParcela": "",
		"parcelamento": "",
		"urlFatura": "https://cobrando.com.br/faturas/7fy36n4n4cd4p4tv0",
		"numeroFatura": "346415577",
		"referenciaPropria": "2c548e6caf17c28ad4c8bf9044e0e5b7",
		"deletado": "0",
		"antecipado": "0",
		"dataCredito": "0000-00-00",
		"estimativaCredito": "0000-00-00",
		"reciboUrl": null,
		"nossoNumero": "182414695",
		"boletoUrl": "https://cobrando.com.br/faturas/boletos/7fy36n4n4cd4p4tv0",
		"faturaUltimaVisuzalizacao": "",
		"desconto": {
			"valor": "5.00",
			"dataLimite": "",
			"diasAntesVencimento": "3",
			"tipo": "FIXED"
		},
		"multa": {
			"valor": "1.00",
			"tipo": "FIXED"
		},
		"juros": {
			"valor": "0.00"
		},
		"codigoBarras": "46191110000085000001882414699013298370000033800",
		"estornos": {
			"dataInsert": "",
			"status": "",
			"valor": "0.00",
			"descricao": "",
			"comprovante": null
		}
	}
}
										
Código 400 (BAD_REQUEST){
	"status": "error",
	"code": 400,
	"message": "Mensagens de erro diversas",
	"document": null
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}
										

Código 422 (UNPROCESSABLE ENTITY){
	"status": "error",
	"code": 422,
	"message": "Não foi possível alterar a cobrança",
	"document": ""
}

Excluir cobrança

Request (body)
										Somente autenticação necessária.
{id_fatura} (path) - ID da fatura
									
Código 200 (SUCCESS){
		"status": "success",
		"code": 200,
		"message": "Cobrança excluída com sucesso",
		"document": {
		"objeto": "cliente",
		"deletado": true,
		"idCliente": "2563256985632"
	}
}

ou 

{
		"status": "success",
		"code": 200,
		"message": "Cobrança excluída com sucesso somente no adquirente, exclua a cobrança também pelo painel",
		"document": {
		"objeto": "cliente",
		"deletado": true,
		"idCliente": "2563256985632"
	}
}
										
Código 400 (BAD_REQUEST){
	"status": "error",
	"code": 400,
	"message": "Mensagens de erro diversas",
	"document": null
}


Código 401 (UNAUTHORIZED){
	"status": "error",
	"code": 401,
	"message": "Token Inválido",
	"document": "Falha na verificação da assinatura"
}


Código 403 (FORBIDDEN){
	"status": "error",
	"code": 403,
	"message": "Token expirado",
	"document": null
}
										

Código 422 (UNPROCESSABLE ENTITY){
	"status": "error",
	"code": 422,
	"message": "Não foi possível excluir a cobrança",
	"document": ""
}

Webhooks

Com nossos webhooks você poderá receber informações relevantes diretamente no seu sistema, como exemplo, baixar o status a fatura do seu lado.

Webhook de cobranças

Cada criação ou alteração que ocorrer em uma cobrança, você poderá receber os dados via webhook, você receberá uma requisição POST com uma Json com os dados da fatura.

Request (body)
										{
	"evento": "PAYMENT_UPDATED",
	"pagamento": {
		"objeto": "payment",
		"idFatura": "pay_lz4zlab6qdhb",
		"dataCriacao": "2023-12-20",
		"assinatura": null,
		"linkPagamento": null,
		"valor": 49.9,
		"valorOriginal": null,
		"totalJurosMultas": null,
		"descricao": "Descrição do serviço/produto da cobrança",
		"tipo": "PIX",
		"transacaoPix": null,
		"status": "RECEIVED_IN_CASH",
		"vencimento": "2023-12-28",
		"vencimentoOriginal": "2023-12-28",
		"dataPagamento": "2024-01-09",
		"numerosParcela": 1,
		"parcelamento": "9979ef97-d2e5-47f1-84f3-bfd606292709",
		"urlFatura": "https://cobrando.com.br/faturas/pay_lz4zlab6qdhbguol",
		"numeroFatura": "346529398",
		"referenciaPropria": "f06a9ef2f42feda133c3979cd077b05c",
		"deletado": false,
		"antecipado": 1,
		"dataCredito": null,
		"estimativaCredito": null,
		"reciboUrl": "https://cobrando.com.br/faturas/recibos/pay_lz4zlab6qdhbguol",
		"nossoNumero": "182227444",
		"boletoUrl": "https://cobrando.com.br/faturas/boletos/pay_lz4zlab6qdhbguol",
		"faturaUltimaVisuzalizacao": null,
		"cliente": {
			"idCliente": "cus_000064491940",
			"nome": "Jhon Doe",
			"email": "[email protected]",
			"telefone": "11999999999",
			"celular": "11999999999",
			"endereco": "RUA DAS FLORES",
			"numero": "131",
			"complemento": "",
			"bairro": "JARDIM POLIFER",
			"cep": "01520000",
			"inscricaoMunicipal": "25632563",
			"referenciaPropria": "2563254F56SD256D45RD563",
			"estado": "SP",
			"cidade": "São Paulo"
		},
		"desconto": {
			"valor": 5,
			"dataLimite": null,
			"diasAntesVencimento": 3,
			"tipo": "FIXED"
		},
		"multa": {
			"valor": 1,
			"tipo": "FIXED"
		},
		"juros": {
			"valor": 0,
			"tipo": "PERCENTAGE"
		},
		"codigoBarras": "",
		"estornos": {
			"dataCriacao": null,
			"status": null,
			"value": null,
			"descricao": null,
			"comprovante": null
		}
	}
}

Possíveis valores do campo "evento"


  • PAYMENT_CREATED - Cobrança nova gerada.
  • PAYMENT_UPDATED - Cobrança alterada.
  • PAYMENT_CONFIRMED - Cobrança confirmada (pagamento efetuado, porém o saldo ainda não foi disponibilizado).
  • PAYMENT_RECEIVED - Cobrança recebida e saldo disponível.
  • PAYMENT_OVERDUE - Cobrança vencida.
  • PAYMENT_DELETED - Cobrança removida.
  • PAYMENT_RESTORED - Cobrança restaurada.
  • PAYMENT_REFUNDED - Cobrança estornada.
  • PAYMENT_REFUND_IN_PROGRESS - Estorno em andamento.
  • PAYMENT_RECEIVED_IN_CASH_UNDONE - Recebimento em dinheiro desfeito.
  • PAYMENT_CHARGEBACK_REQUESTED - Recebido chargeback.
  • PAYMENT_CHARGEBACK_DISPUTE - Em disputa de chargeback.
  • PAYMENT_AWAITING_CHARGEBACK_REVERSAL - Disputa vencida, aguardando repasse da adquirente.

Possíveis valores do campo "status"


  • PENDING - Aguardando pagamento
  • RECEIVED - Recebida
  • CONFIRMED - Pagamento confirmado (saldo ainda não creditado)
  • OVERDUE - Vencida
  • REFUNDED - Estornada
  • RECEIVED_IN_CASH - Recebida em dinheiro (não gera saldo na conta)
  • REFUND_REQUESTED - Estorno Solicitado
  • REFUND_IN_PROGRESS - Estorno em processamento
  • CHARGEBACK_REQUESTED - Recebido chargeback
  • CHARGEBACK_DISPUTE - Em disputa de chargeback
  • AWAITING_CHARGEBACK_REVERSAL - Disputa vencida, aguardando repasse da adquirente
  • DUNNING_RECEIVED - Recuperada

Webhook da régua de cobrança

Na sua régua de cobrança, além de enviar o lembrete para o cliente, também é possível enviar um webhook da cobrança em questão. Você receberá uma requisição POST com uma Json com os dados da fatura e régua de cobrança.

Request (body)
										{
	"evento": "REGUA",
	"pagamento": {
		"objeto": "payment",
		"idFatura": "pay_2u7f6i8pgde98yil",
		"dataCriacao": "2024-01-09",
		"assinatura": "",
		"valor": 15,
		"descricao": "Testando",
		"status": "PENDING",
		"vencimento": "2024-01-10",
		"urlFatura": "https://cobrando.com.br/faturas/pay_2u7f6i8pgde98yil",
		"reciboUrl": "https://cobrando.com.br/faturas/recibos/pay_2u7f6i8pgde98yil",
		"boletoUrl": "https://cobrando.com.br/faturas/boletos/pay_2u7f6i8pgde98yil",
		"regua": {
			"dias": "1",
			"quando": "antes",
			"mensagem": "Olá *Fulano de tal*

Segue abaixo os dados da sua fatura com vencimento amanhã:

Vencimento: *10/01/2024*
Valor: *R$ 15,00*
Descrição: *Testando*
Url da fatura: *https://cobrando.com.br/faturas/pay_2u7f6i8pgde98yil*

Código de barras: 46191110000000000001886548720019195910000001500"
		},
		"cliente": {
			"idCliente": "cus_000064491940",
			"nome": "Fulano de tal",
			"email": "",
			"whatsapp": "11999999999",
			"endereco": "RUA DAS FLORES",
			"numero": "131",
			"complemento": "",
			"bairro": "JARDIM ARAGUAIA",
			"cep": "07111555",
			"inscricaoMunicipal": "6365896569254",
			"referenciaPropria": "3fcff694703ef925cda5e73d92c4S",
			"estado": "SP",
			"cidade": "São Paulo"
		}
	}
}

Entenda os campos enviados para seu webhook.


  • evento - Fixo, sempre REGUA.
  • pagamento->objeto - Fixo, sempre payment.
  • pagamento->idFatura - Identificação da fatura no sistema.
  • pagamento->dataCriacao - Data da criação da fatura
  • pagamento->assinatura - Caso este campo esteja preenchido, a fatura se refere a uma assinatura e este será a identificação.
  • pagamento->valor - Valor da cobrança
  • pagamento->descricao - Descrição da cobrança
  • pagamento->status - Status atual da cobrança
  • pagamento->vencimento - Vencimento da cobrança
  • pagamento->urlFatura - URL da cobrança
  • pagamento->reciboUrl - Recibo para faturas pagas
  • pagamento->boletoUrl - URL do boleto
  • pagamento->regua->dias - Dias da régua de cobrança
  • pagamento->regua->quando - Pode ser antes ou depois, que é a quantidade de dias acima antes ou depois do vencimento da cobrança
  • pagamento->regua->mensagem - Mensagem que foi enviada para o cliente
  • pagamento->cliente->idCliente - Id do cliente no sistema
  • pagamento->cliente->nome - Nome do cliente
  • pagamento->cliente->email - E-mail do cliente
  • pagamento->cliente->whatsapp - Whatsapp do cliente
  • pagamento->cliente->endereco - Endereço do cliente
  • pagamento->cliente->numero - Número do endereço do cliente
  • pagamento->cliente->complemento - Complmento do endereço do cliente
  • pagamento->cliente->bairro - Bairro do cliente
  • pagamento->cliente->cep - CEP do cliente
  • pagamento->cliente->inscricaoMunicipal - Inscrição Municipal do cliente, útil para emissão de NFSe.
  • pagamento->cliente->referenciaPropria - Identificação única no sistema
  • pagamento->cliente->estado - Estado do cliente
  • pagamento->cliente->cidade - Cidade do cliente