NAV
cURL

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/payers/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/payers/1"}
      ]
  }

É possível ter indeterminados pagadores, e a eles que pertencem a uma Conta de Serviço. 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 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/payers/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/payers/1"}
      ]
  }

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

Lista de Todos os Pagadors

Listar Pagadors

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

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

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

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

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

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,
    "_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:

Boleto

As Configurações de Cobrança do tipo Boleto (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 false por padrão
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 (apenas para o Bradesco)
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
_links array of object links da configuração de cobrança e de sua conta bancária

Gateway de Pagamento

Parâmetros

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’)
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
_links array of object links da configuração de cobrança e de sua conta bancária

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,
    "_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:

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

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)
registered_charges boolean (opcional) informa se a configuração de cobrança utiliza boletos registrados ou não, sendo false por padrão
remittance_agreement_code integer (opcional, requerido apenas se registered_charges for true) número do convênio com o banco (apenas para o Bradesco)
remittance_cnab_pattern integer (opcional, requerido apenas se registered_charges for true) padrão utilizado no arquivo CNAB de remessa. Os valores permitidos são 240 ou 400
transmission_code string (opcional, requerido apenas se registered_charges for true) código de transmissão (apenas para o Santander)
initial_remittance_number integer (opcional) número inicial de remessa, ou seja, qual foi o último número sequencial de remessa enviado para o banco (apenas para o Bradesco). 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

Gateway de Pagamento

Parâmetros

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’)*
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
status string (opctional, default “pending”) indica o status, ou etapa, de homologação em que configuração de cobrança está ('pending’, 'production_tests’, 'ok’)
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)

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

cielo-api30
Cielo API 3.0
cielo-ws15
Cielo Webservice 1.5

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)
registered_charges boolean (opcional) informa se a configuração de cobrança utiliza boletos registrados ou não, sendo false por padrão
remittance_agreement_code integer (opcional, requerido apenas se registered_charges for true) número do convênio com o banco (apenas para o Bradesco)
remittance_cnab_pattern integer (opcional, requerido apenas se registered_charges for true) padrão utilizado no arquivo CNAB de remessa. Os valores permitidos são 240 ou 400
transmission_code string (opcional, requerido apenas se registered_charges for true) código de transmissão (apenas para o Santander)
initial_remittance_number integer (opcional) número inicial de remessa, ou seja, qual foi o último número sequencial de remessa enviado para o banco (apenas para o Bradesco). 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

Gateway de Pagamento

Parâmetros

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_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)

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.

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 DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória) ou DV (Diversos)
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 DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória) ou DV (Diversos)
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 DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória) ou DV (Diversos)
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-30", # deprecated
    "paid_amount":"10.07",
    "paid_at":"2015-01-30",
    "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":"cancel","method":"POST","href":"https://app.cobrato.com/api/v1/charges/1/cancel"}
      ]
  }

Cada uma das cobranças criadas serão do mesmo tipo da configuração. Desta forma qualquer Cobrança criada sob uma Configuração de Cobrança do tipo Boleto será uma cobrança do tipo Boleto. Por este motivo os parâmetros, validações e alguns comportamentos serão variáveis de acordo com o tipo de 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
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
paid_amount decimal valor pago
paid_at datetime date e horário em que a cobrança foi paga
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). Por padrão é o que está definido na Configuração de 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)
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

Gateway de Pagamento

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.

Parâmetros

Campo Tipo Comentário
id integer
type string indica o tipo da cobrança. Nesse caso, “payment_gateway”
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
_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-30", # deprecated
    "paid_amount":"10.07",
    "paid_at":"2015-01-30",
    "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":"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:

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"],
        "document_kind":["não pode ficar em branco","não está incluído na lista"],
        "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.

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 (requerido) espécie do documento, podendo ser DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória) ou DV (Diversos)
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.
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
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
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 (opcional, requerido se registrable for true) número do endereço do pagador
complement string (opcional, requerido se registrable for true) complemento do endereço do pagador
street string (opcional, requerido se registrable for true) rua do endereço do pagador
neighbourhood string (opcional, requerido se registrable for true) bairro do endereço do pagador
zipcode string (opcional, requerido se registrable for true) cep do endereço do pagador
city string (opcional, requerido se registrable for true) cidade do endereço do pagador
state string (opcional, requerido se registrable for true) sigla do estado do endereço do pagador (“RJ” por exemplo)

Gateway de Pagamento

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 recebimento ou de erro é enviado via webhook.

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)
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, 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

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
number string (requerido) número do cartão
cvv string (requerido) código de segurança
expiration string (requerido) expiração do cartão, no formato “mm/aa”
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)

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.

Boleto

Parâmetros

Campo Tipo Comentário
due_date date (requerido) data de vencimento da cobrança
document_kind string (requerido) espécie do documento, podendo ser DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória) ou DV (Diversos)
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.
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
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 (opcional, requerido se registrable for true) número do endereço do pagador
complement string (opcional, requerido se registrable for true) complemento do endereço do pagador
street string (opcional, requerido se registrable for true) rua do endereço do pagador
neighbourhood string (opcional, requerido se registrable for true) bairro do endereço do pagador
zipcode string (opcional, requerido se registrable for true) cep do endereço do pagador
city string (opcional, requerido se registrable for true) cidade do endereço do pagador
state string (opcional, requerido se registrable for true) sigla do estado do endereço do pagador (“RJ” por exemplo)

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.

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
number string (requerido) número do cartão
cvv string (requerido) código de segurança
expiration string (requerido) expiração do cartão, no formato “mm/aa”
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)

Re-tentativa de efetivar de Cobrança (Gateway de pagamento)

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:

Gateway de Pagamento

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

Boleto

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)

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)

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)

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

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

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.

Gateway de Pagamento

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

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.

Cartão de Crédito

Cartão de Crédito

EXEMPLO

  {
    "id": 8,
    "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
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,
    "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 '{
        "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
number string (requerido) número do cartão
expiration string (requerido) expiração do cartão, no formato “mm/aa”
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)
cvv string (requerido) código de segurança do cartão
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

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

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,
    "charge_config_id": 1,
    "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": "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/remittance_cnabs/1/file"},
        {"rel": "charges", "method": "GET", "href": "http://localhost:3000/api/v1/remittance_cnabs/1/charges"}
      ]
  }

Os Arquivos CNAB de Remessa são arquivos enviados para o banco com o objetivo de registrar novos títulos, podendo ser gerado a partir de uma ou mais Cobranças. Se forem enviadas Cobranças de Configurações de Cobranças diferentes, será gerado um CNAB de remessa para cada Configuração de Cobrança.

Parâmetros

Campo Tipo Comentário
id integer identificador do CNAB de remessa
charge_config_id string identificador da configuração de cobrança no Cobrato
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,
    "charge_config_id": 1,
    "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": "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/remittance_cnabs/1/file"},
        {"rel": "charges", "method": "GET", "href": "http://localhost:3000/api/v1/remittance_cnabs/1/charges"}
      ]
  }

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 '{
        "charge_ids": [12, 13, 15, 18]
      }'

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Criated

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

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

Parâmetros

Campo Tipo Comentário
charge_ids array of integers (requerido, veja a nota acima) Lista com os ids das cobranças que devem estar incluídas no(s) arquivo(s) CNAB de Remessa
charge_config_ids array of integers (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 de cobrança 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 de cobrança 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.

CNAB de Retorno

CNAB de Retorno

EXEMPLO

  {
    "id": 1,
    "charge_config_id": 9,
    "status": "processed",
    "report": {
      "charges_not_found": 0,
      "received_charges": [{
        "id": 46,
        "_links": [{ "rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/charges/46" }]
      }],
      "registered_charges": [{
        "id": 45,
        "_links": [{ "rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/charges/45" }]
      }]
    },
    "_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_config/1"},
        {"rel": "file", "method": "GET", "href": "https://app.cobrato.com/api/v1/regress_cnabs/1/file"}
      ]
  }

Os arquivos CNABs de retorno, pertencem a uma determinada configuração de cobrança, contendo informações de uma ou mais cobranças desta conta.

Parâmetros

Campo Tipo Comentário
id integer identificador do CNAB de retorno
charge_config_id string identificador da configuração de cobrança no Cobrato
status string situação do arquivo CNAB, podendo ser “processing” (processando), “processed” (processado) e “processing_error” (erro de processamento)
report string relatório de processamento do arquivo CNAB, os parâmetros do relatório se encontram na tabela abaixo
_links array of object links relacionado CNAB de retorno

Parâmetros do Relatório de Processamento

Campo Tipo Comentário
charges_not_found integer Quantidade de cobranças que estavam no CNAB, mas não foram localizadas no sistema
received_charges array of objects Informações das cobranças recebidas pelo CNAB, contendo o código identificador e link
registered_charges array of objects Informações das cobranças registradas pelo CNAB, contendo o código identificador e link

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,
    "status": "processed",
    "report": {
      "charges_not_found": 0,
      "received_charges": [{
        "id": 46,
        "_links": [{ "rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/charges/46" }]
      }],
      "registered_charges": [{
        "id": 45,
        "_links": [{ "rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/charges/45" }]
      }]
    },
    "_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 Todas as 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.

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 '{
          "charge_config_id": 1,
          "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":{
      "charge_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
charge_config_id string (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 CONTA BANCÁRIA 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 COBRANÇA 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:

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_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
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

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:

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_accounts/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.

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.

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.