Informaçães básicas

Autenticação

Antes de acessar o Cobrato, você deverá criar uma conta e precisará do seu API token, que é requerido em todas as requisições via API e será o identificador de sua conta. Para conseguí-lo, vá em Gerenciamento > Configurações Gerais.

A autenticação na API do Cobrato é realizada utilizando HTTP Basic. Você não usará sua senha e login como o de costume, em vez disso usará o API token como seu login e a senha pode ficar em branco ou, caso seu cliente HTTP peça uma senha, pode ser qualquer valor, a letra X por exemplo.

    Formato JSON

    EXEMPLO DE REQUISIÇÃO

      $ curl -i -u $YOUR_API_TOKEN:X \
        -H 'User-Agent: My App 1.0' \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json' \
        -X GET https://app.cobrato.com/api/v1

    EXEMPLO DE RESPOSTA

    {
      "chave": "valor"
    }

Formatos de requisição e resposta

Fuso horário

Todos os dados recebidos e enviados através da API do Cobrato são baseados no fuso horário UTC. Caso seja necessário utilizar outro fuso horário, este será utilizado somente na apresentação, o que não afeta o resultado da resposta da API.

Formatos de data e hora

Todas as datas e horas são formatadas de acordo com ISO 8601 padrão, e sempre serão dadas no fuso horário.

Você deve sempre fornecer os seus valores de data e hora no mesmo formato ISO 8601 e no fuso horário UTC.

Tipo	Formato	Exemplo
Data	YYYY-mm-dd	2014-11-05
Data hora	YYYY-mm-ddTHH:MM:SSZ	2014-11-05T17:28:03Z

Formato numérico

Paginação

Todas as listagens são páginadas. Pode-se utilizar os parâmetros page (valor padrão 1) e per_page (valor padrão 25) para controlar, respectivamente, a página e a quantidade de itens por página.

    Formato JSON

    EXEMPLO DE REQUISIÇÃO

      $ curl -i -u $YOUR_API_TOKEN:X \
        -H 'User-Agent: My App 1.0' \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json' \
        -X GET https://app.cobrato.com/api/v1/lista?page=2&per_page=5

    EXEMPLO DE RESPOSTA

    {
      "chave1": "valor 1",
      "chave2": "valor 2",
      "chave3": "valor 3",
      "chave4": "valor 4",
      "chave5": "valor 5"
    }

Restrição

Toda resposta de requisição conterá os headers X-RateLimit-Limit, X-RateLimit-Reset e X-RateLimit-Remaining, significando respectivamente o limite de requisições por minuto, a data em que a contagem será resetada e quantas requisições restam.

Cada token de autorização está limitado a 60 requests por minuto. Após atingir a cota, todo acesso irá retornar erro 429 Too Many Requests até que o número de acessos seja resetado. Os acessos são resetados de 1 em 1 minuto, ou seja, se você realizou um request às 17:43:53, o reset acontecerá às 17:44:00 e não 17:44:53.


  EXEMPLO DE RESPOSTA

  HTTP/1.1 429 TOO MANY REQUESTS
  Content-Type: application/json; charset=utf-8
  Date: Wed, 26 Jan 2011 12:56:45 GMT
  Retry-After: 60
  X-RateLimit-Limit: 60
  X-RateLimit-Reset: Wed, 26 Jan 2011 12:57:00 GMT
  X-RateLimit-Remaining: -1

Beneficiário

Beneficiário

EXEMPLO

  {
    "id":1,
    "national_identifier_type":"cpf",
    "national_identifier":"38031171513",
    "name":"João Silveira",
    "zipcode":"99000-750",
    "city":"Carapebus",
    "state":"RJ",
    "neighbourhood":"Centro",
    "street":"Rua Julio de Castilhos",
    "number":"100",
    "complement": "Ao lado da lotérica.",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/payees/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/payees/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/payees/1"}
      ]
  }

É possível ter indeterminados beneficiários, e a eles que pertencem as contas bancárias, configurações de cobrança, e as próprias cobranças do sistema. Podem ser tanto pessoas físicas como pessoas jurídicas.

Parâmetros

Campo	Tipo	Comentário
id	integer
national_identifier_type	string	tipo de identificação nacional (‘cpf’ ou 'cnpj’)
national_identifier	string	número válido de cnpj ou cpf, de acordo com o campo anterior
name	string	nome completo do beneficiário
city	string	nome da cidade do domicílio do beneficiário
state	string	uf do estado do domicílio do beneficiário (duas letras, p. ex. 'RJ’)
neighbourhood	string	bairro do domicílio do beneficiário
street	string	logradouro do beneficiário
number	string	número da logradouro do beneficiário
zipcode	string	cep do domicílio do beneficiário
complement	string	complemento para o endereço de domicilio do beneficiário
_links	array of object	links do beneficiário

Informações do Beneficiário

Mostrar Beneficiário

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payees/:payee_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payees/:payee_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id":1,
    "national_identifier_type":"cpf",
    "national_identifier":"38031171513",
    "name":"João Silveira",
    "zipcode":"99000-750",
    "city":"Carapebus",
    "state":"RJ",
    "neighbourhood":"Centro",
    "street":"Rua Julio de Castilhos",
    "number":"100",
    "complement": "Ao lado da lotérica.",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/payees/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/payees/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/payees/1"}
      ]
  }

Retorna as informações detalhadas do beneficiário informado em JSON.

Lista de Todos os Beneficiários

Listar Beneficiários

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payees

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payees

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "payees":
      [
        {
          // informações beneficiário 1
        },
        {
          // informações beneficiário 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos os beneficiários pertencentes a sua Conta de Serviço.

Criação de Beneficiário

Criar Beneficiário

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/payees

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/payees \
    -d '{
        "name": "João Silva",
        "city": "Caxias do Sul",
        "national_identifier_type": "cpf",
        "national_identifier": "38031171513",
        "state": "RS",
        "street": "Rua Principal",
        "neighbourhood": "Centro",
        "number": "174",
        "zipcode": "95055-777"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":{
      "name": ["não pode ficar em branco"],
      "city": ["não pode ficar em branco"],
      "national_identifier_type": ["não pode ficar em branco","não está incluído na lista"],
      "state":["não pode ficar em branco","não possui o tamanho esperado (2 caracteres)"],
      "neighbourhood": ["não pode ficar em branco"],
      "street": ["não pode ficar em branco"],
      "number": ["não pode ficar em branco"],
      "zipcode": ["não pode ficar em branco"]
    }
  }

Cria um novo beneficiário, retornando as informações do mesmo caso haja sucesso. Se houverem erros eles serão informados no corpo da resposta.

Parâmetros

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo de identificação nacional ('cpf’ ou 'cnpj’)
national_identifier	string	(requerido) número válido de cnpj ou cpf, de acordo com o campo anterior
name	string	(requerido) nome completo do beneficiário
city	string	(requerido) nome da cidade do domicílio do beneficiário
state	string	(requerido) uf do estado do domicílio do beneficiário (duas letras, p. ex. 'RJ’)
neighbourhood	string	(requerido) bairro do domicílio do beneficiário
street	string	(requerido) logradouro do beneficiário
number	string	(requerido) número da logradouro do beneficiário
zipcode	string	(requerido) cep do domicílio do beneficiário
complement	string	(opcional) complemento para o endereço de domicilio do beneficiário

Atualização de Beneficiário

Atualizar Beneficiário

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/payees/:payee_id
  PATCH https://app.cobrato.com/api/v1/payees/:payee_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/payees/:payee_id \
    -d '{
        "city": "Farroupilha",
        "state": "RS"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM BENEFICIÁRIO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

    {
      "errors":{
        "national_identifier_type":["não está incluído na lista"]
      }
    }

Atualiza o beneficiário determinado, retornando as informações do mesmo caso haja sucesso. Se houverem erros eles serão informados no corpo da resposta. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Parâmetros

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo de identificação nacional ('cpf’ ou 'cnpj’)
national_identifier	string	(requerido) número válido de cnpj ou cpf, de acordo com o campo anterior
name	string	(requerido) nome completo do beneficiário
city	string	(requerido) nome da cidade do domicílio do beneficiário
state	string	(requerido) uf do estado do domicílio do beneficiário (duas letras, p. ex. 'RJ’)
neighbourhood	string	(requerido) bairro do domicílio do beneficiário
street	string	(requerido) logradouro do beneficiário
number	string	(requerido) número da logradouro do beneficiário
zipcode	string	(requerido) cep do domicílio do beneficiário
complement	string	(opcional) complemento para o endereço de domicilio do beneficiário

Exclusão de Beneficiário

Excluir Beneficiário

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/payees/:payee_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/payees/:payee_id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM BENEFICIÁRIO INEXISTENTE

    404 Not Found

Exclui determinado beneficiário e junto a ele todas suas configurações de cobrança, contas bancárias e as cobranças. As mudanças são irreversíveis.

Pagador

Pagador

EXEMPLO

  {
    "id":1,
    "national_identifier_type":"cpf",
    "national_identifier":"38031171513",
    "name":"João Silveira",
    "zipcode":"99000-750",
    "city":"Carapebus",
    "state":"RJ",
    "neighbourhood":"Centro",
    "street":"Rua Julio de Castilhos",
    "number":"100",
    "complement": "Ao lado da lotérica.",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/people/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/people/1"}
      ]
  }

ATENÇÃO! Este endpoint será descontinuado. Por favor utilize o endpoint de Pessoa

É possível ter indeterminados pagadores pertencentes a uma Conta de Serviço. Podem ser tanto pessoas físicas como pessoas jurídicas.

É importante ressaltar que, para o pagador ser utilizado em uma cobrança via boleto registrado, todos os dados devem ser preenchidos (são obrigatórios), com exceção do complement.

Parâmetros

Campo	Tipo	Comentário
id	integer
national_identifier_type	string	tipo de identificação nacional (‘cpf’ ou 'cnpj’)
national_identifier	string	número válido de cnpj ou cpf, de acordo com o campo anterior
name	string	nome completo do pagador
city	string	nome da cidade do domicílio do pagador
state	string	uf do estado do domicílio do pagador (duas letras, p. ex. 'RJ’)
neighbourhood	string	bairro do domicílio do pagador
street	string	logradouro do pagador
number	string	número da logradouro do pagador
zipcode	string	cep do domicílio do pagador
complement	string	complemento para o endereço de domicilio do pagador
_links	array of object	links do pagador

Informações do Pagador

Mostrar Pagador

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payers/:payer_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payers/:payer_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id":1,
    "national_identifier_type":"cpf",
    "national_identifier":"38031171513",
    "name":"João Silveira",
    "zipcode":"99000-750",
    "city":"Carapebus",
    "state":"RJ",
    "neighbourhood":"Centro",
    "street":"Rua Julio de Castilhos",
    "number":"100",
    "complement": "Ao lado da lotérica.",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/people/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/people/1"}
      ]
  }

ATENÇÃO! Este endpoint será descontinuado. Por favor utilize o endpoint de Pessoa

Retorna as informações detalhadas do pagador em JSON.

Lista de Todos os Pagadores

Listar Pagadores

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payers

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payers

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "people":
      [
        {
          // informações pagador 1
        },
        {
          // informações pagador 2
        },
        ...
      ]
  }

ATENÇÃO! Este endpoint será descontinuado. Por favor utilize o endpoint de Pessoa

Retorna uma lista em JSON contendo todos os pagadores pertencentes a sua Conta de Serviço.

Criação de Pagador

Criar Pagador

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/payers

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/payers \
    -d '{
        "name": "João Silva",
        "city": "Caxias do Sul",
        "national_identifier_type": "cpf",
        "national_identifier": "38031171513",
        "state": "RS",
        "street": "Rua Principal",
        "neighbourhood": "Centro",
        "number": "174",
        "zipcode": "95055-777"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":{
      "name": ["não pode ficar em branco"],
      "national_identifier_type": ["não pode ficar em branco","não está incluído na lista"]
    }
  }

ATENÇÃO! Este endpoint será descontinuado. Por favor utilize o endpoint de Pessoa

Cria um novo pagador, retornando as informações do mesmo caso haja sucesso. Se houverem erros eles serão informados no corpo da resposta.

Parâmetros

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo de identificação nacional ('cpf’ ou 'cnpj’)
national_identifier	string	(requerido) número válido de cnpj ou cpf, de acordo com o campo anterior
name	string	(requerido) nome completo do pagador
city	string	(opcional) nome da cidade do domicílio do pagador
state	string	(opcional) uf do estado do domicílio do pagador (duas letras, p. ex. 'RJ’)
neighbourhood	string	(opcional) bairro do domicílio do pagador
street	string	(opcional) logradouro do pagador
number	string	(opcional) número da logradouro do pagador
zipcode	string	(opcional) cep do domicílio do pagador
complement	string	(opcional) complemento para o endereço de domicilio do pagador

Atualização de Pagador

Atualizar Pagador

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/payers/:payer_id
  PATCH https://app.cobrato.com/api/v1/payers/:payer_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/payers/:payer_id \
    -d '{
        "city": "Farroupilha",
        "state": "RS"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM BENEFICIÁRIO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

    {
      "errors":{
        "national_identifier_type":["não está incluído na lista"]
      }
    }

ATENÇÃO! Este endpoint será descontinuado. Por favor utilize o endpoint de Pessoa

Atualiza um determinado pagador, retornando as informações do mesmo caso haja sucesso. Se houverem erros eles serão informados no corpo da resposta. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Parâmetros

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo de identificação nacional ('cpf’ ou 'cnpj’)
national_identifier	string	(requerido) número válido de cnpj ou cpf, de acordo com o campo anterior
name	string	(requerido) nome completo do pagador
city	string	(opcional) nome da cidade do domicílio do pagador
state	string	(opcional) uf do estado do domicílio do pagador (duas letras, p. ex. 'RJ’)
neighbourhood	string	(opcional) bairro do domicílio do pagador
street	string	(opcional) logradouro do pagador
number	string	(opcional) número da logradouro do pagador
zipcode	string	(opcional) cep do domicílio do pagador
complement	string	(opcional) complemento para o endereço de domicilio do pagador

Pessoa

Pessoa

EXEMPLO

  {
    "id":1,
    "national_identifier_type":"cpf",
    "national_identifier":"38031171513",
    "name":"João Silveira",
    "zipcode":"99000-750",
    "city":"Carapebus",
    "state":"RJ",
    "neighbourhood":"Centro",
    "street":"Rua Julio de Castilhos",
    "number":"100",
    "complement": "Ao lado da lotérica.",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/people/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/people/1"}
      ]
  }

É possível ter indeterminadas pessoas pertencentes a uma Conta de Serviço. Podem ser tanto pessoas físicas como pessoas jurídicas.

É importante ressaltar que, para a pessoa ser utilizada em uma cobrança via boleto registrado, neste caso como Pagador, todos os dados são obrigatórios, com exceção do complement.

Parâmetros

Campo	Tipo	Comentário
id	integer
national_identifier_type	string	tipo de identificação nacional (‘cpf’ ou 'cnpj’)
national_identifier	string	número válido de cnpj ou cpf, de acordo com o campo anterior
name	string	nome completo da pessoa
city	string	nome da cidade do domicílio da pessoa
state	string	uf do estado do domicílio da pessoa (duas letras, p. ex. 'RJ’)
neighbourhood	string	bairro do domicílio da pessoa
street	string	logradouro da pessoa
number	string	número da logradouro da pessoa
zipcode	string	cep do domicílio da pessoa
complement	string	complemento para o endereço de domicilio da pessoa
_links	array of object	links da pessoa

Informações da Pessoa

Mostrar Pessoa

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/people/:person_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/people/:person_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id":1,
    "national_identifier_type":"cpf",
    "national_identifier":"38031171513",
    "name":"João Silveira",
    "zipcode":"99000-750",
    "city":"Carapebus",
    "state":"RJ",
    "neighbourhood":"Centro",
    "street":"Rua Julio de Castilhos",
    "number":"100",
    "complement": "Ao lado da lotérica.",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/people/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/people/1"}
      ]
  }

Retorna as informações detalhadas da pessoa em JSON.

Lista de Todos as Pessoas

Listar Pessoas

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/people

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/people

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "people":
      [
        {
          // informações pessoa 1
        },
        {
          // informações pessoa 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todas as pessoas pertencentes a sua Conta de Serviço.

Criação de Pessoa

Criar Pessoa

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/people

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/people \
    -d '{
        "name": "João Silva",
        "city": "Caxias do Sul",
        "national_identifier_type": "cpf",
        "national_identifier": "38031171513",
        "state": "RS",
        "street": "Rua Principal",
        "neighbourhood": "Centro",
        "number": "174",
        "zipcode": "95055-777"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":{
      "name": ["não pode ficar em branco"],
      "national_identifier_type": ["não pode ficar em branco","não está incluído na lista"]
    }
  }

Cria uma nova pessoa, retornando as informações da mesma caso haja sucesso. Se houverem erros eles serão informados no corpo da resposta.

Parâmetros

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo de identificação nacional ('cpf’ ou 'cnpj’)
national_identifier	string	(requerido) número válido de cnpj ou cpf, de acordo com o campo anterior
name	string	(requerido) nome completo da pessoa
city	string	(opcional) nome da cidade do domicílio da pessoa
state	string	(opcional) uf do estado do domicílio da pessoa (duas letras, p. ex. 'RJ’)
neighbourhood	string	(opcional) bairro do domicílio da pessoa
street	string	(opcional) logradouro da pessoa
number	string	(opcional) número da logradouro da pessoa
zipcode	string	(opcional) cep do domicílio da pessoa
complement	string	(opcional) complemento para o endereço de domicilio da pessoa

Atualização de Pessoa

Atualizar Pessoa

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/people/:person_id
  PATCH https://app.cobrato.com/api/v1/people/:person_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/people/:person_id \
    -d '{
        "city": "Farroupilha",
        "state": "RS"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM BENEFICIÁRIO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

    {
      "errors":{
        "national_identifier_type":["não está incluído na lista"]
      }
    }

Atualiza uma determinada pessoa, retornando as informações da mesma caso haja sucesso. Se houverem erros eles serão informados no corpo da resposta. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Parâmetros

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo de identificação nacional ('cpf’ ou 'cnpj’)
national_identifier	string	(requerido) número válido de cnpj ou cpf, de acordo com o campo anterior
name	string	(requerido) nome completo da pessoa
city	string	(opcional) nome da cidade do domicílio da pessoa
state	string	(opcional) uf do estado do domicílio da pessoa (duas letras, p. ex. 'RJ’)
neighbourhood	string	(opcional) bairro do domicílio da pessoa
street	string	(opcional) logradouro da pessoa
number	string	(opcional) número da logradouro da pessoa
zipcode	string	(opcional) cep do domicílio da pessoa
complement	string	(opcional) complemento para o endereço de domicilio da pessoa

Conta Bancária

Conta Bancária

EXEMPLO

  {
    "id":1,
    "payee_id":"1",
    "bank_code":"001",
    "agency":"1606",
    "agency_digit":"3",
    "account":"91000",
    "account_digit":"7",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
        {"rel":"payee","method":"GET","href":"https://app.cobrato.com/api/v1/payees/1"}
      ]
  }

As Contas Bancárias, pertencem aos seus beneficiários, sendo assim é necessário que sempre haja ao menos um beneficiário para criação de conta bancária.

Parâmetros

Campo	Tipo	Comentário
id	integer
payee_id	integer	identificador do beneficiários no Cobrato
bank_code	string	código do banco no Febraban
agency	string	agência da conta bancária
agency_digit	string	dígito da agência da conta bancária (apenas utilizado pelo Banco do Brasil - 001)
account	string	número da conta bancária
account_digit	string	dígito do número da conta bancária (apenas não utilizado pelo HSBC - 399)
_links	array of object	links da conta bancária e de seu beneficiários

Informações da Conta Bancária

Mostrar Conta Bancária

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/bank_accounts/:bank_account_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/bank_accounts/:bank_account_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id":1,
    "payee_id":"1",
    "bank_code":"001",
    "agency":"1606",
    "agency_digit":"3",
    "account":"91000",
    "account_digit":"7",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
        {"rel":"payee","method":"GET","href":"https://app.cobrato.com/api/v1/payees/1"}
      ]
  }

Retorna as informações detalhadas da conta bancária informada em JSON e também a referência ao seu beneficiário.

Lista de Todas as Contas Bancárias

Listar Contas Bancárias

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/bank_accounts

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/bank_accounts

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "bank_accounts":
      [
        {
          // informações conta bancária 1
        },
        {
          // informações conta bancária 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos as contas bancárias em que seus beneficiários pertencentem a sua Conta de Serviço.

Criação de Conta Bancária

Criar Conta Bancária

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/bank_accounts

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/bank_accounts \
    -d '{
          "payee_id": "1",
          "bank_code": "001",
          "agency":"1606",
          "agency_digit":"3",
          "account":"91000",
          "account_digit":"7"
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "bank_code": ["não pode ficar em branco","não possui o tamanho esperado (3 caracteres)"],
        "agency": ["não pode ficar em branco","não é um número"],
        "account": ["não pode ficar em branco","não é um número"],
        "payee_id":["não pode ficar em branco"]
      }
  }

Cria um nova conta bancária, retornando as informações da mesma caso haja sucesso. Se houverem erros eles serão informados no corpo da resposta.

Parâmetros

Campo	Tipo	Comentário
payee_id	integer	(requerido) identificador do beneficiário no Cobrato em que a conta bancária irá pertencer
bank_code	string	(requerido) código do banco no Febraban
agency	string	(requerido) agência da conta bancária
agency_digit	string	(requerido apenas pelo Banco do Brasil - 001) dígito da agência da conta bancária
account	string	(requerido) número da conta bancária
account_digit	string	(requerido, com exceção do HSBC - 399) dígito do número da conta bancária

Atualização de Conta Bancária

Atualizar Conta Bancária

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/bank_accounts/:bank_account_id
  PATCH https://app.cobrato.com/api/v1/bank_accounts/:bank_account_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/bank_accounts/:bank_account_id \
    -d '{
          "agency":"1606",
          "agency_digit":"3"
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM CONTA BANCÁRIA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "bank_code": ["não possui o tamanho esperado (3 caracteres)"],
        "agency": ["não é um número"],
        "account": ["não é um número"],
      }
  }

Atualiza a conta bancária determinada, retornando as informações da mesma caso haja sucesso. Se houverem erros eles serão informados no corpo da resposta. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Ao alterar campo ‘bank_code’, caso houvesse algum campo preenchido que de acordo com o novo banco deverá ficar em branco, o Cobrato fará automaticamente. Exemplo: ao alterar uma conta bancária ('bank_code’) do Banco do Brasil (001) para o Bradesco (327), o campo 'agency_digit’ receberá 'null’ como novo valor.

Alterações nos campos 'bank_code’, 'agency’, 'agency_digit’, 'account’ ou 'account_digit’ colocará a configuração de cobrança em homologação.

Parâmetros

Campo	Tipo	Comentário
bank_code	string	(requerido) código do banco no Febraban
agency	string	(requerido) agência da conta bancária
agency_digit	string	(requerido apenas pelo Banco do Brasil - 001) dígito da agência da conta bancária
account	string	(requerido) número da conta bancária
account_digit	string	(requerido, com exceção do HSBC - 399) dígito do número da conta bancária

Exclusão de Conta Bancária

Excluir Conta Bancária

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/bank_accounts/:bank_account_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/bank_accounts/:bank_account_id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM CONTA BANCÁRIA INEXISTENTE

    404 Not Found

Exclui determinada conta bancária e junto a ela todas suas configurações de cobrança, e cobranças. As mudanças são irreversíveis.

Carteiras disponíveis

Listar carteiras disponíveis para Conta Bancária

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/bank_accounts/:bank_account_id/portfolio_codes

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/bank_accounts/:bank_account_id/portfolio_codes

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "portfolio_codes": [
      "11",
      "12",
      "16",
      "17",
      "18",
      "31",
      "51"
    ],
    "_links": {
      "rel": "bank_account",
      "method": "GET",
      "href": "https://sandbox.cobrato.com/api/v1/charges/1"
    }
  }

EXEMPLO DE ESTADO DA RESPOSTA COM CONTA BANCÁRIA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

Retorna todas as carteiras disponíveis do banco de uma Conta Bancária.

Configuração de Cobrança

Configuração de Cobrança

EXEMPLO

  {
    "id": 1,
    "type": "billet",
    "payee_id": 1,
    "bank_account_id": 1,
    "portfolio_code": "17",
    "agreement_code": "12345678",
    "agreement_code_digit": "1",
    "name": "Configuração de Cobrança por Boleto",
    "initial_number": 1,
    "next_number": 1,
    "end_number": 1000,
    "status": "pending",
    "registered_charges": true,
    "remittance_agreement_code": 4576361,
    "remittance_cnab_pattern": 400,
    "initial_remittance_number": 1,
    "transmission_code": "987655",
    "pre_released_billet": false,
    "writing_off_deadline": null,
    "available_charge_types": ["billet"],
    "timezone": "Brasilia",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"bank_account","method":"GET","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
        {"rel":"payee","method":"GET","href":"https://app.cobrato.com/api/v1/payee/1"}
      ]
  }

As Configurações de Cobrança podem ser de tipos diferentes. Sendo assim, os parâmetros e algums comportamentos irão variar de acordo com o tipo. Atualmente temos os tipos:

Conta Bancária (billet)
Gateway de pagamento (payment_gateway)

Conta bancária

As Configurações de Cobrança do tipo Conta bancária (billet), pertencem as suas contas bancárias, sendo assim é necessário que sempre haja ao menos uma conta bancária para criação desse tipo configuração de cobrança, que também tem suas validações de acordo com o banco de sua conta bancária.

Parâmetros

Campo	Tipo	Comentário
id	integer
type	string	indica o tipo da configuração de cobrança. Nesse caso ‘billet’
name	string	nome que identifica esta configuração de cobrança
status	string	'ok’ ou 'pending’ para indicar se configuração de cobrança está ou não homologada, respectivamente
payee_id	integer	identificador do beneficiário desta configuração de cobrança no Cobrato
bank_account_id	integer	identificador da conta bancária desta configuração de cobrança no Cobrato
portfolio_code	string	código de portfólio
agreement_code	string	código de convênio ou do beneficiário, de acordo com o banco. No caso do Itaú deve ser igual ao campo 'account’ da conta bancária
agreement_code_digit	string	verificador do código de convênio, de acordo com o banco
initial_number	integer	número inicial do nosso número, sendo atribuído automaticamente e sequencialmente as cobranças
next_number	integer	próximo nosso número a ser atribuído a uma cobrança criada a partir desta configuração de cobrança
end_number	integer	número final do nosso número, sendo o último número a ser atribuído, após isso a sequência é reiniciada
registered_charges	boolean	informa se a configuração de cobrança utiliza boletos registrados ou não, sendo sempre true para configurações de cobrança criadas após 27/10/2018
remittance_agreement_code	integer	número do convênio com o banco (apenas para o Bradesco)
remittance_cnab_pattern	integer	padrão utilizado no arquivo CNAB de remessa
initial_remittance_number	integer	número inicial de remessa, ou seja, qual foi o último número sequencial de remessa enviado para o banco
transmission_code	string	código de transmissão (apenas para o Santander)
pre_released_billet	boolean	caso a configuração de cobrança utilize boletos registrados, este atributo indica se os boletos podem ser acessados antes do registro no banco ser confirmado
writing_off_deadline	integer	número de dias após o vencimento da cobrança para que seja feita a baixa automática do título no banco (apenas para cobranças registradas com padrão 240)
available_charge_types	array of strings	tipos de cobrança disponíveis. No caso de Configuração de Cobrança por Conta Bancária, será disponível somente a opção “billet”. Este campo será gerenciado pelo Cobrato
timezone	string	fuso horário utilizado pelo banco. Utilize essa informação para converter e apresentar atributos do tipo “datetime” das cobranças dessa configuração de forma adequada
_links	array of object	links da configuração de cobrança e de sua conta bancária

Gateway de Pagamento

Parâmetros comuns a todos os Gateways

Campo	Tipo	Comentário
id	integer
type	string	indica o tipo da configuração de cobrança. Nese caso 'payment_gateway’
name	string	nome que identifica esta configuração de cobrança
status	string	indica o status, ou etapa, de homologação em que configuração de cobrança está ('pending’, 'production_tests’, 'ok’)
payee_id	integer	identificador do beneficiário desta configuração de cobrança no Cobrato
gateway_name	string	nome do gateway de pagamento ('cielo-ws15’, 'cielo-api30’, 'pjbank’)
available_charge_types	array of strings	tipos de cobrança disponíveis. No caso de Configuração de Cobrança por Gateway de Pagamento, as opções possíveis são “billet” e “credit_card”. Este campo será gerenciado pelo Cobrato
timezone	string	fuso horário utilizado pelo gateway. Utilize essa informação para converter e apresentar atributos do tipo “datetime” das cobranças dessa configuração de forma adequada
_links	array of object	links da configuração de cobrança e de sua conta bancária

Parâmetros específicos para gateway Cielo

Campo	Tipo	Comentário
gateway_id	string	número de afiliação do contrato com o gateway de pagamento
gateway_key	string	chave de acesso atribuída pelo gateway de pagamento
use_avs	boolean	define se será feita a solicitação e a confirmação do endereço de cobrança da fatura do cartão utilizado no pagamento

Parâmetros específicos para gateway PJBank

Campo	Tipo	Comentário
gateway_id	string	credencial do contrato com o gateway de pagamento para cobranças de cartão de crédito
gateway_key	string	chave de acesso atribuída pelo gateway de pagamento para cobranças de cartão de crédito
billet_gateway_id	string	credencial do contrato com o gateway de pagamento para cobranças de boleto
billet_gateway_key	string	chave de acesso atribuída pelo gateway de pagamento para cobranças de boleto

Informações da Configuração de Cobrança

Mostrar Configuração de Cobrança

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/charge_configs/:charge_config_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/charge_configs/:charge_config_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA (BOLETO)

  {
    "id": 1,
    "type": "billet",
    "payee_id": 1,
    "bank_account_id": 1,
    "portfolio_code": "17",
    "agreement_code": "12345678",
    "agreement_code_digit": "1",
    "name": "Configuração de Cobrança por Boleto",
    "initial_number": 1,
    "next_number": 1,
    "end_number": 1000,
    "status": "pending",
    "registered_charges": true,
    "remittance_agreement_code": 4576361,
    "remittance_cnab_pattern": 400,
    "initial_remittance_number": 1,
    "transmission_code": "987655",
    "pre_released_billet": false,
    "writing_off_deadline": null,
    "available_charge_types": ["billet"],
    "deactivated_at": "2018-04-10T17:46:01.253Z",
    "timezone": "Brasilia",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"bank_account","method":"GET","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
        {"rel":"payee","method":"GET","href":"https://app.cobrato.com/api/v1/payees/1"}
      ]
  }

  EXEMPLO DE CORPO DA RESPOSTA (GATEWAY DE PAGAMENTO)

    {
      "id": 1,
      "type": "payment_gateway",
      "name": "Configuração de Cobrança - PJBank",
      "payee_id": 1,
      "gateway_name": "pjbank",
      "gateway_key": "",
      "gateway_id": "",
      "billet_gateway_key": "ABC123",
      "billet_gateway_id": "ABC123",
      "account_holder": false,
      "use_avs": false,
      "available_charge_types": ["billet"],
      "timezone": "Brasília",
      "logo_url": https://cobrato-sandbox-uploads.s3.amazonaws.com/payment_gateway_configs/logos/114/logo.png?1549051243,
      "_links":
        [
          {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
          {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
          {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
          {"rel":"bank_account","method":"GET","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
          {"rel":"payee","method":"GET","href":"https://app.cobrato.com/api/v1/payees/1"}
        ]
    }

Retorna as informações detalhadas da Configuração de Cobrança informada em JSON e também suas referências.

Lista de Todas as Configurações de Cobrança

Listar Configurações de Cobrança

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/charge_configs

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/charge_configs

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "charge_configs":
      [
        {
          // informações configuração de cobrança 1
        },
        {
          // informações configuração de cobrança 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todas as Configurações de Cobrança que pertencem a sua Conta de Serviço.

É possível filtrar a lista através dos seguintes parâmetros:

type: Filtra pelo tipo de configuração de cobrança. O valor a ser informado é string com um dos tipos existentes de configuração de cobrança.
charge_type: Filtra pelo tipo de cobrança disponível para a configuração, ou seja retornará as configurações que suportam o tipo de cobrança informado. O valor a ser informado é a string com um dos tipos de cobrança disponíveis (“billet” ou “credit_card” até o momento).
bank_code: Filtrar pelo código do banco da configuração de cobrança. O valor a ser informado é uma string com o código do banco. Por exemplo “341” para Itaú, “237” para Bradesco e etc.
payee_ids: Filtra pelos beneficiários informados. O valor informado é uma lista* de ids dos beneficiários.
payee_national_identifiers: Filtra pelos beneficiários informados. O valor informado é uma lista* de número de documentos dos beneficiários.
active: Filtra pelo estado da configuração de cobrança. O valor a ser informado é true para retornar somente as configurações ativas ou false para retornar somente as configurações de cobrança desativadas.

lista* Os valores em “lista” devem ser enviados da seguinte forma: url?payee_ids[]=15&payee_ids[]=42.

Criação de Configuração de Cobrança

Criar Configuração de Cobrança

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/charge_configs

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/charge_configs \
    -d '{
          "type": "billet",
          "payee_id": "1",
          "bank_account_id": "1",
          "portfolio_code": "17",
          "agreement_code": "12345678",
          "agreement_code_digit": "1",
          "name": "Configuração de Cobrança por Boleto",
          "initial_number": "1",
          "end_number": "1000",
          "registered_charges": "true",
          "remittance_agreement_code": "4576361",
          "remittance_cnab_pattern": "400",
          "initial_remittance_number": "1"
          "transmission_code": "987655",
          "logo": {
            "content": "iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAM...",
            "content_type": "image/png",
            "filename": "logo.png",
          }
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "name":["não pode ficar em branco"],
        "portfolio_code":["não pode ficar em branco"],
        "agreement_code":["não pode ficar em branco"],
        "agreement_code_digit":["não pode ficar em branco"]
      }
  }

Cria uma nova Configuração de Cobrança, retornando as informações da mesma em caso de sucesso. Se houverem erros eles serão informados no corpo da resposta.

Boleto

Parâmetros

Campo	Tipo	Comentário
type	string	(opcional) indica o tipo da configuração de cobrança. Neste caso deve ser informado “billet” ou deixado em branco, pois este é o valor padrão
payee_id	integer	(requerido) código de identificação do beneficiário ao qual a configuração de cobrança irá pertencer
bank_account_id	integer	(requerido) código de identificação da conta bancária em que a configuração de cobrança irá pertencer
portfolio_code	string	(requerido) código de portfólio, validação conforme o banco
agreement_code	string	(requerido, com exceção do Itaú onde é preenchido automaticamente) código de convênio ou do beneficiário, de acordo com o banco
agreement_code_digit	string	(requerido, com exceção do HSBC e Itaú, sendo preenchido automaticamente para o último) verificador do código de convênio, de acordo com o banco
name	string	(requerido) nome que identifica esta configuração de cobrança
initial_number	integer	(requerido) número inicial do nosso número, sendo atribuído automaticamente e sequencialmente às cobranças
end_number	integer	(opcional) número final do nosso número, sendo o último número a ser atribuído, após isso a sequência é reiniciada
next_number	integer	(opcional) próximo nosso número a ser atribuído a uma cobrança criada a partir desta configuração de cobrança (por padrão inicia com o valor de `initial_number` e é incrementado automatica e sequencialmente)
remittance_agreement_code	integer	(requerido) número do convênio com o banco (apenas para o Bradesco)
remittance_cnab_pattern	integer	(requerido) padrão utilizado no arquivo CNAB de remessa. Os valores permitidos são 240 ou 400
transmission_code	string	(requerido) código de transmissão (apenas para o Santander)
initial_remittance_number	integer	(requerido) número inicial de remessa, ou seja, qual foi o último número sequencial de remessa enviado para o banco. Por padrão o valor é 1
pre_released_billet	boolean	(opcional) caso a configuração de cobrança utilize boletos registrados, este atributo indica se os boletos podem ser acessados antes do registro no banco ser confirmado. Por padrão é `false`
writing_off_deadline	integer	(opcional) número de dias após o vencimento da cobrança para que seja feita a baixa automática do título no banco. Valor pode variar entre 7 e 90. (apenas para cobranças registradas com padrão 240)

ATENÇÃO! Caso seu cliente pague o boleto antes do banco ter confirmado seu registro, o pagamento pode ser devolvido e/ou o banco pode te cobrar uma sobretaxa. Ao definir o campo pre_released_billet como true, você está assumindo este risco.

Gateway de Pagamento

Parâmetros comuns a todos os Gateways

Campo	Tipo	Comentário
type	string	(requerido) indica o tipo da configuração de cobrança. Neste caso deve ser informado “payment_gateway”
payee_id	integer	(requerido) código de identificação do beneficiário ao qual a configuração de cobrança irá pertencer
name	string	(requerido) nome que identifica esta configuração de cobrança
gateway_name	string	(requerido) nome do gateway de pagamento ('cielo-ws15’, 'cielo-api30’, 'pjbank’)*

Parâmetros para o gateway Cielo

Campo	Tipo	Comentário
gateway_id	string	(requerido) número de afiliação do contrato com o gateway de pagamento
gateway_key	string	(requerido) chave de acesso atribuída pelo gateway de pagamento
use_avs	boolean	(opcional) define se será feita a solicitação e a confirmação do endereço de cobrança da fatura do cartão utilizado no pagamento (`false` por padrão)
status	string	(opcional, default “pending”) indica o status, ou etapa, de homologação em que configuração de cobrança está ('pending’, 'production_tests’, 'ok’)

Parâmetros para o gateway PJBank

Campo	Tipo	Comentário
gateway_id	string	(requerido, somente quando o campo 'gateway_key’ estiver preenchido) credencial do contrato com o gateway de pagamento para cobranças de cartão de crédito
gateway_key	string	(requerido, somente quando o campo 'gateway_id’ estiver preenchido) chave de acesso atribuída pelo gateway de pagamento para cobranças de cartão de crédito
billet_gateway_id	string	(requerido, somente quando o campo 'billet_gateway_key’ estiver preenchido) credencial do contrato com o gateway de pagamento para cobranças de boleto
billet_gateway_key	string	(requerido, somente quando o campo 'billet_gateway_id’ estiver preenchido) chave de acesso atribuída pelo gateway de pagamento para cobranças de boleto
logo	object	(opcional) dados do logotipo que aparecerá nos boletos gerados
logo[content]	string	(opcional) conteúdo do arquivo do logotipo codificado em Base64
logo[content_type]	string	(opcional) Content-Type do arquivo do logotipo. Exemplo: “image/png” (deve ser imagem no formato png, gif ou jpg)
logo[filename]	string	(opcional) Nome do arquivo do logotipo.

* Os possíveis valores para o gateway_name são os seguintes:

cielo-api30: API e-Commerce Cielo

cielo-ws15: Webservice 1.5

pjbank: PJBank

Atualização de Configuração de Cobrança

Atualizar Configuração de Cobrança

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/charge_configs/:charge_config_id
  PATCH https://app.cobrato.com/api/v1/charge_configs/:charge_config_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/charge_configs/:charge_config_id \
    -d '{
          "portfolio_code": "17",
          "agreement_code": "12345678",
          "agreement_code_digit": "1",
          "name": "Novo Nome"
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM CONFIGURAÇÃO DE COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "bank_code": ["não possui o tamanho esperado (3 caracteres)"],
        "agency": ["não é um número"],
        "account": ["não é um número"],
      }
  }

Atualiza a Configuração de Cobrança determinada, retornando as informações da mesma em caso de sucesso. Se houverem erros, eles serão informados no corpo da resposta. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Boleto

Parâmetros

Campo	Tipo	Comentário
payee_id	integer	(requerido) código de identificação do beneficiário ao qual a configuração de cobrança irá pertencer
portfolio_code	string	(requerido) código de portfólio, validação conforme o banco
agreement_code	string	(requerido, com exceção do Itaú onde é preenchido automaticamente) código de convênio ou do beneficiário, de acordo com o banco
agreement_code_digit	string	(requerido, com exceção do HSBC e Itaú, sendo preenchido automaticamente para o último) verificador do código de convênio, de acordo com o banco
name	string	(requerido) nome que identifica esta configuração de cobrança
initial_number	integer	(requerido) número inicial do nosso número, sendo atribuído automaticamente e sequencialmente às cobranças
end_number	integer	(opcional) número final do nosso número, sendo o último número a ser atribuído, após isso a sequência é reiniciada
next_number	integer	(opcional) próximo nosso número a ser atribuído a uma cobrança criada a partir desta configuração de cobrança (é incrementado automatica e sequencialmente)
remittance_agreement_code	integer	(requerido) número do convênio com o banco (apenas para o Bradesco)
remittance_cnab_pattern	integer	(requerido) padrão utilizado no arquivo CNAB de remessa. Os valores permitidos são 240 ou 400
transmission_code	string	(requerido) código de transmissão (apenas para o Santander)
initial_remittance_number	integer	(requerido) número inicial de remessa, ou seja, qual foi o último número sequencial de remessa enviado para o banco. Por padrão o valor é 1
pre_released_billet	boolean	(opcional) caso a configuração de cobrança utilize boletos registrados, este atributo indica se os boletos podem ser acessados antes do registro no banco ser confirmado. Por padrão é `false`
writing_off_deadline	integer	(opcional) número de dias após o vencimento da cobrança para que seja feita a baixa automática do título no banco. Valor pode variar entre 7 e 90. (apenas para cobranças registradas com padrão 240)

Gateway de Pagamento

Parâmetros comuns a todos os Gateways

Campo	Tipo	Comentário
name	string	(requerido) nome que identifica esta configuração de cobrança
payee_id	integer	(requerido) código de identificação do beneficiário ao qual a configuração de cobrança irá pertencer
gateway_name	string	(requerido) nome do gateway de pagamento ('cielo-ws15’, 'cielo-api30’, 'pjbank’)*

Parâmetros para o gateway Cielo

Campo	Tipo	Comentário
gateway_id	string	(requerido) número de afiliação do contrato com o gateway de pagamento
gateway_key	string	(requerido) chave de acesso atribuída pelo gateway de pagamento
use_avs	boolean	(opcional) define se será feita a solicitação e a confirmação do endereço de cobrança da fatura do cartão utilizado no pagamento (`false` por padrão)
status	string	(opcional, default “pending”) indica o status, ou etapa, de homologação em que configuração de cobrança está ('pending’, 'production_tests’, 'ok’)

Parâmetros para o gateway PJBank

Campo	Tipo	Comentário
gateway_id	string	(requerido, somente quando o campo 'gateway_key’ estiver preenchido) credencial do contrato com o gateway de pagamento para cobranças de cartão de crédito
gateway_key	string	(requerido, somente quando o campo 'gateway_id’ estiver preenchido) chave de acesso atribuída pelo gateway de pagamento para cobranças de cartão de crédito
billet_gateway_id	string	(requerido, somente quando o campo 'billet_gateway_key’ estiver preenchido) credencial do contrato com o gateway de pagamento para cobranças de boleto
billet_gateway_key	string	(requerido, somente quando o campo 'billet_gateway_id’ estiver preenchido) chave de acesso atribuída pelo gateway de pagamento para cobranças de boleto
logo	object	(opcional) dados do logotipo que aparecerá nos boletos gerados
logo[content]	string	(opcional) conteúdo do arquivo do logotipo codificado em Base64
logo[content_type]	string	(opcional) Content-Type do arquivo do logotipo. Exemplo: “image/png” (deve ser imagem no formato png, gif ou jpg)
logo[filename]	string	(opcional) Nome do arquivo do logotipo.

Exclusão de Configuração de Cobrança

Excluir Configuração de Cobrança

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/charge_configs/:charge_config_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/charge_configs/:charge_config_id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM CONFIGURAÇÃO DE COBRANÇA INEXISTENTE

    404 Not Found

Exclui determinada Configuração de Cobrança e junto a ela todas suas Cobranças. As mudanças são irreversíveis.

Desativação de Configuração de Cobrança

Desativar Configuração de Cobrança

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/charge_configs/:id/deactivate

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/charge_configs/:id/deactivate

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM CONFIGURAÇÃO DE COBRANÇA INEXISTENTE

    404 Not Found

Desativa determinada Configuração de Cobrança.

Modelo de Cobrança

Charge Template

EXEMPLO

  {
    "id": 1,
    "name": "Nome do Modelo",
    "charge_config_id": 1,
    "charged_amount": 1,
    "document_kind": "DM",
    "instructions": "",
    "demonstrative": "",
    "registrable": false,
    "interest_amount_per_month": "4.56",
    "mulct_type": 1,
    "mulct_value": "",
    "auto_send_billet": false,
    "email_sender_name": "Nome da Empresa",
    "email_subject": "Boleto de cobrança",
    "email_text": "",
    "email_reply_to": "name@company.com",
    "_links": [
      {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/charge_templates/1"},
      {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/charge_templates/1"},
      {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/charge_templates/1"}
    ]
  }

É possível ter indeterminados modelos. Cada modelo de cobrança pertence à uma configuração de cobrança.

Parâmetros

Campo	Tipo	Comentário
name	string	(requerido) Nome identificador do modelo de cobrança
charge_config_id	integer	(requerido) id da configuração de cobrança
charged_amount	decimal	(opcional) valor cobrado no boleto
document_kind	string	(opcional) espécie do documento, podendo ser para qualquer tipo de cobrança: DM (Duplicata Mercantil), DS (Duplicata de Serviço) ou NP (Nota Promissória). Somente para cobranças via banco: DV (Diversos) ou somente para cobranças via gateway: LC (Letra de Cambio) ou RC (Recibo)
instructions	integer	(opcional) instruções de pagamento do boleto, por padrão “Pagável em qualquer agência até data do vencimento.” (pode ser linhas separadas por “\n”)
demonstrative	integer	(opcional) demonstrativo do Boleto, por padrão “Não receber após o vencimento.” (pode ser linhas separadas por “\n”)
registrable	boolean	(opcional) indica se a cobrança é registrável (do tipo que deve ser registrada no banco). Por padrão é o que está definido na Configuração de Cobrança
interest_amount_per_month	decimal	(opcional) porcentagem de juros mensal que deve ser aplicado em caso de atraso. No boleto será mostrado o valor diário de juros que será calculado
mulct_type	string	(opcional) indica o tipo de multa que deve ser aplicada em caso de atraso (“percentage” para porcentagem, “currency” para valor em reais)
mulct_value	decimal	(opcional) valor da multa que deve ser aplicada em caso de atraso, com base em seu tipo
auto_send_billet	boolean	(opcional) Padrão “false”. Envio ou não de boleto por email
email_sender_name	string	(opcional) Nome do remetente do email de notificação de cobrança
email_subject	string	(opcional) Assunto do email de notificação de cobrança
email_text	string	(opcional) Texto do email de notificação de cobrança
email_reply_to	string	(opcional) Endereço de email a ser utilizado na respsta ao email de notificação de cobrança

Informações do Modelo de Cobrança

Mostra Modelo de Cobrança

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/charge_templates/:id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/charge_templates/:id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id": 1,
    "name": "Nome do Modelo",
    "charge_config_id": 1,
    "charged_amount": 1,
    "document_kind": "DM",
    "instructions": "",
    "demonstrative": "",
    "registrable": false,
    "interest_amount_per_month": "4.56",
    "mulct_type": 1,
    "mulct_value": "",
    "auto_send_billet": true,
    "email_sender_name": "Nome da Empresa",
    "email_subject": "Boleto de cobrança",
    "email_text": "",
    "email_reply_to": "name@company.com",
    "_links": [
      {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/charge_templates/1"},
      {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/charge_templates/1"},
      {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/charge_templates/1"}
    ]
  }

Retorna as informações detalhadas do modelo de cobrança em formato JSON.

Lista de Todos os Modelos de Cobrança


Listar Modelos de cobrança

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/charge_templates

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/charge_templates

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "charge_templates":
      [
        {
          // informações modelo 1
        },
        {
          // informações modelo 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos os modelos de cobrança pertencentes a sua conta de serviço. É possível filtrar os Modelos pela configuração de cobrança passando o charge_config_id

Criação de Modelo de Cobrança

Criar Modelo de Cobrança

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/charge_templates

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/charge_templates \
    -d '{
        "name": "Nome do Modelo",
        "charge_config_id": 1,
        "charged_amount": 1,
        "document_kind": "DM",
        "instructions": "",
        "demonstrative": "",
        "registrable": false,
        "interest_amount_per_month": "4.56",
        "mulct_type": 1,
        "mulct_value": "",
        "auto_send_billet": true,
        "email_sender_name": "Nome da Empresa",
        "email_subject": "Boleto de cobrança",
        "email_text": "",
        "email_reply_to": "name@company.com"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "name": [
        "não é válido",
        "não pode ficar em branco"
      ]
    }
  }

Cria um novo modelo de cobrança, retornando as informações do mesmo caso haja sucesso.

Parâmetros

Campo	Tipo	Comentário
name	string	(requerido) Nome identificador do modelo de cobrança
charge_config_id	integer	(requerido) id da configuração de cobrança
charged_amount	decimal	(opcional) valor cobrado no boleto
document_kind	string	(opcional) espécie do documento, podendo ser para qualquer tipo de cobrança: DM (Duplicata Mercantil), DS (Duplicata de Serviço) ou NP (Nota Promissória). Somente para cobranças via banco: DV (Diversos) ou somente para cobranças via gateway: LC (Letra de Cambio) ou RC (Recibo)
instructions	integer	(opcional) instruções de pagamento do boleto, por padrão “Pagável em qualquer agência até data do vencimento.” (pode ser linhas separadas por “\n”)
demonstrative	integer	(opcional) demonstrativo do Boleto, por padrão “Não receber após o vencimento.” (pode ser linhas separadas por “\n”)
registrable	boolean	(opcional) indica se a cobrança é registrável (do tipo que deve ser registrada no banco). Por padrão é o que está definido na Configuração de Cobrança
interest_amount_per_month	decimal	(opcional) porcentagem de juros mensal que deve ser aplicado em caso de atraso. No boleto será mostrado o valor diário de juros que será calculado
mulct_type	string	(opcional) indica o tipo de multa que deve ser aplicada em caso de atraso (“percentage” para porcentagem, “currency” para valor em reais)
mulct_value	decimal	(opcional) valor da multa que deve ser aplicada em caso de atraso, com base em seu tipo
auto_send_billet	boolean	(opcional) Padrão “false”. Envio ou não de boleto por email
email_sender_name	string	(opcional) Nome do remetente do email de notificação de cobrança
email_subject	string	(opcional) Assunto do email de notificação de cobrança
email_text	string	(opcional) Texto do email de notificação de cobrança
email_reply_to	string	(opcional) Endereço de email a ser utilizado na respsta ao email de notificação de cobrança

Atualização de Modelo de Cobrança

Atualizar Modelo de Cobrança

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/charge_templates/:id
  PATCH https://app.cobrato.com/api/v1/charge_templates/:id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/charge_templates \
    -d '{
        "id": "1"
        "name": "Nome do Modelo",
        "charged_amount": 1,
        "document_kind": "DM",
        "charge_config_id": 1,
        "instructions": "",
        "demonstrative": "",
        "registrable": false,
        "interest_amount_per_month": "4.56",
        "mulct_type": 1,
        "mulct_value": "",
        "auto_send_billet": false,
        "email_sender_name": "Nome da Empresa",
        "email_subject": "Boleto de cobrança",
        "email_text": "",
        "email_reply_to": "name@company.com"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM MODELO DE COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

Atualiza campos do Modelo de Cobrança. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Parâmetros

Campo	Tipo	Comentário
name	string	(requerido) Nome identificador do modelo de cobrança
charge_config_id	integer	(requerido) id da configuração de cobrança
charged_amount	decimal	(opcional) valor cobrado no boleto
document_kind	string	(opcional) espécie do documento, podendo ser para qualquer tipo de cobrança: DM (Duplicata Mercantil), DS (Duplicata de Serviço) ou NP (Nota Promissória). Somente para cobranças via banco: DV (Diversos) ou somente para cobranças via gateway: LC (Letra de Cambio) ou RC (Recibo)
instructions	integer	(opcional) instruções de pagamento do boleto, por padrão “Pagável em qualquer agência até data do vencimento.” (pode ser linhas separadas por “\n”)
demonstrative	integer	(opcional) demonstrativo do Boleto, por padrão “Não receber após o vencimento.” (pode ser linhas separadas por “\n”)
registrable	boolean	(opcional) indica se a cobrança é registrável (do tipo que deve ser registrada no banco). Por padrão é o que está definido na Configuração de Cobrança
interest_amount_per_month	decimal	(opcional) porcentagem de juros mensal que deve ser aplicado em caso de atraso. No boleto será mostrado o valor diário de juros que será calculado
mulct_type	string	(opcional) indica o tipo de multa que deve ser aplicada em caso de atraso (“percentage” para porcentagem, “currency” para valor em reais)
mulct_value	decimal	(opcional) valor da multa que deve ser aplicada em caso de atraso, com base em seu tipo
auto_send_billet	boolean	(opcional) Padrão “false”. Envio ou não de boleto por email
email_sender_name	string	(opcional) Nome do remetente do email de notificação de cobrança
email_subject	string	(opcional) Assunto do email de notificação de cobrança
email_text	string	(opcional) Texto do email de notificação de cobrança
email_reply_to	string	(opcional) Endereço de email a ser utilizado na respsta ao email de notificação de cobrança

Exclusão de Modelo de Cobrança

Excluir Modelo de Cobrança

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/charge_templates/:id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/charge_templates/:id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM MODELO DE COBRANÇA INEXISTENTE

    404 Not Found

Exclui determinado modelo de cobrança. A exclusão é irreversível.

Cobrança

Cobrança

EXEMPLO

  {
    "id":1,
    "type": "billet",
    "charge_config_id": 1,
    "due_date":"2015-02-14",
    "document_kind":"DV",
    "document_date":null,
    "document_number":null,
    "custom_our_number": "true",
    "our_number":"0",
    "our_number_digit":null,
    "charged_amount":"10.07",
    "interest_amount_per_month": "1.02",
    "mulct_type": "percentage",
    "mulct_value": "10.12",
    "instructions":"Pagável em qualquer agência até data do vencimento.",
    "demonstrative":"Não receber após o vencimento.",
    "notification_emails":["myemail@gmail.com"],
    "received":true, # deprecated
    "received_amount":"10.07", # deprecated
    "received_at":"2015-01-30T04:00:00Z", # deprecated
    "paid_amount":"10.07",
    "paid_at":"2015-01-30T04:00:00Z",
    "paid_discount":"4.56",
    "paid_additions":"0.50",
    "paid_rebate":"0.30",
    "payment_tax":"2.5",
    "paid_difference":"0",
    "processing_date":"2015-01-30",
    "for_homologation":true,
    "registrable": true,
    "payer_national_identifier_type": "cpf",
    "payer_national_identifier": "12345678909",
    "payer_name": "Jonh Doe",
    "payer_number": "43",
    "payer_complement": "8 andar",
    "payer_street": "Rua do Carmo",
    "payer_neighbourhood": "Centro",
    "payer_zipcode": "22230062",
    "payer_city": "Rio de Janeiro",
    "payer_state": "RJ",
    "registration_status": "without_remittance",
    "canceled_at": "2015-01-31T17:46:01.253Z",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/charges/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/charges/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/charges/1"},
        {"rel":"receive","method":"POST","href":"https://app.cobrato.com/api/v1/charges/1/receive"},
        {"rel":"deliver","method":"POST","href":"https://app.cobrato.com/api/v1/charges/1/deliver_billet"},
        {"rel":"charge_config","method":"GET","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"billet","method":"GET","href":"https://app.cobrato.com/api/v1/charges/1/billet"},
        {"rel":"public_billet","method":"GET","href":"https://app.cobrato.com/public/billets/1dac03daed4ab93edd3bb2b25639d33f/download"},
        {"rel":"cancel","method":"POST","href":"https://app.cobrato.com/api/v1/charges/1/cancel"}
      ]
  }

Cada uma das cobranças criadas terá um tipo, podendo variar de acordo com a configuração de cobrança. Um gateway de pagamento pode ter suporte à cobranças via boleto ou cartão de crédito, por exemplo. Por este motivo os parâmetros, validações e alguns comportamentos serão variáveis de acordo com o tipo de cobrança e da configuração de cobrança.

Cobranças via Conta Bancária

Boleto

Parâmetros

Campo	Tipo	Comentário
id	integer
type	string	indica o tipo da cobrança. Nesse caso, “billet”
charge_config_id	integer	identificador da configuração de cobrança a qual esta cobrança pertence
due_date	date	data de vencimento da cobranca
document_kind	string	espécie do documento, podendo ser DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória) ou DV (Diversos)
document_date	date	data de emissão do documento
document_number	string	número do documento é o número utilizado e controlado pelo beneficiário para identificar o título de cobrança.
our_number	string	nosso número
our_number_digit	integer	digito do verificador do nosso número
custom_our_number	boolean	indica se a cobrança utiliza um “nosso número” customizado. O valor padrão é false, mas caso definido true, o campo ‘our_number’ se torna requerido
charged_amount	decimal	valor cobrado no boleto
interest_amount_per_month	decimal	porcentagem de juros mensal que deve ser aplicado em caso de atraso. No boleto será mostrado o valor diário de juros que será calculado
mulct_type	string	indica o tipo de multa que deve ser aplicada em caso de atraso (“percentage” para porcentagem, “currency” para valor em reais)
mulct_value	decimal	valor da multa que deve ser aplicada em caso de atraso, com base em seu tipo
instructions	string	instruções de pagamento do boleto
demonstrative	string	demonstrativo do Boleto
notification_emails	array of strings	emails que receberão notificações sobre a cobrança
payer_emails	array of strings	(DEPRECATED: use notification_emails) emails que receberão notificações sobre a cobrança
received	boolean	(DEPRECATED: use paid_at) indica se a cobrança foi recebida
received_amount	decimal	(DEPRECATED: use paid_amount) valor pago
received_at	datetime	(DEPRECATED: use paid_at) date e horário em que a cobrança foi paga. (Utilize o timezone da configuração de cobrança ao converter para data)
paid_amount	decimal	valor pago
paid_at	datetime	date e horário em que a cobrança foi paga. (Utilize o timezone da configuração de cobrança ao converter para data)
paid_discount	decimal	valor do desconto no momento do pagamento
paid_additions	decimal	valor do juros, multas e encargos no momento do pagamento
paid_rebate	decimal	valor do abatimento no momento do pagamento
payment_tax	decimal	valor taxa cobrada pela instituição financeira para o processamento da cobrança
paid_difference	decimal	diferença entre valor pago e valor cobrando
processing_date	date	data de geração do boleto
for_homologation	boolean	indica se é uma cobrança que foi criada com o objetivo de homologar uma Configuração de cobrança
registrable	boolean	indica se a cobrança é registrável (do tipo que deve ser registrada no banco). Sendo sempre true para Cobranças criadas após 27/10/2018
payer_id	integer	identificador do pagador
payer_national_identifier_type	string	tipo do documento do pagador (cpf ou cnpj)
payer_national_identifier	string	documento do pagador
payer_name	string	nome do pagador
payer_number	string	número do endereço do pagador
payer_complement	string	complemento do endereço do pagador
payer_street	string	rua do endereço do pagador
payer_neighbourhood	string	bairro do endereço do pagador
payer_zipcode	string	cep do endereço do pagador
payer_city	string	cidade do endereço do pagador
payer_state	string	sigla do estado do endereço do pagador (“RJ” por exemplo)
registration_status	string	status de registro em que a cobrança se encontra (without_remittance, remitted, registered, registered_with_error, cancelation_started, canceled)
canceled_at	datetime	data e horário em que a cobrança foi cancelada, se for o caso
available_billet	boolean	indica se o boleto está disponível para download
_links	array of object	links relacionados à cobrança

Cobranças via Gateway de Pagamento

Cada Gateway de Pagamento tem suporte à tipos de cobrança diferentes. Alguns têm suporte à cobranças via boleto, outros não, por exemplo. Em cada tipo de cobrança abaixo é especificado quais Gatways de Pagamento suportam tal tipo de cobrança.

As Cobranças tem o comportamento assíncrono em relação à comunicação com o Gateway de Pagamento. Ou seja, às ações que dependem de efetivação no Gateway de Pagamento não tem resposta na mesma requisição, são feitas em um processo separado e tem suas respostas dadas em payloads via webhook.

Cartão de crédito

Parâmetros

Campo	Tipo	Comentário
id	integer
type	string	indica o tipo da cobrança. Nesse caso, “credit_card”
charge_config_id	integer	identificador da configuração de cobrança a qual esta cobrança pertence
charged_amount	decimal	valor cobrado no boleto
notification_emails	array of strings	emails que receberão notificações sobre a cobrança
payer_emails	array of strings	(DEPRECATED: use notification_emails) emails que receberão notificações sobre a cobrança
payer_id	integer	identificador do pagador
payer_national_identifier_type	string	tipo do documento do pagador (cpf ou cnpj)
payer_national_identifier	string	documento do pagador
payer_name	string	nome do pagador
payer_number	string	número do endereço do pagador
payer_complement	string	complemento do endereço do pagador
payer_street	string	rua do endereço do pagador
payer_neighbourhood	string	bairro do endereço do pagador
payer_zipcode	string	cep do endereço do pagador
payer_city	string	cidade do endereço do pagador
payer_state	string	sigla do estado do endereço do pagador (“RJ” por exemplo)
credit_card_id	integer	identificador do cartão de crédito utilizado na cobrança
description	string	descrição da cobrança
soft_descriptor	string	descritor que irá aparecer na fatura do cartão (no máximo 13 caracteres)
payment_method	string	método de pagamento (1: pagamento à vista, 2: pagamento parcelado)
installments	integer	número de parcelas
for_homologation	boolean	indica se é uma cobrança que foi criada com o objetivo de homologar uma Configuração de cobrança ou um Cartão de Crédito
payment_gateway_status	string	status da cobrança em relação ao gateway de pagamento (pending, authorized, captured, canceled, authorize_error, capture_error, cancel_error)
payment_gateway_message	string	mensagem do gateway de pagamento relacionada ao seu status
canceled_at	datetime	data e horário em que a cobrança foi cancelada, se for o caso. (Utilize o timezone da configuração de cobrança ao converter para data)
_links	array of object	links relacionados à cobrança

Boleto

Parâmetros

Campo	Tipo	Comentário
id	integer
type	string	indica o tipo da cobrança. Nesse caso, “billet”
charge_config_id	integer	identificador da configuração de cobrança a qual esta cobrança pertence
charged_amount	decimal	valor cobrado no boleto
due_date	date	data de vencimento da cobranca
interest_amount_per_month	decimal	porcentagem de juros mensal que deve ser aplicado em caso de atraso. Esse valore será dividido por 30 para ser encontrata a taxa diária
mulct_value	decimal	valor da multa que deve ser aplicada em caso de atraso
discount_amount	decimal	valor do disconto que deve ser aplicado em caso de pagamento até a data de vencimento
payer_id	integer	identificador do pagador
payer_national_identifier_type	string	tipo do documento do pagador (cpf ou cnpj)
payer_national_identifier	string	documento do pagador
payer_name	string	nome do pagador
payer_number	string	número do endereço do pagador
payer_complement	string	complemento do endereço do pagador
payer_street	string	rua do endereço do pagador
payer_neighbourhood	string	bairro do endereço do pagador
payer_zipcode	string	cep do endereço do pagador
payer_city	string	cidade do endereço do pagador
payer_state	string	sigla do estado do endereço do pagador (“RJ” por exemplo)
document_kind	string	espécie do documento
auto_send_billet	boolean	indica se será enviado email de notificação automaticamente para os emails especificados no campo 'notification_emails’
notification_emails	array of strings	emails que receberão notificações sobre a cobrança
email_sender_name	string	nome do remetente do email de notificação de cobrança
email_subject	string	assunto do email de notificação de cobrança
email_text	string	texto do email de notificação de cobrança
email_reply_to	string	endereço de email a ser utilizado na resposta ao email de notificação de cobrança
canceled_at	datetime	data e horário em que a cobrança foi cancelada, se for o caso
available_billet	boolean	indica se o boleto está disponível para download
instructions	string	instruções que serão adicionadas à composição da cobrança
_links	array of object	links relacionados à cobrança

Informações da Cobrança

Mostrar Cobrança

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/charges/:charge_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/charges/:charge_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA (BOLETO)

  {
    "id":1,
    "type":"billet",
    "charge_config_id": 1,
    "due_date":"2015-02-14",
    "document_kind":"DV",
    "document_date":null,
    "document_number":null,
    "custom_our_number": "true",
    "our_number":"0",
    "our_number_digit":null,
    "charged_amount":"10.07",
    "interest_amount_per_month": "1.02",
    "mulct_type": "percentage",
    "mulct_value": "10.12",
    "instructions":"Pagável em qualquer agência até data do vencimento.",
    "demonstrative":"Não receber após o vencimento.",
    "notification_emails":["myemail@gmail.com"],
    "received":true, # deprecated
    "received_amount":"10.07", # deprecated
    "received_at":"2015-01-30T04:00:00Z", # deprecated
    "paid_amount":"10.07",
    "paid_at":"2015-01-30T04:00:00Z",
    "paid_discount":"4.56",
    "paid_additions":"0.50",
    "paid_rebate":"0.30",
    "payment_tax":"2.5",
    "paid_difference":"0",
    "processing_date":"2015-01-30",
    "for_homologation":true,
    "registrable": true,
    "payer_national_identifier_type": "cpf",
    "payer_national_identifier": "12345678909",
    "payer_name": "Jonh Doe",
    "payer_number": "43",
    "payer_complement": "8 andar",
    "payer_street": "Rua do Carmo",
    "payer_neighbourhood": "Centro",
    "payer_zipcode": "22230062",
    "payer_city": "Rio de Janeiro",
    "payer_state": "RJ",
    "registration_status": "without_remittance",
    "canceled_at": "2015-01-31T17:46:01.253Z",
    "available_billet": "false",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/charges/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/charges/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/charges/1"},
        {"rel":"receive","method":"POST","href":"https://app.cobrato.com/api/v1/charges/1/receive"},
        {"rel":"deliver","method":"POST","href":"https://app.cobrato.com/api/v1/charges/1/deliver_billet"},
        {"rel":"charge_config","method":"GET","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"billet","method":"GET","href":"https://app.cobrato.com/api/v1/charges/1/billet"},
        {"rel":"public_billet","method":"GET","href":"https://app.cobrato.com/public/billets/1dac03daed4ab93edd3bb2b25639d33f/download"},
        {"rel":"cancel","method":"POST","href":"https://app.cobrato.com/api/v1/charges/1/cancel"}
      ]
  }

Retorna as informações detalhadas da cobrança informada em JSON e também a referência a sua configuração de cobrança.

Lista de Todas as Cobrança



DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/charges

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/charges

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "charges":
      [
        {
          // informações cobrança 1
        },
        {
          // informações cobrança 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos as cobranças que pertencem a sua Conta de Serviço.

É possível filtrar a lista através dos seguintes parâmetros:

type: Filtra pelo tipo de cobrança. O valor a ser informado é string com um dos tipos existentes de cobrança (“billet” e “credit_card”, sendo que existe “payment_gateway” que está deprecated retornando a mesma coisa que “credit_card”) .
remittable: Filtra as cobranças remessáveis, ou seja, passíveis de geração de arquivo de remessa. É necessária apenas a presença do parâmetro, não importando seu valor.
charge_config_ids: Filtra pelas configurações de cobrança informadas. O valor informado é uma lista* de ids das configurações de cobrança.
payee_ids: Filtra pelos beneficiários informados. O valor informado é uma lista* de ids dos beneficiários.
payee_national_identifiers: Filtra pelos beneficiários informados. O valor informado é uma lista* de número de documentos dos beneficiários.

lista* Os valores em “lista” devem ser enviados da seguinte forma: url?charge_config_ids[]=15&charge_config_ids[]=42.

Criação de Cobrança

Criar Cobrança

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/charges

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/charges \
    -d '{
          "charge_config_id": 1,
          "due_date":"2015-02-14",
          "document_kind":"DV",
          "our_number":"12345678",
          "charged_amount":"10.07",
          "notification_emails":["myemail@gmail.com"]
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "charge_config_id":["não pode ficar em branco"],
        "our_number":["não pode ficar em branco"],
        "charged_amount":["não pode ficar em branco"],
        "due_date":["não pode ficar em branco"]
      }
  }

Cria um nova cobrança, caso haja sucesso retornará as informações da mesma e será gerado seu boleto. Se houverem erros eles serão informados no corpo da resposta.

Cobrança via Conta Bancária

Boleto

Parâmetros

Campo	Tipo	Comentário
charge_config_id	integer	(requerido) código de identificação da configuração de cobrança da qual a cobrança irá pertencer
due_date	date	(requerido) data de vencimento da cobrança
document_kind	string	(opcional) espécie do documento, podendo ser DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória) ou DV (Diversos). Caso não seja informado o valor assumido será “DM”
charged_amount	decimal	(requerido) valor cobrado no boleto
document_number	string	(opcional) número do documento é o número utilizado e controlado pelo beneficiário para identificar o título de cobrança. Caso não seja informado é atribuído automaticamente um valor aleatório de até 10 caracteres. Este valor deve ser único para cobranças feitas pelo Banco Bradesco de mesmo valor cobrado, data de vencimento e configuração de cobrança
notification_emails	array of strings	(opcional - requerido caso `auto_send_billet` seja `true`) emails que receberão notificações sobre a cobrança
payer_emails	array of strings	(DEPRECATED: use notification_emails) (opcional - requerido caso `auto_send_billet` seja `true`) emails que receberão notificações sobre a cobrança
document_date	date	(opcional) data de emissão do documento
our_number	string	(opcional) nosso número. Caso não informado, é atribuído automaticamente pelo sistema
our_number_digit	integer	(opcional) digito do verificador do nosso número
custom_our_number	boolean	(opcional) indica se a cobrança utiliza um “nosso número” customizado. O valor padrão é false, mas caso definido true, o campo 'our_number’ se torna requerido
interest_amount_per_month	decimal	(opcional) porcentagem de juros mensal que deve ser aplicado em caso de atraso. No boleto será mostrado o valor diário de juros que será calculado
mulct_type	string	(opcional) indica o tipo de multa que deve ser aplicada em caso de atraso (“percentage” para porcentagem, “currency” para valor em reais)
mulct_value	decimal	(opcional) valor da multa que deve ser aplicada em caso de atraso, com base em seu tipo
instructions	string	(opcional) instruções de pagamento do boleto. As linhas devem ser separadas por “\n”. Deve ter no máximo 9 linhas com 65 caracteres cada, sendo que se tiver definido multa e juros para a cobrança, será permitido no máximo 6 linhas, pois 3 já serão utilizadas automaticamente.
demonstrative	string	(opcional) demonstrativo do Boleto. As linhas devem ser separadas por “\n”. Deve ter no máximo 9 linhas com 65 caracteres cada, sendo que se tiver definido multa e juros para a cobrança, será permitido no máximo 6 linhas, pois 3 já serão utilizadas automaticamente.
charge_template_id	integer	(opcional) número do modelo de cobrança a ser utilizado. A cobrança será criada com base nos atributos preestabelecidos do modelo. Contudo, os valores enviados na criação terão preferência
for_homologation	boolean	(requerido, se a configuração de cobrança não estiver homologada) indica se é uma cobrança para ser utilizada na homologação da Configuração de cobrança
payer_id	integer	(requerido, se não enviar payer_attributes) identificador do pagador (caso seja fornecido, o parâmetro payer_attributes será ignorado)
payer_attributes*	object	(requerido, se não enviar payer_id) atributos para a criação de um novo pagador ou atualização de um pagador existente com o mesmo documento (national_identifier)
auto_send_billet	boolean	(opcional) Indica se será enviado email de notificação automaticamente para os emails especificados no campo 'notification_emails’. Caso não seja informada assumirá valor 'false’
email_sender_name	string	(opcional) Nome do remetente do email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
email_subject	string	(opcional) Assunto do email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
email_text	string	(opcional) Texto do email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
email_reply_to	string	(opcional) Endereço de email a ser utilizado na resposta ao email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’

payer_attributes

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do pagador (cpf ou cnpj)
national_identifier	string	(requerido) documento do pagador
name	string	(requerido) nome do pagador
number	string	(requerido) número do endereço do pagador
complement	string	(requerido) complemento do endereço do pagador
street	string	(requerido) rua do endereço do pagador
neighbourhood	string	(requerido) bairro do endereço do pagador
zipcode	string	(requerido) cep do endereço do pagador
city	string	(requerido) cidade do endereço do pagador
state	string	(requerido) sigla do estado do endereço do pagador (“RJ” por exemplo)

Cobranças via Gateway de Pagamento

Cobranças via gateway de pagamento podem ser de vários tipos, como Boleto e Cartão de crédito. Desse modo, quando for criar uma cobrança via gateway de pagamento, deve ser indicado o tipo através do atributo type. Por padrão, esse atributo terá o valor "credit_card".

É importante ressaltar que os tipos de cobrança disponíveis dependem do gateway de pagamento utilizado e da configuração de cobrança.

Após a cobrança ser criada com sucesso (sem erros de validação) é iniciado o processo assíncrono para a comunicação com o gateway. Assim que esse processo terminar, um payload de atualização ou de erro é enviado via webhook.

Cartão de crédito

Se for utilizado um cartão já existente (enviando o parâmetro credit_card_id), este deve pertencer a mesma Configuração de Cobrança (parâmetro charge_config_id) utilizada.

Parâmetros

Campo	Tipo	Comentário
charge_config_id	integer	(requerido) código de identificação da configuração de cobrança da qual a cobrança irá pertencer
charged_amount	decimal	(requerido) valor cobrado
payment_method	string	(requerido) método de pagamento (“credit_card_in_cash” pagamento à vista, “credit_card_financed” pagamento parcelado)
type	string	(requerido) tipo da cobrança, nesse caso deve ser “credit_card”
description	string	(opcional) descrição da cobrança
soft_descriptor	string	(opcional) descritor que irá aparecer na fatura do cartão (no máximo 13 caracteres)
installments	integer	(opcional) número de parcelas (1 por padrão)
generate_token	boolean	(opcional) indica se deve ser gerado token para utilização do cartão de crédito no pagamento recorrente (false por padrão)
notification_emails	array of strings	(opcional - requerido caso `auto_send_billet` seja `true`) emails que receberão notificações sobre a cobrança
payer_emails	array of strings	(DEPRECATED: use notification_emails) (opcional - requerido caso `auto_send_billet` seja `true`) emails que receberão notificações sobre a cobrança
payer_id	integer	(requerido, se não enviar payer_attributes) identificador do pagador (caso seja fornecido, o parâmetro payer_attributes será ignorado)
payer_attributes*	object	(requerido, se não enviar payer_id) atributos para a criação de um novo pagador ou atualização de um pagador existente com o mesmo documento (national_identifier)
credit_card_id	integer	(requerido, se não enviar credit_card_attributes) identificador do cartão de crédito utilizado na cobrança, que deve pertencer ao mesmo payer e charge_config informados
credit_card_attributes*	object	(requerido, se não enviar credit_card_id) atributos para a criação de um novo cartão de crédito que será ligado ao pagador
overwrite_card_payer	boolean	(opcional) indica se o pagador dono do cartão deve ser alterado para o pagador informado

payer_attributes

Caso exista um Pagador (Person) com o mesmo national_identifier, não será criado um novo, mas sim atualizado o existente.

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do pagador (cpf ou cnpj)
national_identifier	string	(requerido) documento do pagador
name	string	(requerido) nome do pagador
number	string	(opcional) número do endereço do pagador
complement	string	(opcional) complemento do endereço do pagador
street	string	(opcional) rua do endereço do pagador
neighbourhood	string	(opcional) bairro do endereço do pagador
zipcode	string	(opcional) cep do endereço do pagador
city	string	(opcional) cidade do endereço do pagador
state	string	(opcional) sigla do estado do endereço do pagador (“RJ” por exemplo)

credit_card_attributes

Campo	Tipo	Comentário
token	string	(requerido) token do cartão
national_identifier	string	(requerido) cpf do portador do cartão
number	string	(requerido) número mascarado do cartão
cvv	string	(requerido) código de segurança
expiration	string	(requerido) expiração do cartão, no formato “mm/aa” ou “mm/aaaa”
holder_name	string	(requerido) nome do dono do cartão
brand	string	(requerido) bandeira do cartão (visa, mastercard, amex, elo, diners, discover, jcb, aura)
avs_address	string	(opcional) endereço de cobrança do cartão
avs_number	string	(opcional) número do endereço de cobrança do cartão
avs_complement	string	(opcional) complemento endereço de cobrança do cartão
avs_district	string	(opcional) bairro do endereço de cobrança do cartão
avs_zipcode	string	(opcional) cep do endereço de cobrança do cartão
created_as_reusable	boolean	(opcional) indica se o cartão de crédito deve ser salvo de modo que possa ser re-utilizado futuramente em novas cobranças desde mesmo pagador e configuração de cobrança (false por padrão)

Boleto

Parâmetros

Campo	Tipo	Comentário
type	string	(requerido) tipo da cobrança, nesse caso deve ser “billet”
charge_config_id	integer	(requerido) código de identificação da configuração de cobrança da qual a cobrança irá pertencer
charged_amount	decimal	(requerido) valor cobrado
due_date	date	(requerido) data de vencimento da cobrança
payer_id	integer	(requerido, se não enviar payer_attributes) identificador do pagador (caso seja fornecido, o parâmetro payer_attributes será ignorado)
payer_attributes*	object	(requerido, se não enviar payer_id) atributos para a criação de um novo pagador ou atualização de um pagador existente com o mesmo documento (national_identifier)
document_kind	string	(opcional) espécie do documento, podendo ser DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória), LC (Letra de Cambio) ou RC (Recibo). Caso não seja informado o valor assumido será “DM”.
interest_amount_per_month	decimal	(opcional) porcentagem de juros mensal que deve ser aplicado em caso de atraso. Esse valore será dividido por 30 para ser encontrata a taxa diária
mulct_value	decimal	(opcional) porcentagem de multa que deve ser aplicada em caso de atraso
discount_amount	decimal	(opcional) valor do disconto que deve ser aplicado em caso de pagamento até a data de vencimento
auto_send_billet	boolean	(opcional) Indica se será enviado email de notificação automaticamente para os emails especificados no campo 'notification_emails’. Caso não seja informada assumirá valor 'false’
notification_emails	array of strings	(opcional - requerido caso `auto_send_billet` seja `true`) emails que receberão notificações sobre a cobrança
email_sender_name	string	(opcional) Nome do remetente do email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
email_subject	string	(opcional) Assunto do email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
email_text	string	(opcional) Texto do email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
email_reply_to	string	(opcional) Endereço de email a ser utilizado na resposta ao email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
instructions	string	(opcional) instruções que serão adicionadas à composição da cobrança. Devem ter no máximo 528 caracteres.

payer_attributes

Caso exista um Pagador (Payer) com o mesmo national_identifier, não será criado um novo, mas sim atualizado o existente.

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do pagador (cpf ou cnpj)
national_identifier	string	(requerido) documento do pagador
name	string	(requerido) nome do pagador
number	string	(opcional) número do endereço do pagador
complement	string	(opcional) complemento do endereço do pagador
street	string	(opcional) rua do endereço do pagador
neighbourhood	string	(opcional) bairro do endereço do pagador
zipcode	string	(opcional) cep do endereço do pagador
city	string	(opcional) cidade do endereço do pagador
state	string	(opcional) sigla do estado do endereço do pagador (“RJ” por exemplo)

Atualização de Cobrança

Atualizar Cobrança

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/charges/:charge_id
  PATCH https://app.cobrato.com/api/v1/charges/:charge_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/charges/:charge_id \
    -d '{
          "document_date":"2015-02-02",
          "document_number":"123456789",
          "notification_emails":["myemail@gmail.com"]
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {"document_kind":["não está incluído na lista"]}
  }

Atualiza a cobrança determinada, caso haja sucesso retornará as informações da mesma. Se houverem erros eles serão informados no corpo da resposta. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Cobranças via Conta Bancária

Boleto

Parâmetros

Campo	Tipo	Comentário
due_date	date	(requerido) data de vencimento da cobrança
document_kind	string	(opcional) espécie do documento, podendo ser DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória) ou DV (Diversos). Caso não seja informado o valor assumido será “DM”.
charged_amount	decimal	(requerido) valor cobrado no boleto
document_number	string	(opcional) número do documento é o número utilizado e controlado pelo beneficiário para identificar o título de cobrança. Caso não seja informado é atribuído automaticamente um valor aleatório de até 10 caracteres. Este valor deve ser único para cobranças feitas pelo Banco Bradesco de mesmo valor cobrado, data de vencimento e configuração de cobrança
notification_emails	array of strings	(opcional) emails que receberão notificações sobre a cobrança
payer_emails	array of strings	(opcional) (DEPRECATED: use notification_emails) emails que receberão notificações sobre a cobrança
document_date	date	(opcional) data de emissão do documento
our_number	string	(opcional) nosso número. Caso não informado, é atribuído automaticamente pelo sistema
our_number_digit	integer	(opcional) digito do verificador do nosso número
custom_our_number	boolean	(opcional) indica se a cobrança utiliza um “nosso número” customizado. O valor padrão é false, mas caso definido true, o campo 'our_number’ se torna requerido
interest_amount_per_month	decimal	(opcional) porcentagem de juros mensal que deve ser aplicado em caso de atraso. No boleto será mostrado o valor diário de juros que será calculado
mulct_type	string	(opcional) indica o tipo de multa que deve ser aplicada em caso de atraso (“percentage” para porcentagem, “currency” para valor em reais)
mulct_value	decimal	(opcional) valor da multa que deve ser aplicada em caso de atraso, com base em seu tipo
instructions	string	(opcional) instruções de pagamento do boleto. As linhas devem ser separadas por “\n”. Deve ter no máximo 9 linhas com 65 caracteres cada, sendo que se tiver definido multa e juros para a cobrança, será permitido no máximo 6 linhas, pois 3 já serão utilizadas automaticamente.
demonstrative	string	(opcional) demonstrativo do Boleto. As linhas devem ser separadas por “\n”. Deve ter no máximo 9 linhas com 65 caracteres cada, sendo que se tiver definido multa e juros para a cobrança, será permitido no máximo 6 linhas, pois 3 já serão utilizadas automaticamente.
payer_id	integer	(requerido, se não enviar payer_attributes) identificador do pagador (caso seja fornecido, o parâmetro payer_attributes será ignorado)
payer_attributes*	object	(requerido, se não enviar payer_id) atributos para a criação de um novo pagador ou atualização de um pagador existente com o mesmo documento (national_identifier)

payer_attributes

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do pagador (cpf ou cnpj)
national_identifier	string	(requerido) documento do pagador
name	string	(requerido) nome do pagador
number	string	(requerido) número do endereço do pagador
complement	string	(requerido) complemento do endereço do pagador
street	string	(requerido) rua do endereço do pagador
neighbourhood	string	(requerido) bairro do endereço do pagador
zipcode	string	(requerido) cep do endereço do pagador
city	string	(requerido) cidade do endereço do pagador
state	string	(requerido) sigla do estado do endereço do pagador (“RJ” por exemplo)

Cobranças via Gateway de Pagamento

Uma cobrança com o status de erro no gateway de pagamento pode ser editada com o objetivo de corrigir este error (descrito no atributo 'payment_gateway_message’). Sendo atualizada com sucesso, é feita uma re-tentativa de efetivação da cobrança no gateway de pagamento.

Cartão de crédito

Parâmetros

Campo	Tipo	Comentário
charged_amount	decimal	(requerido) valor cobrado no boleto
payment_method	string	(requerido) método de pagamento (1: pagamento à vista, 2: pagamento parcelado)
description	string	(opcional) descrição da cobrança
soft_descriptor	string	(opcional) descritor que irá aparecer na fatura do cartão (no máximo 13 caracteres)
installments	integer	(opcional) número de parcelas (1 por padrão)
generate_token	boolean	(opcional) indica se deve ser gerado token para utilização do cartão de crédito no pagamento recorrente (false por padrão)
notification_emails	array of strings	(opcional) emails que receberão notificações sobre a cobrança
payer_emails	array of strings	(opcional) (DEPRECATED: use notification_emails) emails que receberão notificações sobre a cobrança
payer_id	integer	(requerido, se não enviar payer_attributes) identificador do pagador (caso seja fornecido, o parâmetro payer_attributes será ignorado)
payer_attributes*	object	(requerido, se não enviar payer_id) atributos para a criação de um novo pagador ou atualização de um pagador existente com o mesmo documento (national_identifier)
credit_card_id	integer	(requerido, se não enviar credit_card_attributes) identificador do cartão de crédito utilizado na cobrança
credit_card_attributes*	object	(requerido, se não enviar credit_card_id) atributos para a criação de um novo cartão de crédito que será ligado ao pagador
overwrite_card_payer	boolean	(opcional) indica se o pagador dono do cartão deve ser alterado para o pagador informado

payer_attributes

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do pagador (cpf ou cnpj)
national_identifier	string	(requerido) documento do pagador
name	string	(requerido) nome do pagador
number	string	(opcional) número do endereço do pagador
complement	string	(opcional) complemento do endereço do pagador
street	string	(opcional) rua do endereço do pagador
neighbourhood	string	(opcional) bairro do endereço do pagador
zipcode	string	(opcional) cep do endereço do pagador
city	string	(opcional) cidade do endereço do pagador
state	string	(opcional) sigla do estado do endereço do pagador (“RJ” por exemplo)

credit_card_attributes

Campo	Tipo	Comentário
token	string	(requerido) token do cartão
national_identifier	string	(requerido) cpf do portador do cartão
number	string	(requerido) número mascarado do cartão
cvv	string	(requerido) código de segurança
expiration	string	(requerido) expiração do cartão, no formato “mm/aa” ou “mm/aaaa”
holder_name	string	(requerido) nome do dono do cartão
brand	string	(requerido) bandeira do cartão (visa, mastercard, amex, elo, diners, discover, jcb, aura)
avs_address	string	(opcional) endereço de cobrança do cartão
avs_number	string	(opcional) número do endereço de cobrança do cartão
avs_complement	string	(opcional) complemento endereço de cobrança do cartão
avs_district	string	(opcional) bairro do endereço de cobrança do cartão
avs_zipcode	string	(opcional) cep do endereço de cobrança do cartão
created_as_reusable	boolean	(opcional) indica se o cartão de crédito deve ser salvo de modo que possa ser re-utilizado futuramente em novas cobranças desde mesmo pagador e configuração de cobrança (false por padrão)

Boleto

Parâmetros

Campo	Tipo	Comentário
charged_amount	decimal	(requerido) valor cobrado
due_date	date	(requerido) data de vencimento da cobrança
payer_id	integer	(requerido, se não enviar payer_attributes) identificador do pagador (caso seja fornecido, o parâmetro payer_attributes será ignorado)
payer_attributes*	object	(requerido, se não enviar payer_id) atributos para a criação de um novo pagador ou atualização de um pagador existente com o mesmo documento (national_identifier)
document_kind	string	(opcional) espécie do documento, podendo ser DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória), LC (Letra de Cambio) ou RC (Recibo)
interest_amount_per_month	decimal	(opcional) porcentagem de juros mensal que deve ser aplicado em caso de atraso. Esse valore será dividido por 30 para ser encontrata a taxa diária
mulct_value	decimal	(opcional) porcentagem de multa que deve ser aplicada em caso de atraso
discount_amount	decimal	(opcional) valor do disconto que deve ser aplicado em caso de pagamento até a data de vencimento
auto_send_billet	boolean	(opcional) Indica se será enviado email de notificação automaticamente para os emails especificados no campo 'notification_emails’. Caso não seja informada assumirá valor 'false’
notification_emails	array of strings	(opcional - requerido caso `auto_send_billet` seja `true`) emails que receberão notificações sobre a cobrança
email_sender_name	string	(opcional) Nome do remetente do email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
email_subject	string	(opcional) Assunto do email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
email_text	string	(opcional) Texto do email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
email_reply_to	string	(opcional) Endereço de email a ser utilizado na resposta ao email de notificação de cobrança, caso a opção auto_send_billet estiver com valor 'true’
instructions	string	(opcional) instruções que serão adicionadas à composição da cobrança. Devem ter no máximo 528 caracteres.

payer_attributes

Caso exista um Pagador (Payer) com o mesmo national_identifier, não será criado um novo, mas sim atualizado o existente.

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do pagador (cpf ou cnpj)
national_identifier	string	(requerido) documento do pagador
name	string	(requerido) nome do pagador
number	string	(opcional) número do endereço do pagador
complement	string	(opcional) complemento do endereço do pagador
street	string	(opcional) rua do endereço do pagador
neighbourhood	string	(opcional) bairro do endereço do pagador
zipcode	string	(opcional) cep do endereço do pagador
city	string	(opcional) cidade do endereço do pagador
state	string	(opcional) sigla do estado do endereço do pagador (“RJ” por exemplo)

Re-tentativa de efetivar de Cobrança (Cartão de crédito)

Re-tentativa de efetivação de Cobrança

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/charges/:charge_id/retry
  PATCH https://app.cobrato.com/api/v1/charges/:charge_id/retry

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/charges/:charge_id/retry

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {"message":["Esta Cobrança não suporta retentativa"]}
  }

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

Quando uma Cobrança do tipo Gateway de Pagamento tem um erro que não necessita correção (atualização) da mesma, é possível fazer uma re-tentativa de efetivação dessa Cobrança.

Exclusão de Cobrança

Excluir Cobrança

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/charges/:charge_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/charges/:charge_id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

Exclui determinada cobrança. As mudanças são irreversíveis, e não será mais possível receber o boleto da cobrança excluída!

Uma cobrança poderá ser excluída nos seguintes casos:

Cartão de crédito

Somente quando a cobrança estiver com erro de autorização (payment_gateway_status tiver o valor “authorize_error”).

Boleto via Gateway de pagamento

Somente quando a cobrança estiver com erro de criação (payment_gateway_status tiver o valor “error_on_creation”).

Boleto via Conta Bancária

Para boletos sem registro a cobrança pode ser excluída enquanto não tiver sido recebida.

Para boletos com registro, por sua vez, enquanto não tiver sido recebida e enquanto não tiver sido registrada (registration_status diferente de “registered”).

Recebimento de Cobrança (Boleto via Conta Bancária)

Receber Cobrança (Boleto)

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/charges/:charge_id/receive

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/charges/:charge_id/receive \
    -d '{
         "paid_at": "2015-02-06",
         "paid_amount": "9.57",
         "paid_discount": "4.56",
         "paid_additions": "0.50",
         "paid_rebate":  "0.30",
         "payment_tax": "2.5"
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "paid_at": ["não pode ficar em branco"],
      "paid_amount": ["não pode ficar em branco"]
    }
  }

Marca determinada cobrança via Boleto como recebida, retornando JSON contendo as informações da cobrança em caso de sucesso ou os erros, caso haja algum.

Parâmetros (Boleto)

Campo	Tipo	Comentário
received_amount	decimal	(requerido) (DEPRECATED: use paid_amount) valor pago
received_at	datetime	(requerido) (DEPRECATED: use paid_at) date e horário em que a cobrança foi paga
paid_amount	decimal	(requerido) valor pago
paid_at	datetime	(requerido) date e horário em que a cobrança foi paga
paid_discount	decimal	(optional) valor do desconto
paid_additions	decimal	(optional) valor do juros, multa e encargos
paid_rebate	decimal	(optional) valor do abatimento
payment_tax	decimal	(opcional) valor taxa cobrada pela instituição financeira para o processamento da cobrança

Desfazer Recebimento de Cobrança (Boleto via conta Bancária)

Desfazer Recebimento de Cobrança (Boleto)

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/charges/:charge_id/undo_receive

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/charges/:charge_id/undo_receive

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "paid_amount": [
        "Impossível cancelar o recebimento de uma cobrança não recebida!"
      ]
    }
  }

Marca determinada cobrança via Boleto como não recebida, retornando JSON contendo as informações da cobrança em caso de sucesso ou os erros, caso haja algum.

Renovação de Cobrança (Boleto via conta Bancária)

Renovar Cobrança (Boleto)

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/charges/:charge_id/renew
  PATCH https://app.cobrato.com/api/v1/charges/:charge_id/renew

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PUT https://app.cobrato.com/api/v1/charges/:charge_id/renew \
    -d '{
         "new_due_date": "2015-02-06"
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "due_date": ["não pode ficar em branco"]
    }
  }

Atualiza a data de vencimento do boleto bancário. É importante ressaltar que é necessária a criação e envio de um novo arquivo de remessa para efetivar a renovação junto ao banco.

A renovação só será permitida caso a cobrança seja do tipo registrada e já esteja registrada junto ao banco. Caso contrário, é possível renovar editando a data de vencimento da cobrança.

Retorna um JSON contento informações atualizadas da cobrança em caso de sucesso ou erros caso haja algum.

Parâmetros (Boleto)

Campo	Tipo	Comentário
new_due_date	date	(requerido) nova data de vencimento da cobrança

Boleto da Cobrança (Boleto via Gateway e Conta Bancária)

Mostrar Boleto da Cobrança (URL)

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/charges/:charge_id/billet

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/charges/:charge_id/billet

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE CORPO DA RESPOSTA COM SUCESSO

  {
    "url":"https://cobrato-uploads.s3.amazonaws.com/billets/1/6186_08033_1445001056.pdf?Expires=1445034829"
  }

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "message": "O boleto bancário para esta cobrança ainda não está disponível. Se sua cobrança é registrada você precisa registrar essa cobrança enviando o arquivo de remessa para seu banco."
    }
  }

Mostra o link da url do boleto de determinada cobrança via Boleto

Envio de Boleto da Cobrança (Boleto via Gateway e Conta Bancária)

Enviar Boleto da Cobrança

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/charges/:charge_id/deliver_billet

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/charges/:charge_id/deliver_billet \
    -d '{
         "to": ["email1@host.com","email1@host.com"]
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM EMAIL NÃO CADASTRADO E NÃO INFORMADO

      422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "notification_emails": ["não pode ficar em branco"]
    }
  }

Envia o boleto da cobrança por email, gerando o mesmo caso necessário. É enviado para os emails informados, ou então os cadastrados na cobrança.

Parâmetros

Campo	Tipo	Comentário
to	array of string	(requerido) emails que receberão o boleto ao invés dos emails cadastrados na cobrança

Cancelar cobrança

Cancela Cobrança

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/charges/:charge_id/cancel

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/charges/:charge_id/cancel

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "message": "Esta Cobrança não pode ser cancelada"
    }
  }

Cancela determinada cobrança.

Cartão de crédito

Neste caso o cancelamento irá estornar o valor cobrado para o cliente.

A cobrança poderá ser cancelada somente quando tiver sido autorizada, capturada ou com erro no cancelamento (payment_gateway_status tiver um dos seguintes valores: “authorized”, “captured”, ou “cancel_error”).

Boleto via Gateway

Neste caso o cancelamento irá invalidar a cobrança, não permitindo mais o seu pagamento.

A cobrança poderá ser cancelada somente quando ainda não tiver sido paga ou já tiver tido uma tentativa de cancelamento com erro (payment_gateway_status tiver o valor “error_on_cancelation”).

Boleto via Conta Bancária

Para boletos sem registro, a cobrança pode ser cancelada enquanto não tiver sido recebida.

Para boletos com registro, por sua vez, enquanto não tiver sido recebida e tiver sido registrada ou não tiver arquivo de remessa (registration_status com um dos valores: “registered” ou “without_remittance”). Após ser cancelada no Cobrato será necessário criar um arquivo de remessa para notificar o Banco do cancelamento da cobrança.

Revogar Cobrança

Revogar Cobrança

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/charges/:charge_id/revoke

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/charges/:charge_id/revoke

EXEMPLO DE ESTADO DA RESPOSTA EXCLUÍDA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA CANCELADA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "message": "Esta Cobrança não pode ser excluída nem cancelada"
    }
  }

Primeiro tenta excluir a cobrança. Caso não seja possível, tenta cancelá-la. Caso também não seja possível, retorna a resposta de insucesso.

Configuração de Pagamento

Configuração de Pagamento

EXEMPLO

  {
    "id": 1,
    "bank_account_id": 1,
    "name": "Configuração de Pagamento",
    "timezone": "Brasilia",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/payment_configs/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/payment_configs/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/payment_configs/1"},
        {"rel":"bank_account","method":"GET","href":"https://app.cobrato.com/api/v1/bank_accounts/1"}
      ]
  }

Informações da Configuração de Pagamento

Mostrar Configuração de Pagamento

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payment_configs/:payment_config_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payment_configs/:payment_config_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id": 1,
    "bank_account_id": 1,
    "name": "Configuração de Pagamento",
    "timezone": "Brasilia",
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/payment_configs/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/payment_configs/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/payment_configs/1"},
        {"rel":"bank_account","method":"GET","href":"https://app.cobrato.com/api/v1/bank_accounts/1"}
      ]
  }

Retorna as informações detalhadas da Configuração de Pagamento informada em JSON e também suas referências.

Lista de Todas as Configurações de Pagamento

Listar Configurações de Pagamento

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payment_configs

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payment_configs

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "payment_configs":
      [
        {
          // informações configuração de pagamento 1
        },
        {
          // informações configuração de pagamento 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todas as Configurações de Pagamento que pertencem a sua Conta de Serviço.

Criação de Configuração de Pagamento

Criar Configuração de Pagamento

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/payment_configs

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/payment_configs \
    -d '{
          "bank_account_id": "1",
          "name": "Configuração de Pagamento"
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "bank_account_id":["não pode ficar em branco"],
        "name":["não pode ficar em branco"]
      }
  }

Cria uma nova Configuração de Pagamento, retornando as informações da mesma em caso de sucesso. Se houverem erros eles serão informados no corpo da resposta.

Parâmetros

Campo	Tipo	Comentário
bank_account_id	integer	(requerido) código de identificação da conta bancária em que a configuração de pagamento irá pertencer
name	string	(requerido) nome que identifica esta configuração de pagamento

Atualização de Configuração de Pagamento

Atualizar Configuração de Pagamento

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/payment_configs/:payment_config_id
  PATCH https://app.cobrato.com/api/v1/payment_configs/:payment_config_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/payent_configs/:payent_config_id \
    -d '{
          "name": "Novo Nome"
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM CONFIGURAÇÃO DE PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "name": ["não pode ficar em branco"]
      }
  }

Atualiza a Configuração de Pagamento determinada, retornando as informações da mesma em caso de sucesso. Se houverem erros, eles serão informados no corpo da resposta. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Parâmetros

Campo	Tipo	Comentário
name	string	(requerido) nome que identifica esta configuração de pagamento

Exclusão de Configuração de Pagamento

Excluir Configuração de Pagamento

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/payment_configs/:payment_config_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/payment_configs/:payment_config_id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM CONFIGURAÇÃO DE PAGAMENTO INEXISTENTE

    404 Not Found

Exclui determinada Configuração de Pagamento. As mudanças são irreversíveis.

Métodos de pagamento

Lista de todos os Métodos de Pagamento

Listar Métodos de Pagamento

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payment_methods

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payment_methods

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "payment_methods":
      [
        { 
          "identifier": 'credit_other_ownership',
          "group": 'transfer',
          "label": 'Crédito em conta Corrente - Outra titularidade' 
        },
        { 
          // informações de outro método 
        },
        ...
      ]
  }

Retorna um objeto JSON contendo todos os Métodos de Pagamento possíveis.

Pagamento

Pagamentos

EXEMPLO

  {
    "id": 10,
    "amount": "456.78",
    "date": "2017-12-07",
    "our_number": null,
    "payment_method": "ted_same_ownership",
    "payment_type": "benefit",
    "account": "12345",
    "account_digit": "9",
    "agency": "4321",
    "bank_code": "033",
    "doc_goal": null,
    "payee_document": "123.456.789-09",
    "payee_name": "John Doe",
    "ted_goal": "00300",
    "_links": [
      { "rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/payments/10" },
      { "rel": "update", "method": "PUT", "href": "https://app.cobrato.com/api/v1/payments/10" },
      { "rel": "destroy", "method": "DELETE", "href": "https://app.cobrato.com/api/v1/payments/10" },
      { "rel": "payment_config", "method": "GET", "href": "https://app.cobrato.com/api/v1/payment_configs/1" }
    ]
  }

Parâmetros

Campo	Tipo	Comentário
payment_config_id	integer	código de identificação da configuração de pagamento à qual o pagamento irá pertencer
amount	decimal	valor do pagamento
date	date	data do pagamento
payment_method	string	forma de pagamento (‘credit_other_ownership’, 'credit_same_ownership’, 'credit_savings_account’, 'doc_other_ownership’, 'doc_same_ownership’, 'ted_other_ownership’, 'ted_same_ownership’, 'dealership’, 'billet_same_bank’, 'billet_other_bank’, 'gps’, 'darf’, 'das’, 'ipva’, 'icms_sp’, 'dpvat’, 'fgts’)
payment_type	string	tipo de pagamento. Os possíveis valores variam de acordo com o “payment_method” (vide tabela 1)
bank_code	string	código de 3 dígitos do banco da conta bancária para o pagamento
account	string	número da conta bancária para o pagamento
account_digit	string	dígito da conta bancária para fazer o pagamento
agency	string	número da agência da conta bancária para fazer o pagamento
payee_id	integer	identificador do beneficiário
payee_name	string	nome do beneficiário
payee_document_type	string	tipo do documento do beneficiário
payee_document	string	número do documento do beneficiário
doc_goal	string	código referente ao objetivo do DOC. Possíveis valores na tabela 2
ted_goal	string	código referente ao objetivo do TED. Possíveis valores na tabela 3
our_number	string	número que identifica o pagamento no banco
gps_payment_code	string	código do GPS, de 4 dígitos
competency_month	string	mês de competência do GPS, repesentado por 2 dígitos
competency_year	string	ano de competência do GPS, repesentado por 4 dígitos
other_entities_amount	decimal	valor extra para outras entidades
monetary_update	decimal	atualização monetária, incluindo valores de juros e multa
discount_amount	decimal	valor do desconto
barcode	string	código de barras
due_date	date	data de vencimento
taxpayer_document_type	string	Tipo do documento do contribuinte
taxpayer_document	string	Número do documento do contribuinte
registration_status	string	status de registro do pagamento ('without_remittance’, 'remitted’, 'registered’, 'canceled’, 'edit_amount_started’, 'reschedule_started’, 'registered_with_error’, 'cancelation_started’, 'canceled_awaiting_confirmation’, 'amount_edited_awaiting_confirmation’, 'rescheduled_awaiting_confirmation’, 'unauthorized’)
note	string	Oberservação do pagamento

Informações do Pagamento

Mostrar Pagamento

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payments/:payment_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payments/:payment_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id": 10,
    "amount": "456.78",
    "date": "2017-12-07",
    "our_number": null,
    "payment_method": "ted_same_ownership",
    "payment_type": "benefit",
    "account": "12345",
    "account_digit": "9",
    "agency": "4321",
    "bank_code": "033",
    "doc_goal": null,
    "payee_document": "123.456.789-09",
    "payee_name": "John Doe",
    "ted_goal": "00300",
    "note": "Pagamento feito para outra conta",
    "_links": [
      { "rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/payments/10" },
      { "rel": "update", "method": "PUT", "href": "https://app.cobrato.com/api/v1/payments/10" },
      { "rel": "destroy", "method": "DELETE", "href": "https://app.cobrato.com/api/v1/payments/10" },
      { "rel": "payment_config", "method": "GET", "href": "https://app.cobrato.com/api/v1/payment_configs/1" }
    ]
  }

Retorna em JSON as informações detalhadas do Pagamento informado e também suas referências.

Lista de todos os Pagamentos

Listar Pagamentos

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payments

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payments

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "payments":
      [
        {
          // informações pagamento 1
        },
        {
          // informações pagamento 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos os Pagamentos que pertencem a sua Conta de Serviço.

Criação de Pagamento

Criar Pagamento

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/payments

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/payments \
    -d '{
          "payment_config_id": "1",
          "payment_type": "provider",
          "payment_method": "ted_other_ownership",
          "date": "2017-10-22",
          "amount": "255.99",
          "bank_code": "341",
          "agency": "9358",
          "account": "21500",
          "account_digit": "3",
          "payee_document_type": "cpf",
          "payee_document": "123.456.789-09",
          "payee_name": "Jane Doe"
          "note": "Pagamento para fornecedores",
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "payment_config_id":["não pode ficar em branco"],
        "payment_type":["não pode ficar em branco"]
      }
  }

Cria um novo Pagamento, retornando as informações do mesmo em caso de sucesso. Se houverem erros eles serão informados no corpo da resposta.

Parâmetros comuns à todas as formas de pagamento

Campo	Tipo	Comentário
payment_config_id	integer	(requerido) código de identificação da configuração de pagamento à qual o pagamento irá pertencer
payment_method	string	(requerido) forma de pagamento ('credit_other_ownership’, 'credit_same_ownership’, 'credit_savings_account’, 'doc_other_ownership’, 'doc_same_ownership’, 'ted_other_ownership’, 'ted_same_ownership’, 'gps’, 'darf’, 'das’, 'ipva’, icms_sp’, 'dpvat’)
amount	decimal	(requerido) valor do pagamento
date	date	(requerido) data do pagamento
note	string	(opcional) oberservação do pagamento
payee_name	string	(opcional) nome do beneficiário

Transferências (DOC, TED, Crédito)

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros comuns aos pagamentos via transferência, além de alguns espefíficos para cada tipo de transferência.

Parâmetros comuns à todos os pagamentos via transferência

Campo	Tipo	Comentário
account	string	(requerido) número da conta bancária para o pagamento
account_digit	string	(requerido) dígito da conta bancária para fazer o pagamento
agency	string	(requerido) número da agência da conta bancária para fazer o pagamento
payee_id	string	(requerido, se não enviar payee) identificador do beneficiário (caso seja fornecido, o parâmetro `payee` será ignorado)
payee*	object	(requerido, se não enviar payee_id) atributos para a criação de um novo beneficiário ou atualização de um beneficiário existente com o mesmo documento (national_identifier)
payment_type	string	(requerido) tipo de pagamento. Os possíveis valores variam de acordo com o “payment_method” (vide tabela 1)

Parâmetros quando payment_method é 'doc_other_ownership’ ou 'doc_same_ownership’

Campo	Tipo	Comentário
bank_code	string	(requerido) código de 3 dígitos do banco da conta bancária para o pagamento
payment_type	string	(requerido) tipo de pagamento. Os possíveis valores variam de acordo com o “payment_method” (vide tabela 1)
doc_goal	string	(opcional) código referente ao objetivo do DOC. Possíveis valores na tabela 2

Parâmetros quando payment_method é 'ted_other_ownership’

Campo	Tipo	Comentário
bank_code	string	(requerido) código de 3 dígitos do banco da conta bancária para o pagamento
payment_type	string	(requerido) tipo de pagamento. Os possíveis valores variam de acordo com o “payment_method” (vide tabela 1)
ted_goal	string	(opcional) código referente ao objetivo do TED. Possíveis valores na tabela 3

Boleto Bancário (Boleto de mesmo banco, Boleto de outro Banco)

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros espefíficos para o pagamento de boletos bancários.

O attributo amount nesse caso é opcional, pois ele é identificado a partir do código de barras.

Parâmetros quando payment_method é 'billet_same_bank’ ou 'billet_other_bank’

Campo	Tipo	Comentário
barcode	string	(requerido) Código de barras do boleto bancário
payee_id	string	(requerido, se não enviar payee) identificador do beneficiário (caso seja fornecido, o parâmetro `payee` será ignorado)
payee*	object	(requerido, se não enviar payee_id) atributos para a criação de um novo beneficiário ou atualização de um beneficiário existente com o mesmo documento (national_identifier)
payment_type	string	(requerido) tipo de pagamento. Os possíveis valores variam de acordo com o “payment_method” (vide tabela 1)
due_date	date	(opicional, já que é identificado no código de barras) Data de vencimento do boleto
discount_amount	decimal	(opcional) valor do desconto

Boleto de Tributo (Tributo com código de barras, FGTS)

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros espefíficos para o pagamento de boletos de tributos.

O attributo amount nesse caso é opcional, pois ele é identificado a partir do código de barras.

O attributo payment_type é automaticamente definido como "tribute".

Parâmetros quando payment_method é 'tribute_with_barcode’

Campo	Tipo	Comentário
barcode	string	(requerido) Código de barras do boleto bancário
due_date	date	(requerido) Data de vencimento do boleto

Parâmetros quando payment_method é 'fgts’

Campo	Tipo	Comentário
barcode	string	(requerido) Código de barras do boleto bancário
taxpayer_document_type	string	(requerido) Tipo do documento do contribuinte (“cnpj” ou “cei”)
taxpayer_document	string	(requerido) Número do documento do contribuinte

Boleto de Concessionária

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros espefíficos para o pagamento de boletos de concessionárias.

O attributo amount nesse caso é opcional, pois ele é identificado a partir do código de barras.

Parâmetros quando payment_method é 'dealership’

Campo	Tipo	Comentário
barcode	string	(requerido) Código de barras do boleto bancário
due_date	date	(requerido) Data de vencimento do boleto
payment_type	string	(requerido) tipo de pagamento. Os possíveis valores variam de acordo com o “payment_method” (vide tabela 1)

Tributos sem código de barras (GPS, DARF, DAS, IPVA, ICMS-SP, DPVAT)

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros específicos para cada tipo de tributo:

O attributo payment_type é automaticamente definido como "tribute".

Parâmetros quando payment_method é 'gps’

Campo	Tipo	Comentário
gps_payment_code	string	(requerido) código do GPS, de 4 dígitos
competency_month	string	(requerido) mês de competência do GPS, repesentado por 2 dígitos
competency_year	string	(requerido) ano de competência do GPS, repesentado por 4 dígitos
other_entities_amount	decimal	(opcional) valor extra para outras entidades
monetary_update	decimal	(opcional) atualização monetária, incluindo valores de juros e multa

Parâmetros quando payment_method é 'darf’

Campo	Tipo	Comentário
due_date	date	(requerido) data de vencimento
calculation_period	date	(requerido) período de apuração
receita_federal_code	string	(requerido) código da receita federal, de 4 dígitos
reference_number	string	(opcional) número de referência
mulct_amount	decimal	(opcional) valor da multa
interest_amount	decimal	(opcional) valor do juros

Parâmetros quando payment_method é 'das’

Campo	Tipo	Comentário
due_date	date	(requerido) data de vencimento
calculation_period	date	(requerido) período de apuração
receita_federal_code	string	(requerido) código da receita federal, de 4 dígitos
gross_revenue	decimal	(requerido) Valor da receita bruta
gross_revenue_percentage	decimal	(requerido) Valor da porcentagem da receita bruta
mulct_amount	decimal	(opcional) valor da multa
interest_amount	decimal	(opcional) valor do juros

Parâmetros quando payment_method é 'ipva’

Campo	Tipo	Comentário
due_date	date	(requerido) data de vencimento
city_code	integer	(requerido) código da cidade
competency_year	string	(requerido) ano de competência do IPVA, repesentado por 4 dígitos
license_plate	string	(requerido) placa do carro
payment_option	string	(requerido) opção de pagamento. Possíveis valores na tabela 4
renavam	string	(requerido) número do Renavam
uf	string	(requerido) estado, representado por seu acrônimo (RJ, SC, etc)
discount_amount	decimal	(opcional, requerido quando `payment_option` for 'single_with_discount’) valor do desconto.

Parâmetros quando payment_method é 'icms_sp’

Campo	Tipo	Comentário
due_date	date	(requerido) data de vencimento
receita_federal_code	string	(requerido) código da receita federal, de 4 dígitos
competency_month	string	(requerido) mês de competência do ICMS-SP, repesentado por 2 dígitos
competency_year	string	(requerido) ano de competência do ICMS-SP, repesentado por 4 dígitos
state_registration	string	(requerido) registro estadual
active_debt_registration	string	(requerido) registro de dívida ativa
installment_number	string	(requerido) número da prestação
mulct_amount	decimal	(opcional) valor da multa
interest_amount	decimal	(opcional) valor do juros

Parâmetros quando payment_method é 'dpvat’

Campo	Tipo	Comentário
competency_year	string	(requerido) ano de competência do DPVAT, repesentado por 4 dígitos
license_plate	string	(requerido) placa do carro
renavam	string	(requerido) número do Renavam
uf	string	(requerido) estado, representado por seu acrônimo (RJ, SC, etc)
discount_amount	decimal	(opcional) valor do desconto.
due_date	date	(opcional) data de vencimento
city_code	integer	(opcional) código da cidade

payee

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do beneficiário (cpf ou cnpj)
national_identifier	string	(requerido) documento do beneficiário
name	string	(requerido) nome do beneficiário

Atualização de Pagamento

Atualizar Pagamento

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/payments/:id
  PATCH https://app.cobrato.com/api/v1/payments/:id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/payents/:id \
    -d '{
          "amount": "125.99"
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "amount": ["não pode ficar em branco"]
      }
  }

Atualiza um determinado Pagamento, retornando as informações do mesmo em caso de sucesso. Se houverem erros, eles serão informados no corpo da resposta. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Parâmetros comuns a todas as formas de pagamento

Campo	Tipo	Comentário
amount	decimal	(requerido) valor do pagamento
date	date	(requerido) data do pagamento
note	string	(opcional) oberservação do pagamento

Transferências (DOC, TED, Crédito)

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros comuns aos pagamentos via transferência, além de alguns espefíficos para cada tipo de transferência.

Parâmetros comuns à todos os pagamentos via transferência

Campo	Tipo	Comentário
bank_code	string	(requerido) código de 3 dígitos do banco da conta bancária para o pagamento
account	string	(requerido) número da conta bancária para o pagamento
account_digit	string	(requerido) dígito da conta bancária para fazer o pagamento
agency	string	(requerido) número da agência da conta bancária para fazer o pagamento
payee_id	string	(requerido, se não enviar payee) identificador do beneficiário (caso seja fornecido, o parâmetro `payee` será ignorado)
payee*	object	(requerido, se não enviar payee_id) atributos para a criação de um novo beneficiário ou atualização de um beneficiário existente com o mesmo documento (national_identifier)

Parâmetros quando payment_method é 'doc_other_ownership’ ou 'doc_same_ownership’

Campo	Tipo	Comentário
doc_goal	string	(opcional) código referente ao objetivo do DOC. Possíveis valores na tabela 2

Parâmetros quando payment_method é 'ted_other_ownership’

Campo	Tipo	Comentário
ted_goal	string	(opcional) código referente ao objetivo do TED. Possíveis valores na tabela 3

Boleto Bancário (Boleto de mesmo banco, Boleto de outro Banco)

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros espefíficos para o pagamento de boletos bancários.

Parâmetros quando payment_method é 'billet_same_bank’ ou 'billet_other_bank’

Campo	Tipo	Comentário
payee_id	string	(requerido, se não enviar payee) identificador do beneficiário (caso seja fornecido, o parâmetro `payee` será ignorado)
payee*	object	(requerido, se não enviar payee_id) atributos para a criação de um novo beneficiário ou atualização de um beneficiário existente com o mesmo documento (national_identifier)
due_date	date	(requerido) Data de vencimento do boleto
discount_amount	decimal	(opcional) valor do desconto

Boleto de Tributo (Tributo com código de barras, FGTS)

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros espefíficos para o pagamento de boletos de tributos.

Parâmetros quando payment_method é 'tribute_with_barcode’

Campo	Tipo	Comentário
due_date	date	(requerido) Data de vencimento do boleto

Parâmetros quando payment_method é 'fgts’

Campo	Tipo	Comentário
taxpayer_document_type	string	(requerido) Tipo do documento do contribuinte (“cnpj” ou “cei”)
taxpayer_document	string	(requerido) Número do documento do contribuinte

Boleto de Concessionária

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros espefíficos para o pagamento de boletos de concessionárias.

Parâmetros quando payment_method é 'dealership’

Campo	Tipo	Comentário
due_date	date	(requerido) Data de vencimento do boleto

Tributos sem código de barras (GPS, DARF, DAS, IPVA, ICMS-SP, DPVAT)

Além dos parâmetros comuns à todas as formas de pagamento, temos parâmetros específicos para cada tipo de tributo:

Parâmetros quando payment_method é 'gps’

Campo	Tipo	Comentário
gps_payment_code	string	(requerido) código do GPS, de 4 dígitos
competency_month	string	(requerido) mês de competência do GPS, repesentado por 2 dígitos
competency_year	string	(requerido) ano de competência do GPS, repesentado por 4 dígitos
other_entities_amount	decimal	(opcional) valor extra para outras entidades
monetary_update	decimal	(opcional) atualização monetária, incluindo valores de juros e multa

Parâmetros quando payment_method é 'darf’

Campo	Tipo	Comentário
due_date	date	(requerido) data de vencimento
calculation_period	date	(requerido) período de apuração
receita_federal_code	string	(requerido) código da receita federal, de 4 dígitos
reference_number	string	(opcional) número de referência
mulct_amount	decimal	(opcional) valor da multa
interest_amount	decimal	(opcional) valor do juros

Parâmetros quando payment_method é 'das’

Campo	Tipo	Comentário
due_date	date	(requerido) data de vencimento
calculation_period	date	(requerido) período de apuração
receita_federal_code	string	(requerido) código da receita federal, de 4 dígitos
gross_revenue	decimal	(requerido) Valor da receita bruta
gross_revenue_percentage	decimal	(requerido) Valor da porcentagem da receita bruta
mulct_amount	decimal	(opcional) valor da multa
interest_amount	decimal	(opcional) valor do juros

Parâmetros quando payment_method é 'ipva’

Campo	Tipo	Comentário
due_date	date	(requerido) data de vencimento
city_code	integer	(requerido) código da cidade
competency_year	string	(requerido) ano de competência do IPVA, repesentado por 4 dígitos
license_plate	string	(requerido) placa do carro
payment_option	string	(requerido) opção de pagamento. Possíveis valores na tabela 4
renavam	string	(requerido) número do Renavam
uf	string	(requerido) estado, representado por seu acrônimo (RJ, SC, etc)
discount_amount	decimal	(opcional, requerido quando `payment_option` for 'single_with_discount’) valor do desconto.

Parâmetros quando payment_method é 'icms_sp’

Campo	Tipo	Comentário
due_date	date	(requerido) data de vencimento
receita_federal_code	string	(requerido) código da receita federal, de 4 dígitos
competency_month	string	(requerido) mês de competência do ICMS-SP, repesentado por 2 dígitos
competency_year	string	(requerido) ano de competência do ICMS-SP, repesentado por 4 dígitos
state_registration	string	(requerido) registro estadual
active_debt_registration	string	(requerido) registro de dívida ativa
installment_number	string	(requerido) número da prestação
mulct_amount	decimal	(opcional) valor da multa
interest_amount	decimal	(opcional) valor do juros

Parâmetros quando payment_method é 'dpvat’

Campo	Tipo	Comentário
competency_year	string	(requerido) ano de competência do DPVAT, repesentado por 4 dígitos
license_plate	string	(requerido) placa do carro
renavam	string	(requerido) número do Renavam
uf	string	(requerido) estado, representado por seu acrônimo (RJ, SC, etc)
discount_amount	decimal	(opcional) valor do desconto.
due_date	date	(opcional) data de vencimento
city_code	integer	(opcional) código da cidade

payee

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do beneficiário (cpf ou cnpj)
national_identifier	string	(requerido) documento do beneficiário
name	string	(requerido) nome do beneficiário

Exclusão de Pagamento

Excluir Pagamento

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/payment/:id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/payment/:id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

Exclui determinado Pagamento. As mudanças são irreversíveis.

Cancelamento de Pagamento

Cancelar Pagamento

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/payment/:id/cancel

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/payment/:id/cancel

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "registration_status": ["não permite cancelamento. Somente pagamentos com status 'Pagamento registrado' podem ser cancelados"]
      }
  }

Inicia o processo de cancelamento de um determinado Pagamento, retornando JSON contendo as informações do pagamento em caso de sucesso ou os erros, caso haja algum.

Após iniciar o processo de cancelamento será necessário gerar um arquivo de remessa, enviar para o banco e esperar o arquivo de retorno confirmando o cancelamento.

Marcar Pagamento como não autorizado

Marcar Pagamento como não autorizado

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/payment/:id/unauthorize

  EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/payment/:id/unauthorize

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "registration_status": ["Não é possível marcar este pagamento como não autorizado. Somente pagamentos com status 'registrado', NÃO efetivados e vencidos podem ser marcados como não autorizados"]
      }
  }

Marca um determinado Pagamento como não autorizado, retornando JSON com as informações do pagamento em caso de sucesso ou, caso contrário, os erros.

Reagendar Pagamento

Reagendar Pagamento

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/payments/:id/reschedule

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/payents/:id/reschedule \
    -d '{
          "date": "2018-10-02"
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "date": ["não pode ficar em branco"]
        "registration_status": ["não permite reagendar pagamento. Somente pagamentos com status 'Pagamento registrado', podem ser reagendados"]
      }
  }

Reagenda um determinado Pagamento. Se houverem erros, eles serão informados no corpo da resposta.

Marcar pagamento com Erro no Registro

Marcar pagamento com Erro no Registro

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/payment/:id/register_error

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/payment/:id/register_error

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":
      {
        "registration_status": ["não permite marcar como Erro no Registro"]
      }
  }

Marca o pagamento com Erro no registro manualmente.

Importante para pagamentos que tiveram o lote rejeitado pelo sistema do banco. Neste caso o banco não envia nenhum erro no arquivo de retorno e é necessário marcar manualmente.

Schema de Pagamento

Schema de Pagamento

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/payments/schema

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/payments/schema?payment_config_id=1&payment_method=ted_other_ownership

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE CORPO DA RESPOSTA COM SUCESSO

  {
    "schema": {
      // json schema
    },
    "form": {
      // json schema form
    }
  }

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "payment_method":["ao menos um dos parâmetros deve ser enviado: payment_method e barcode"],
      "barcode":["ao menos um dos parâmetros deve ser enviado: payment_method e barcode"],
      "payment_config_id":["não pode ficar em branco"]
    }
  }

Retorna o json schema e o json schema form com as informações necessárias para criar um pagamento, baseado nos dados enviados.

Parâmetros

Campo	Tipo	Comentário
payment_config_id	integer	(requerido) código de identificação da configuração de pagamento à qual o pagamento irá pertencer
payment_method	string	(requerido, ou barcode) forma de pagamento ('credit_other_ownership’, 'credit_same_ownership’, 'credit_savings_account’, 'doc_other_ownership’, 'doc_same_ownership’, 'ted_other_ownership’, 'ted_same_ownership’, 'gps’, 'darf’, 'das’, 'ipva’, icms_sp’, 'dpvat’)
barcode	string	(requerido, ou payment_method) código de barras do pagamento

Tabelas

Possíveis valores para payment_type (tabela 1)

payment_type ⟶ payment_method ↴	salary	dividend	debenture	traveling_expense	authorized_representative	provider	benefit	insurance_claim	investment_fund	other	tribute
credit_other_ownership	X	X	X	X	X	X	X	X	X	X
credit_same_ownership						X				X
credit_savings_account		X				X	X	X		X
doc_other_ownership		X	X	X	X	X	X	X		X
doc_same_ownership						X				X
ted_other_ownership		X	X	X	X	X	X	X		X
ted_same_ownership						X				X
billet_other_bank						X				X
billet_same_bank						X				X
dealership						X				X
tribute_with_barcode											X
fgts											X
gps											X
darf											X
das											X
ipva											X
icms_sp											X
dpvat											X

Possíveis valores para doc_goal (tabela 2)

Quando payment_method for 'doc_other_ownership’ todos os valores são aceitos. Contudo, quando payment_method for 'doc_same_ownership’, apenas os valores '01’ e '11’ são aceitos.

Código	Descrição
01	Crédito em Conta
02	Pagamento de Aluguel / Condomínio
03	Pagamento de Duplicata / Títulos
04	Pagamento de Dividendos
05	Pagamento de Mensalidade Escolar
06	Pagamento de Salários
07	Pagamento de Fornecedores / Honorários
08	Operações de Câmbio / Fundos
09	Repasse de Arrecadação / Pagamento de Tributos
10	Transferência Internacional de Reais
11	DOC para Poupança
12	DOC para Depósito Judicial
13	Pensão Alimentícia
99	Outros

Possíveis valores para ted_goal (tabela 3)

Código	Descrição
00001	Pagamento de Impostos, Tributos e Taxas
00002	Pagamento a Concessionárias de Serviço Público
00003	Pagamento de Dividendos
00004	Pagamento de Salários
00005	Pagamento de Fornecedores
00006	Pagamento de Honorários
00007	Pagamento de Aluguéis e Taxas e Condomínio
00008	Pagamento de Duplicatas e Títulos
00009	Pagamento de Honorários
00010	Crédito em Conta
00011	Pagamento a Corretoras
00016	Crédito em Conta Investimento
00100	Depósito Judicial
00101	Pensão Alimentícia
00200	Transferência Internacional de Reais
00201	Ajuste Posição Mercado Futuro
00204	Compra/Venda de Ações - Bolsas de Valores e Mercado de Balcão
00205	Contrato referenciado em Ações/Índices de Ações - BV/BMF
00300	Restituição de Imposto de Renda
00500	Restituição de Prêmio de Seguros
00501	Pagamento de indenização de Sinistro de Seguro
00502	Pagamento de Prêmio de Co-seguro
00503	Restituição de prêmio de Co-seguro
00504	Pagamento de indenização de Co-seguro
00505	Pagamento de prêmio de Resseguro
00506	Restituição de prêmio de Resseguro
00507	Pagamento de Indenização de Sinistro de Resseguro
00508	Restituição de Indenização de Sinistro de Resseguro
00509	Pagamento de Despesas com Sinistros
00510	Pagamento de Inspeções/Vistorias Prévias
00511	Pagamento de Resgate de Título de Capitalização
00512	Pagamento de Sorteio de Título de Capitalização
00513	Pagamento de Devolução de Mensalidade de Título de Capitalização
00514	Restituição de Contribuição de Plano Previdenciário
00515	Pagamento de Benefício Previdenciário de Pecúlio
00516	Pagamento de Benefício Previdenciário de Pensão
00517	Pagamento de Benefício Previdenciário de Aposentadoria
00518	Pagamento de Resgate Previdenciário
00519	Pagamento de Comissão de Corretagem
00520	Pagamento de Transferências/Portabilidade de Reserva de Seguro/Previdência

Possíveis valores para payment_option (tabela 4)

Opção de pagamento	Descrição
single_with_discount	Simples com desconto
single_without_discount	Simples sem desconto
installment_1	Primeira prestação
installment_2	Segunda prestação
installment_3	Terceira prestação
installment_4	Quarta prestação
installment_5	Quinta prestação
installment_6	Sexta prestação

Ações permitidas para cada Status (Tabela 5)

Somente os status without_remittance, registered, canceled e registered_with_error permitem ações. Abaixo as ações disponíveis para todos os Status.

Status	Descrição	Cancelar	Excluir	Editar / Reagendar
without_remittance	Pagamento criado, mas ainda não teve o arquivo de remessa gerado pelo usuário		✓	✓
remitted	Pagamento teve seu arquivo de remessa gerado e o usuário deve enviar o arquivo para o banco. Ainda não foi registrado no banco
registered	O banco informou que o pagamento foi devidamente registrado e será efetivado na data cadastrada	✓
registered_with_error	O banco não conseguiu processar a instrução de registro do pagamento e portanto existe a garantia de que não será efetivado		✓	✓
canceled	Pagamento previamente registrado no banco foi cancelado antes de ser efetivado	✓
cancelation_started	Pagamento teve seu processo de cancelamento iniciado. Nesse momento ainda não foi criado o arquivo de remessa de cancelamento
canceled_awaiting_confirmation	Pagamento teve seu arquivo de remessa de cancelamento gerado e o usuário deve envia-lo para o banco. O pagamento pode ter sido efetivado pelo banco e não há a garantia que o cancelamento ocorra a tempo
edit_amount_started	Pagamento teve seu processo de alteração do valor iniciado. Nesse momento ainda não foi criado o arquivo de remessa de alteração
amount_edited_awaiting_confirmation	Pagamento teve seu arquivo de remessa de alteração do valor gerado e o usuário deve envia-lo para o banco. O pagamento pode ter sido efetivado pelo banco e não há a garantia que a alteração ocorra a tempo
reschedule_started	Pagamento teve seu processo de reagendamento iniciado. Nesse momento ainda não foi criado o arquivo de remessa de reagendamento
rescheduled_awaiting_confirmation	Pagamento teve seu arquivo de remessa reagendamento criado e o usuário deve envia-lo para o banco. O pagamento pode ter sido efetivado pelo banco e não há a garantia que o reagendamento ocorra a tempo
unauthorized	Pagamento foi registrado no banco porém não foi autorizado pelo administrador da conta. Portanto não será efetivado e foi marcado como não autorizado pelo usuário.

Cartão de Crédito

Cartão de Crédito

EXEMPLO

  {
    "id": 8,
    "token": "kUzSKmYvKpGQTAZtXbgefPFUt/i1N+rNHb4UJGM0u2E=",
    "national_identifier": "444.023.930-78",
    "number": "545301******6167",
    "holder_name": "John Doe",
    "brand": "amex",
    "expiration": "05/18",
    "avs_address": "Rua Julio de Castilhos",
    "avs_number": "100",
    "avs_complement": "Apto 103",
    "avs_district": "Centro",
    "avs_zipcode": "99000-750",
    "reusability_status": "error",
    "reusability_error_message": "Código de segurança inválido",
    "payer_id": 1,
    "charge_config_id": 12,
    "_links": [
      { "rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/credit_cards/8" }
    ]
  }

Os Cartões de Crédito pertencem ao Pagador utilizado no momento de sua criação (primeira utilização em uma Cobrança) e, dessa forma, só pode ser reutilizado em Cobranças onde o Pagador é o mesmo.

Parâmetros

Campo	Tipo	Comentário
token	string	token do cartão gerado com o CobratoJS
national_identifier	string	cpf do portador do cartão
number	string	números do cartão (incompleto, apenas para identificação)
expiration	string	expiração do cartão, no formato “mm/aa”
holder_name	string	nome do dono do cartão
brand	string	bandeira do cartão (visa, mastercard, amex, elo, diners, discover, jcb, aura)
avs_address	string	endereço de cobrança do cartão
avs_number	string	número do endereço de cobrança do cartão
avs_complement	string	complemento endereço de cobrança do cartão
avs_district	string	bairro do endereço de cobrança do cartão
avs_zipcode	string	cep do endereço de cobrança do cartão
reusability_status	string	status da configuração para possibilitar o reuso o cartão em futuras cobranças (pending, ok, error)
reusability_error_message	string	informa o motivo do erro na configuração de reuso, apenas quando o atributo reusability_status tem o valor “error”
payer_id	integer	identificador do Payer ao qual este cartão pertence
charge_config_id	integer	identificador da ChargeConfig à qual este cartão pertence
_links	array of object	links do beneficiário

reusability_status

O atributo reusability_status pode ter os seguintes valores:

Valor	Descrição
pending	assim que é criado e ainda não foi feita verificação do cartão através de uma cobrança
error	quando ocorre um erro na utilização do cartão (o erro ficará descrito no atributo `reusability_error_message`)
reusable	quando já foi feita uma cobrança com sucesso utilizando o cartão e ele foi salvo para ser reutilizado em futuras cobranças
not_reusable	quando o cartão não foi salvo para ser reutilizado

Informações do Cartão de Crédito

Mostrar Cartão de Crédito

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/credit_cards/:credit_card_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/credit_cards/:credit_card_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id": 8,
    "token": "kUzSKmYvKpGQTAZtXbgefPFUt/i1N+rNHb4UJGM0u2E=",
    "national_identifier": "444.023.930-78",
    "number": "545301******6167",
    "holder_name": "John Doe",
    "brand": "amex",
    "expiration": "05/18",
    "avs_address": "Rua Julio de Castilhos",
    "avs_number": "100",
    "avs_complement": "Apto 103",
    "avs_district": "Centro",
    "avs_zipcode": "99000-750",
    "reusability_status": "error",
    "reusability_error_message": "Código de segurança inválido",
    "payer_id": 1,
    "charge_config_id": 12,
    "_links": [
      { "rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/credit_cards/8" }
    ]
  }

Retorna as informações detalhadas do cartão de crédito informado em JSON.

Lista dos Cartões de crédito

Listar Cartões de Crédito

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/credit_cards

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/credit_cards?charge_config_id=12

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "credit_cards":
      [
        {
          // informações cartão de crédito 1
        },
        {
          // informações cartão de crédito 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo os Cartões de Crédito pertencentes à sua Conta de Serviço.

É possível filtrar a lista através dos parâmetros: payer_id, charge_config_id, number, holder_name, brand, reusability_status

Criação de Cartão de Crédito

Criar Cartão de Crédito

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/credit_cards

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/credit_cards \
    -d '{
        "token": "kUzSKmYvKpGQTAZtXbgefPFUt/i1N+rNHb4UJGM0u2E=",
        "national_identifier": "444.023.930-78",
        "number": "5453010000066167",
        "holder_name": "John Doe",
        "brand": "mastercard",
        "expiration": "05/18",
        "cvv": "123",
        "avs_address": "Rua Julio de Castilhos",
        "avs_number": "100", 
        "avs_complement": "Apto 103",
        "avs_district": "Centro",
        "avs_zipcode": "99000-750",
        "payer_id": 1,
        "charge_config_id": 12,
        "soft_descriptor": "CompanyName"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":{
      "number": ["não pode ficar em branco"],
      "holder_name": ["não pode ficar em branco"]
    }
  }

Cria um novo Cartão de Crédito com o objetivo de utilizá-lo em futuras cobranças sem a necessidade de solicitar novamente ao usuário os dados do cartão. Para que o cartão seja homologado, é feita uma cobrança com o valor entre R$ 1,00 e R$ 2,00 que é automaticamente cancelada em seguida.

Se houverem erros a criação o cartão, eles serão informados no corpo da resposta.

Em caso de sucesso, as informações do cartão são retornadas. Contudo, o cartão ainda não estará apto para re-utilização em novas cobranças. Isto só ocorrerá quando a cobrança de homologação for concluída com sucesso. Esta informação pode ser obtida através do atributo reusability_status. Caso ele tenha o valor “pending”, quer dizer que a cobrança ainda não foi feita. Caso tenha o valor “reusable” quer dizer que o cartão pode ser reutilizado. Caso tenha o valor “error”, significa que ocorreu um erro na cobrança de homologação, e o motivo pode ser verificado no atributo reusability_error_message.

Parâmetros

Campo	Tipo	Comentário
token	string	(requerido para cobranças PJBank) token do cartão
national_identifier	string	(requerido para cobranças PJBank) cpf do portador do cartão
number	string	(requerido) número do cartão
expiration	string	(requerido) expiração do cartão, no formato “mm/aa” ou “mm/aaaa”
holder_name	string	(requerido) nome do dono do cartão
cvv	string	(requerido) código de segurança do cartão
brand	string	(requerido) bandeira do cartão (visa, mastercard, amex, elo, diners, discover, jcb, aura)
charge_config_id	integer	(requerido) identificador da ChargeConfig à qual este cartão pertence
payer_id	integer	(requerido, se não enviar payer_attributes ) identificador do pagador ao qual este cartão pertence (caso seja fornecido, o parâmetro payer_attributes será ignorado)
payer_attributes*	object	(requerido, se não enviar payer_id ) atributos para a criação de um novo pagador ou atualização de um pagador existente com o mesmo documento (national_identifier)
avs_address	string	(opcional) endereço de cobrança do cartão
avs_number	string	(opcional) número do endereço de cobrança do cartão
avs_complement	string	(opcional) complemento endereço de cobrança do cartão
avs_district	string	(opcional) bairro do endereço de cobrança do cartão
avs_zipcode	string	(opcional) cep do endereço de cobrança do cartão
soft_descriptor	string	(opcional) descritor que irá aparecer na fatura do cartão referente à cobrança de homologação (no máximo 13 caracteres)

payer_attributes

Caso exista um Pagador (Payer) com o mesmo national_identifier, não será criado um novo, mas sim atualizado o existente.

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do pagador (cpf ou cnpj)
national_identifier	string	(requerido) documento do pagador
name	string	(requerido) nome do pagador
number	string	(opcional) número do endereço do pagador
complement	string	(opcional) complemento do endereço do pagador
street	string	(opcional) rua do endereço do pagador
neighbourhood	string	(opcional) bairro do endereço do pagador
zipcode	string	(opcional) cep do endereço do pagador
city	string	(opcional) cidade do endereço do pagador
state	string	(opcional) sigla do estado do endereço do pagador (“RJ” por exemplo)

Atualização de Cartão de Crédito

Atualizar Cartão de Crédito

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/credit_cards/:credit_card_id
  PATCH https://app.cobrato.com/api/v1/credit_cards/:credit_card_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/credit_cards/1 \
    -d '{
        "payer_id": 5
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM BENEFICIÁRIO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

    {
      "errors": {
        "payer_id": ["não existe para a sua conta"]
      }
    }

Atualiza um determinado Cartão de Crédito, retornado as informações do mesmo caso haja sucesso. Se houverem erros, eles serão informados no corpo da resposta.

Parâmetros

Campo	Tipo	Comentário
payer_id	integer	(requerido, se não enviar payer_attributes ) identificador do pagador ao qual este cartão pertence (caso seja fornecido, o parâmetro payer_attributes será ignorado)
payer_attributes*	object	(requerido, se não enviar payer_id ) atributos para a criação de um novo pagador ou atualização de um pagador existente com o mesmo documento (national_identifier)

payer_attributes

Caso exista um Pagador (Payer) com o mesmo national_identifier, não será criado um novo, mas sim atualizado o existente.

Campo	Tipo	Comentário
national_identifier_type	string	(requerido) tipo do documento do pagador (cpf ou cnpj)
national_identifier	string	(requerido) documento do pagador
name	string	(requerido) nome do pagador
number	string	(opcional) número do endereço do pagador
complement	string	(opcional) complemento do endereço do pagador
street	string	(opcional) rua do endereço do pagador
neighbourhood	string	(opcional) bairro do endereço do pagador
zipcode	string	(opcional) cep do endereço do pagador
city	string	(opcional) cidade do endereço do pagador
state	string	(opcional) sigla do estado do endereço do pagador (“RJ” por exemplo)

Lista de Todas as cobranças feitas com o cartão de crédito

Listar as Cobranças realizadas com o Cartão de Crédito

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/credit_cards/:id/charges

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/credit_cards/12/charges

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "charges":
      [
        {
          // informações cobrança 1
        },
        {
          // informações cobrança 2
        },
        ...
      ]
  }

Retorna uma lista paginada em JSON contendo todos as Cobranças realizadas com o Cartão de Crédito.

É possível filtrar a lista através dos parâmetros: total_amount, received, payment_gateway_status.

CNAB de Remessa

CNAB de Remessa

EXEMPLO

  {
    "id": 1,
    "config_id": 1,
    "type": "charge",
    "filename": "CI14058A.REM",
    "status": "processed",
    "_links":
      [
        {"rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1"},
        {"rel": "destroy", "method": "DELETE", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1"},
        {"rel": "config", "method": "GET", "href": "https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel": "file", "method": "GET", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1/file"},
        {"rel": "items", "method": "GET", "href": "http://localhost:3000/api/v1/remittance_cnabs/1/items"}
      ]
  }

Os Arquivos CNAB de Remessa são arquivos enviados para o banco com o objetivo de registrar novas cobranças/pagamentos, podendo ser gerado a partir de um ou mais items (Cobranças ou Pagamentos). Se forem enviados items de Configurações diferentes, será gerado um CNAB de remessa para cada Configuração.

Parâmetros

Campo	Tipo	Comentário
id	integer	identificador do CNAB de remessa
type	string	indica o tipo de arquivo de remessa (‘charge’ ou 'payment’)
config_id	string	identificador da configuração no Cobrato relacionada ao arquivo de remessa
charge_config_id	string	(DEPRECATED: use config_id) identificador da configuração de cobrança no Cobrato
filename	string	nome do arquivo de remessa
status	string	situação da remessa, podendo ser “processing” (processando), “processed” (processado) e “processing_error” (erro de processamento)
_links	array of object	links relacionado CNAB de remessa

Informações do CNAB de Remessa

Mostrar CNAB de Remessa

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/remittance_cnabs/:id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/remittance_cnabs/:id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id": 1,
    "config_id": 1,
    "type": "charge",
    "filename": "CI14058A.REM",
    "status": "processed",
    "_links":
      [
        {"rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1"},
        {"rel": "destroy", "method": "DELETE", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1"},
        {"rel": "config", "method": "GET", "href": "https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel": "file", "method": "GET", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1/file"},
        {"rel": "items", "method": "GET", "href": "http://localhost:3000/api/v1/remittance_cnabs/1/items"}
      ]
  }

Retorna as informações detalhadas em JSON do CNAB de remessa informado.

Lista de Todas as CNABs de Remessa

Listar CNABs de Remessa

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/remittance_cnabs

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/remittance_cnabs

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "remittance_cnabs":
      [
        {
          // informações do CNAB de remessa 1
        },
        {
          // informações do CNAB de remessa 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos os CNABs de remessa que pertencem a sua Conta de Serviço.

Criação de Arquivo CNAB de Remessa

Criar Arquivo CNAB de Remessa

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/remittance_cnabs

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/remittance_cnabs \
    -D '{
        "item_ids": [12, 13, 15, 18]
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA

  {
    "remittance_cnabs": [
      "id": 1,
      "config_id": 1,
      "type": "charge",
      "filename": "CI14058A.REM",
      "status": "processed",
      "charge_config_id": 1,
      "_links":
        [
          {"rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1"},
          {"rel": "destroy", "method": "DELETE", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1"},
          {"rel": "config", "method": "GET", "href": "https://app.cobrato.com/api/v1/charge_configs/1"},
          {"rel": "file", "method": "GET", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1/file"},
          {"rel": "items", "method": "GET", "href": "http://localhost:3000/api/v1/remittance_cnabs/1/items"}
        ]
    }]
  }

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":{
      "item_ids": ["não pode ficar em branco"],
    }
  }

Cria novo(s) Arquivo(s) CNAB de Remessa, retornando as informações do(s) mesmo(s) caso haja sucesso. Se houverem erros, eles serão informados no corpo da resposta.

Um Arquivo de remessa sempre está associado à uma Configuração. Sendo assim, será gerado um CNAB de remessa para cada Configuração envolvida na solicitação de criação, e esse arquivo irá incluir todos os items passíveis de remessa, seja para registrar a inclusão, cancelamento ou alteração.

Parâmetros

Campo	Tipo	Comentário
type	string	(optional) Define o tipo de arquivo(s) CNAB de Remessa a ser(em) criado(s). Os possíveis valores são 'charge’ para Cobrança e 'payment’ para Pagamento, sendo que o padrão é 'charge’
item_ids	array of integers	(requerido, veja a nota acima) Lista com os ids dos itens (cobranças ou pagamentos) que devem estar incluídos no(s) arquivo(s) CNAB de Remessa
charge_ids	array of integers	(DEPRECATED: use item_ids) (requerido, veja a nota acima) Lista com os ids das cobranças que devem estar incluídas no(s) arquivo(s) CNAB de Remessa
config_ids	array of integers	(requerido, veja a nota acima) Lista com os ids das configurações para as quais devem ser criados os Arquivos CNAB de Remessa
charge_config_ids	array of integers	(DEPRECATED: use config_ids) (requerido, veja a nota acima) Lista com os ids das configurações de cobranças para as quais devem ser criados os Arquivos CNAB de Remessa
payee_ids	array of integers	(requerido, veja a nota acima) Lista com os ids dos beneficiários das configurações para as quais devem ser criados os Arquivos CNAB de Remessa
payee_national_identifiers	array of strings	(requerido, veja a nota acima) Lista com os números de documento dos beneficiários das configurações para as quais devem ser criados os Arquivos CNAB de Remessa

Exclusão de CNAB de Remessa

Excluir CNAB de Remessa

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/remittance_cnabs/:id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/remittance_cnabs/:id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM CNAB DE REMESSA INEXISTENTE

    404 Not Found

Exclui determinado CNAB de remessa. A exclusão é irreversível.

Arquivo do CNAB de Remessa

Mostrar Arquivo do CNAB de Remessa (URL)

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/remittance_cnabs/:id/file

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/remittance_cnabs/:id/file

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM CNAB DE REMESSA INEXISTENTE

    404 Not Found

EXEMPLO DE CORPO DA RESPOSTA COM SUCESSO

  {
    "url":"https://cobrato-uploads.s3.amazonaws.com/remittance_cnabs/cnabs/1/B425065A.RET?AWSAccessKeyId=AKIAIRJFH3YRXV5YRVTQ&Expires=1452277155&Signature=IJ1P%2Bc%2F9vC%2FKlBWuHGIBEl%2BAHKk%3D"
  }

Mostra o link da url do arquivo de determinado CNAB de remessa.

Lista de Todas as Cobrança do Arquivo de Remessa

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/remittance_cnabs/:id/charges

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/remittance_cnabs/:id/charges

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "charges":
      [
        {
          // informações cobrança 1
        },
        {
          // informações cobrança 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos as cobranças que pertencem ao CNAB de remessa informado.

Lista de Todos os items do Arquivo de Remessa

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/remittance_cnabs/:id/items

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/remittance_cnabs/:id/items

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA (COBRANÇAS)

  {
    "charges":
      [
        {
          // informações do item 1 (charge)
        },
        {
          // informações do item 2 (charge)
        },
        ...
      ]
  }

EXEMPLO DE CORPO DA RESPOSTA (PAGAMENTOS)

  {
    "payments":
      [
        {
          // informações do item 1 (payment)
        },
        {
          // informações do item 2 (payment)
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos os items que pertencem ao CNAB de remessa informado.

CNAB de Retorno

CNAB de Retorno

EXEMPLO

  {
    "id": 1,
    "charge_config_id": 9, # DEPRECATED
    "config_id": 9,
    "status": "processed",
    "type": "charge",
    "filename": "CI14058A.RET",
    "_links":
      [
        {"rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/regress_cnabs/1"},
        {"rel": "destroy", "method": "DELETE", "href": "https://app.cobrato.com/api/v1/regress_cnabs/1"},
        {"rel": "config", "method": "GET", "href": "https://app.cobrato.com/api/v1/charge_config/1"},
        {"rel": "file", "method": "GET", "href": "https://app.cobrato.com/api/v1/regress_cnabs/1/file"}
      ]
  }

Os Arquivos CNAB de retorno são arquivos disponibilizados pelo banco com as informações de ocorrências relacionadas às cobranças/pagamentos. Os arquivos CNABs de retorno é relacionado à uma determinada Configuração e o cobrato tentará encontrar os itens relacionados e aplicar as informações enviadas pelo banco.

Parâmetros

Campo	Tipo	Comentário
id	integer	identificador do CNAB de retorno
type	string	indica o tipo de arquivo de remessa (‘charge’ ou 'payment’)
config_id	string	identificador da configuração no Cobrato relacionada ao arquivo de remessa
charge_config_id	string	(DEPRECATED: use config_id) identificador da configuração de cobrança no Cobrato
filename	string	nome do arquivo de retorno
status	string	situação do arquivo CNAB, podendo ser “processing” (processando), “processed” (processado) e “processing_error” (erro de processamento)
_links	array of object	links relacionado CNAB de retorno

Informações do CNAB de Retorno

Mostrar CNAB de Retorno

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/regress_cnabs/:id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/regress_cnabs/:id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id": 1,
    "charge_config_id": 9, # DEPRECATED
    "config_id": 9,
    "status": "processed",
    "type": "charge",
    "filename": "CI14058A.RET",
    "_links":
      [
        {"rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/regress_cnabs/1"},
        {"rel": "destroy", "method": "DELETE", "href": "https://app.cobrato.com/api/v1/regress_cnabs/1"},
        {"rel": "charge_config", "method": "GET", "href": "https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel": "file", "method": "GET", "href": "https://app.cobrato.com/api/v1/regress_cnabs/1/file"}
      ]
  }

Retorna as informações detalhadas em JSON do CNAB de retorno informado.

Lista de Todos os CNABs de Retorno

Listar CNABs de Retorno

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/regress_cnabs

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/regress_cnabs

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "regress_cnabs":
      [
        {
          // informações do CNAB de retorno 1
        },
        {
          // informações do CNAB de retorno 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos os CNABs de retorno que pertencem a sua Conta de Serviço.

É possível filtrar a lista através dos seguintes parâmetros:

type: Filtra pelo tipo de arquivo de retorno. O valor a ser informado é string com um dos tipos existentes de arquivo de retorno (“charge” ou “payment”).
config_id: Filtra pela configuração informada. O valor informado deve ser o id de uma configuração, seja de cobrança ou de pagamento. É fortemente recomendado usar sempre o filtro type em conjunto com esse para ter os resultados esperados.

Criação de CNAB de Retorno

Criar CNAB de Retorno

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/regress_cnabs

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/regress_cnabs \
    -d '{
          "config_id": 1,
          "type": "charge",
          "cnabs": {
            "content":      "MDJSRVRPUk5PMDFDT0JSQU5DQSAgICAgICAzMTMwMDAyMjY5OTAgICA...",
            "content_type": "text/plain"
            "filename":     "example.RET"
          }
        }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    202 Accepted

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors":{
      "config_id": ["não pode ficar em branco"],
      "cnabs": ["não pode ficar em branco"]
    }
  }

Cria um CNAB de retorno inicia o processamento do arquivo.

Parâmetros

Campo	Tipo	Comentário
type	string	(optional) Define o tipo de arquivo CNAB de Retorno a ser criado. Os possíveis valores são 'charge’ para Cobrança e 'payment’ para Pagamento, sendo que o padrão é 'charge’
config_id	string	(requerido) identificador da configuração à qual o arquivo CNAB de retorno pertence
charge_config_id	string	(DEPRECATED: use config_id) (requerido) identificador da configuração de cobrança à qual o arquivo CNAB de retorno pertence
cnabs	object	(requerido) dados do arquivo CNAB de retorno. O “content” deve ser uma string com o conteúdo do arquivo codificado em Base64

Exclusão de CNAB de retorno

Excluir CNAB de retorno

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/regress_cnabs/:id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/regress_cnabs/:id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM ARQUIVO DE RETORNO INEXISTENTE

    404 Not Found

Exclui determinado CNAB de retorno. A exclusão é irreversível.

Arquivo do CNAB de Retorno

Mostrar Arquivo do CNAB de Retorno (URL)

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/regress_cnabs/:id/file

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/regress_cnabs/:id/file

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM ARQUIVO DE RETORNO INEXISTENTE

    404 Not Found

EXEMPLO DE CORPO DA RESPOSTA COM SUCESSO

  {
    "url":"https://cobrato-uploads.s3.amazonaws.com/regress_cnabs/cnabs/1/B425065A.RET?AWSAccessKeyId=AKIAIRJFH3YRXV5YRVTQ&Expires=1452277155&Signature=IJ1P%2Bc%2F9vC%2FKlBWuHGIBEl%2BAHKk%3D"
  }

Mostra o link da url do arquivo de determinado CNAB de retorno.

Webhook

Webhook

EXEMPLO

  {
    "id": 1,
    "url": "http://www.seusitema.com/cobrato",
    "description": "teste",
    "secret": "my-secret-token",
    "_links": [
      {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/webhooks/1"},
      {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/webhooks/1"},
      {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/webhooks/1"}
    ]
  }

É possível ter indeterminados webhooks, que enviarão requisições para uma determinada URL quando certas ações ocorrem no Cobrato (Payloads).

Parâmetros

Campo	Tipo	Comentário
url	string	(requerido) URL na qual serão feitas as requisições GET e POST, esperando HTTP 200 como retorno
description	string	(opcional) descrição opcional do Webhook
secret	string	(requerido) Segredo pra ser adicionado no header de todas as requisições

Informações do Webhook

Mostra Webhook

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/webhooks/:webhook_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/webhooks/:webhook_id

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "id": 1,
    "url": "http://www.seusitema.com/cobrato",
    "description": "teste",
    "secret": "my-secret-token",
    "_links": [
      {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/webhooks/1"},
      {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/webhooks/1"},
      {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/webhooks/1"}
    ]
  }

Retorna as informações detalhadas do webhook em formato JSON.

Lista de Todos os Webhooks


Listar Webhooks

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/webhooks

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/webhooks

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "webhooks":
      [
        {
          // informações webhook 1
        },
        {
          // informações webhook 2
        },
        ...
      ]
  }

Retorna uma lista em JSON contendo todos os webhooks pertencentes a sua Conta de Serviço.

Criação de Webhook

Criar Webhook

DEFINIÇÃO

  POST https://app.cobrato.com/api/v1/webhooks

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X POST https://app.cobrato.com/api/v1/webhooks \
    -d '{
        "url": "http://www.seusitema.com/cobrato",
        "description": "Webhook teste",
        "secret": "my-secret-token"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

  {
    "errors": {
      "url": [
        "não é válida",
        "não pode ficar em branco"
      ]
    }
  }

Cria um novo webhook, retornando as informações do mesmo caso haja sucesso. Para realizar o cadastro é necessária que a URL informa aceite requisições POST, respondendo sempre com HTTP 200. No momento da criação, afim verificar a URL informada, o Cobrato fará uma requisição de teste à mesma. A requisição de teste será um payload com o corpo {"test": true}.

Parâmetros

Campo	Tipo	Comentário
url	string	(requerido) URL na qual serão feitas as requisições GET e POST, esperando HTTP 200 como retorno
description	string	(opcional) descrição opcional do Webhook

Atualização de Webhook

Atualizar Webhook

DEFINIÇÃO

  PUT https://app.cobrato.com/api/v1/webhooks/:webhook_id
  PATCH https://app.cobrato.com/api/v1/webhooks/:webhook_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X PATCH https://app.cobrato.com/api/v1/webhooks/:webhook_id \
    -d '{
        "descripction": "Webhook teste",
        "secret": "my-secret-token"
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM BENEFICIÁRIO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

Atualiza a descrição do webhook. Não é possível alterar a URL de um Webhook. A requisição não diferencia a utilização dos verbos PUT e PATCH.

Parâmetros

Campo	Tipo	Comentário
description	string	(opcional) descrição opcional do Webhook
secret	string	(requerido) segredo à ser adicionado aos readers

Exclusão de Webhook

Excluir Webhook

DEFINIÇÃO

  DELETE https://app.cobrato.com/api/v1/webhooks/:webhook_id

EXEMPLO DE REQUISIÇÃO

  $ curl -i -u $API_TOKEN:X \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X DELETE https://app.cobrato.com/api/v1/webhooks/:webhook_id

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM WEBHOOK INEXISTENTE

    404 Not Found

Exclui determinado webhook. A exclusão é irreversível.

Payloads

São as requisições enviadas pelo webhook do Cobrato para uma determinada URL notificando a ocorrência de certos eventos.

Quando um destes eventos ocorre, o webhook envia o payload (para a URL definida na criação do Webhook) em uma requisição HTTP do tipo POST com os seguintes headers:

Accept: application/json
Content-Type: application/json
User-Agent: Cobrato v1
X-Cobrato-Signature: <some-signature>
X-Cobrato-Requestid: <some-request-id>

Os dois últimos fazem parte da assinatura do payload, detalhada a seguir.

Assinatura do Payload

Por medidas de segurança, você pode verificar a assinatura do payload antes de tomar qualquer ação em relação ao payload recebido. Isso pode evitar que alguém se passe pelo Cobrato e enviei payloads falsos de eventos que não ocorreram de fato.

# EXEMPLO DE CÁCULO PARA VERIFICAÇÃO DA SIGNATURE (ruby)

secret = 'segredo definido na criação do Webhook'
content = "#{request.headers['X-Cobrato-RequestId']}#{request.body}"
cobrato_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), secret, content)

cobrato_signature == request.headers['X-Cobrato-Signature']
# => true

X-Cobrato-RequestId

Este header é único para cada requisição e é utilizado no cálculo do X-Cobrato-Signature.

X-Cobrato-Signature

Este header é a assinatura do webhook. Este valor pode ser calculado com o HMAC hex digest do X-Cobrato-RequestId concatenado ao corpo do payload, utilizando o Segredo (definido na criação do Webhook) como a chave.

Eventos notificados

Os eventos notificados são os seguintes:

Objeto	Evento	Descrição
charge	created	quando a cobrança é criada
charge	updated	quando a cobrança é atualizada
charge	destroyed	quando a cobrança é excluída
charge	received	quando a cobrança é recebida
charge	undone_receivement	quando a cobrança tem seu recebimento desfeito
charge	canceled	quando a cobrança é cancelada
charge	receivement_error	quando houve erro no recebimento
charge	cancellation_error	quando houve erro no cancelamento
charge_config	created	quando a configuração de cobrança é criada
charge_config	updated	quando a configuração de cobrança é atualizada
charge_config	destroyed	quando a configuração de cobrança é excluída
charge_config	deactivated	quando a configuração de cobrança é desativada
credit_card	created	quando o cartão de crédito é criado
credit_card	updated	quando o cartão de crédito é atualizado
charge_template	created	quando o modelo de cobrança é criado
charge_template	updated	quando o modelo de cobrança é atualizado
charge_template	destroyed	quando o modelo de cobrança é excluído
payer	created	quando o pagador é criado
payer	updated	quando o pagador é atualizado
payer	destroyed	quando o pagador é excluído
payment	created	quando o pagamento é criado
payment	updated	quando o pagamento é atualizado
payment	canceled	quando o pagamento é cancelado
payment	destroyed	quando o pagamento é excluído
payment	unauthorized	quando o pagamento é marcado como não autorizado
payment	registered_with_error	quando o pagamento é marcado com Erro no registro
payment	registered	quando o pagamento é registrado
payment	rescheduled	quando o pagamento é reagendado
payment	edited	quando o pagamento tem a edição confirmada
payment	paid	quando o pagamento é efetivado
remittance_cnab	updated	quando o arquivo de remessa é atualizado
regress_cnab	updated	quando o arquivo de retorno é atualizado

Cobrança criada

Cobrança Criada

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"created",
    "object_type":"charge",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charges/12"
    }]
  }

Informações enviadas quando uma Cobrança é criada.

Cobrança Atualizada

Cobrança Atualizada

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"updated",
    "object_type":"charge",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charges/12"
    }]
  }

Informações enviadas quando uma Cobrança é atualizada.

Cobrança Excluída

Cobrança Excluída

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"destroyed",
    "object_type":"charge",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charges/12"
    }]
  }

Informações enviadas quando uma Cobrança é excluída.

Cobrança Recebida

Cobrança Recebida

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"received",
    "object_type":"charge",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charges/12"
    }]
  }

Este payload é enviado para todos os tipos de Cobrança e indica que uma Cobrança foi recebida. De acordo com seu tipo uma cobrança é dita recebida quando:

Boleto: o usuário indica o recebimento de forma manual ou através de arquivo de retorno.
Gateway de pagamento: o gateway de pagamento informa o recebimento.

Recebimento de Cobrança desfeito

Recebimento de Cobrança desfeito

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"undone_receivement",
    "object_type":"charge",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charges/12"
    }]
  }

Este payload é disparado quando o recebimento da Cobrança é desfeito. No caso da cobrança do tipo boleto, ele indica apenas que no Cobrato o recebimento da Cobrança foi desfeito, mas não tem qualquer relação com o estado do boleto no banco. Já no caso da cobrança do tipo gateway de pagamento, está cobrança foi cancelada.

Cobrança Cancelada

Cobrança Cancelada

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"canceled",
    "object_type":"charge",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charges/12"
    }]
  }

Este payload é enviado apenas para cobranças do tipo gateway de pagamento e é disparado quando o gateway de pagamento informa sobre o cancelamento de uma Cobrança, que pode ter sido pedido pelo próprio usuário ou não. Ele indica que a Cobrança teve seu pagamento cancelado, ou seja, estornado.

Erro no recebimento de uma cobrança

Erro no recebimento de uma cobrança

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"receivement_error",
    "retryable":false,
    "card_error":true,
    "object_type":"charge",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charges/12"
    }]
  }

Este payload é enviado apenas para cobranças do tipo gateway de pagamento e é disparado quando o gateway de pagamento informa sobre um erro na tentativa de recebimnto de uma Cobrança. O parâmetro retryable indica se é passível ou não de retentativa. Já o parâmetro card_error indica se o erro foi oriundo de um problema no cartão ou não.

Erro no cancelamento de uma cobrança

Erro no cancelamento de uma cobrança

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"cancellation_error",
    "object_type":"charge",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charges/12"
    }]
  }

Este payload é enviado apenas para cobranças do tipo gateway de pagamento e é disparado quando o gateway de pagamento informa sobre um erro na tentativa de cancelamento de uma Cobrança.

Configuração de Cobrança criada

Configuração de Cobrança Criada

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"created",
    "object_type":"charge_config",
    "object_id":7,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charges_configs/7"
    }]
  }

Informações enviadas quando uma Configuração de Cobrança é Criada.

Configuração de Cobrança Atualizada

Configuração de Cobrança Atualizada

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"updated",
    "object_type":"charge_config",
    "object_id":7,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charge_configs/7"
    }]
  }

Informações enviadas quando uma Configuração de Cobrança é atualizada.

Configuração de Cobrança Excluída

Configuração de Cobrança Excluída

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"destroyed",
    "object_type":"charge_config",
    "object_id":7,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charge_configs/7"
    }]
  }

Informações enviadas quando uma Configuração de Cobrança é excluída.

Configuração de Cobrança desativada

Configuração de Cobrança Desativada

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"deactivated",
    "object_type":"charge_config",
    "object_id":7,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charge_configs/7"
    }]
  }

Informações enviadas quando uma Configuração de Cobrança é Desativada.

Cartão de crédito criado

Cartão de crédito Criado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"created",
    "object_type":"credit_card",
    "object_id":23,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/credit_card/23"
    }]
  }

Informações enviadas quando um Cartão de crédito é criado.

Cartão de crédito Atualizado

Cartão de crédito Atualizado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"updated",
    "object_type":"credit_card",
    "object_id":23,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/credit_card/23"
    }]
  }

Informações enviadas quando um Cartão de crédito é atualizado.

Modelo de Cobrança Criado


Modelo de Cobrança Criado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"created",
    "object_type":"charge_template",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charge_templates/12"
    }]
  }

Informações enviadas quando um Modelo de cobraça é criado.

Modelo de cobrança Atualizado

Modelo de cobrança Atualizado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"updated",
    "object_type":"charge_template",
    "object_id":13,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charge_templates/13"
    }]
  }

Informações enviadas quando um Modelo de cobrança é atualizado.

Modelo de cobrança Excluído

Modelo de cobrança Excluído

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"updated",
    "object_type":"charge_template",
    "object_id":14,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/charge_templates/14"
    }]
  }

Informações enviadas quando um Modelo de cobrança é excluído.

Pagador criado

Pagador Criado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"created",
    "object_type":"payer",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payers/12"
    }]
  }

Informações enviadas quando uma Pagador é criado.

Pagador Atualizado

Pagador Atualizado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"updated",
    "object_type":"payer",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payers/12"
    }]
  }

Informações enviadas quando uma Pagador é atualizado.

Pagador Excluído

Pagador Excluído

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"destroyed",
    "object_type":"payer",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payers/12"
    }]
  }

Informações enviadas quando uma Pagador é excluído.

Pagamento criado

Pagamento Criado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"created",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento é criado.

Pagamento Atualizado

Pagamento Atualizado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"updated",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento é atualizado.

Pagamento Cancelado

Pagamento Cancelado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"canceled",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento é cancelado.

Pagamento Excluído

Pagamento Excluído

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"destroyed",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento é excluído.

Pagamento Marcado como Não Autorizado

Pagamento Marcado como Não Autorizado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"unauthorized",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento é marcado como Não Autorizado.

Pagamento Marcado com Erro no Registro

Pagamento Marcado com Erro no Registro

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"registered_with_error",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento é marcado com Erro no Registro.

Pagamento registrado

Pagamento Registrado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"registered",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento é registrado.

Pagamento reagendado

Pagamento reagendado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"rescheduled",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento tem sua edição confirmada.

Pagamento com edição confirmada

Pagamento com edição confirmada

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"edited",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento tem sua edição confirmada.

Pagamento Efetivado

Pagamento Efetivado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"paid",
    "object_type":"payment",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/payments/12"
    }]
  }

Informações enviadas quando um Pagamento é efetivado.

Arquivo de remessa Atualizado

Arquivo de remessa Atualizadao

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"updated",
    "object_type":"remittance_cnab",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/remittance_cnabs/12"
    }]
  }

Informações enviadas quando um Arquivo de remessa é atualizado.

Arquivo de retorno Atualizado

Arquivo de retorno Atualizado

EXEMPLO DE PAYLOAD

  {
    "created_at":"2015-05-21T16:13:33Z",
    "event":"updated",
    "object_type":"regress_cnab",
    "object_id":12,
    "_links":[{
      "rel":"self",
      "method":"GET",
      "url":"https://app.cobrato.com/api/v1/regress_cnabs/12"
    }]
  }

Informações enviadas quando um Arquivo de retorno é atualizado.

Tipos de cobrança

Os tipos de cobrança implementados pelo Cobrato.

bank_billets (Boletos bancários)

Campo	Tipo	Comentário
bank_code	string	código do banco
bank_name	string	nome do banco
portfolio_codes	array	lista de códigos de portfólio do banco
regress	array	indica quais layouts CNAB de retorno são suportados para o banco
remittance	array	indica quais layouts CNAB de remessa são suportados para o banco

Lista de Todos os Tipos de Cobrança

Listar Tipos de Cobrança

DEFINIÇÃO

  GET https://app.cobrato.com/api/v1/charging_types

EXEMPLO DE REQUISIÇÃO

  $ curl -i \
    -H 'User-Agent: My App 1.0' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -X GET https://app.cobrato.com/api/v1/charging_types

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

  {
    "charging_types": {
      "bank_billets": [
        {
          "bank_code": "001",
          "bank_name": "BancoDoBrasil",
          "portfolio_codes": [ "11", "12", "16", "17", "18", "31", "51" ],
          "regress": [240],
          "remittance": []
        },
        {
          // informações de outro banco
        }
        ...
      ]
    }
  }

Retorna um objeto JSON contendo todos os tipos de cobraça implementados pelo Cobrato.