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,
    "writing_off_deadline": null,
    "available_charge_types": ["billet"],
    "_links":
      [
        {"rel":"self","method":"GET","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"update","method":"PUT","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"destroy","method":"DELETE","href":"https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel":"bank_account","method":"GET","href":"https://app.cobrato.com/api/v1/bank_accounts/1"},
        {"rel":"payee","method":"GET","href":"https://app.cobrato.com/api/v1/payee/1"}
      ]
  }

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

Conta bancária

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

Parâmetros

Campo Tipo Comentário
id integer
type string indica o tipo da configuração de cobrança. Nesse caso ‘billet’
name string nome que identifica esta configuração de cobrança
status string 'ok’ ou 'pending’ para indicar se configuração de cobrança está ou não homologada, respectivamente
payee_id integer identificador do beneficiário desta configuração de cobrança no Cobrato
bank_account_id integer identificador da conta bancária desta configuração de cobrança no Cobrato
portfolio_code string código de portfólio
agreement_code string código de convênio ou do beneficiário, de acordo com o banco. No caso do Itaú deve ser igual ao campo 'account’ da conta bancária
agreement_code_digit string verificador do código de convênio, de acordo com o banco
initial_number integer número inicial do nosso número, sendo atribuído automaticamente e sequencialmente as cobranças
next_number integer próximo nosso número a ser atribuído a uma cobrança criada a partir desta configuração de cobrança
end_number integer número final do nosso número, sendo o último número a ser atribuído, após isso a sequência é reiniciada
registered_charges boolean informa se a configuração de cobrança utiliza boletos registrados ou não, sendo 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
writing_off_deadline integer número de dias após o vencimento da cobrança para que seja feita a baixa automática do título no banco (apenas para cobranças registradas com padrão 240)
available_charge_types array of strings tipos de cobrança disponíveis. No caso de Configuração de Cobrança por Conta Bancária, será disponível somente a opção “billet”. Este campo será gerenciado pelo Cobrato.
_links array of object links da configuração de cobrança e de sua conta bancária

Gateway de Pagamento

Parâmetros comuns a todos os Gateways

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

Parâmetros específicos para gateway Cielo

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

Parâmetros específicos para gateway PJBank

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

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

Mostrar Configuração de Cobrança

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA (BOLETO)

  {
    "id": 1,
    "type": "billet",
    "payee_id": 1,
    "bank_account_id": 1,
    "portfolio_code": "17",
    "agreement_code": "12345678",
    "agreement_code_digit": "1",
    "name": "Configuração de Cobrança por Boleto",
    "initial_number": 1,
    "next_number": 1,
    "end_number": 1000,
    "status": "pending",
    "registered_charges": true,
    "remittance_agreement_code": 4576361,
    "remittance_cnab_pattern": 400,
    "initial_remittance_number": 1,
    "transmission_code": "987655",
    "pre_released_billet": false,
    "writing_off_deadline": null,
    "available_charge_types": ["billet"],
    "_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
writing_off_deadline integer (opcional) número de dias após o vencimento da cobrança para que seja feita a baixa automática do título no banco. Valor pode variar entre 7 e 90. (apenas para cobranças registradas com padrão 240)

Gateway de Pagamento

Parâmetros comuns a todos os Gateways

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

Parâmetros para o gateway Cielo

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

Parâmetros para o gateway PJBank

Campo Tipo Comentário
gateway_id string (requerido, somente quando o campo 'gateway_key’ estiver preenchido) credencial do contrato com o gateway de pagamento para cobranças de cartão de crédito
gateway_key string (requerido, somente quando o campo 'gateway_id’ estiver preenchido) chave de acesso atribuída pelo gateway de pagamento para cobranças de cartão de crédito
billet_gateway_id string (requerido, somente quando o campo 'billet_gateway_key’ estiver preenchido) credencial do contrato com o gateway de pagamento para cobranças de boleto
billet_gateway_key string (requerido, somente quando o campo 'billet_gateway_id’ estiver preenchido) chave de acesso atribuída pelo gateway de pagamento para cobranças de boleto

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

cielo-api30
API e-Commerce Cielo
cielo-ws15
Webservice 1.5
pjbank
PJBank

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

Atualizar Configuração de Cobrança

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

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

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Boleto

Parâmetros

Campo Tipo Comentário
payee_id integer (requerido) código de identificação do beneficiário ao qual a configuração de cobrança irá pertencer
portfolio_code string (requerido) código de portfólio, validação conforme o banco
agreement_code string (requerido, com exceção do Itaú onde é preenchido automaticamente) código de convênio ou do beneficiário, de acordo com o banco
agreement_code_digit string (requerido, com exceção do HSBC e Itaú, sendo preenchido automaticamente para o último) verificador do código de convênio, de acordo com o banco
name string (requerido) nome que identifica esta configuração de cobrança
initial_number integer (requerido) número inicial do nosso número, sendo atribuído automaticamente e sequencialmente às cobranças
end_number integer (opcional) número final do nosso número, sendo o último número a ser atribuído, após isso a sequência é reiniciada
next_number integer (opcional) próximo nosso número a ser atribuído a uma cobrança criada a partir desta configuração de cobrança (é incrementado automatica e sequencialmente)
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
writing_off_deadline integer (opcional) número de dias após o vencimento da cobrança para que seja feita a baixa automática do título no banco. Valor pode variar entre 7 e 90. (apenas para cobranças registradas com padrão 240)

Gateway de Pagamento

Parâmetros comuns a todos os Gateways

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

Parâmetros para o gateway Cielo

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

Parâmetros para o gateway PJBank

Campo Tipo Comentário
gateway_id string (requerido, somente quando o campo 'gateway_key’ estiver preenchido) credencial do contrato com o gateway de pagamento para cobranças de cartão de crédito
gateway_key string (requerido, somente quando o campo 'gateway_id’ estiver preenchido) chave de acesso atribuída pelo gateway de pagamento para cobranças de cartão de crédito
billet_gateway_id string (requerido, somente quando o campo 'billet_gateway_key’ estiver preenchido) credencial do contrato com o gateway de pagamento para cobranças de boleto
billet_gateway_key string (requerido, somente quando o campo 'billet_gateway_id’ estiver preenchido) chave de acesso atribuída pelo gateway de pagamento para cobranças de boleto

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

Cobranças via Conta Bancária

Boleto

Parâmetros

Campo Tipo Comentário
id integer
type string indica o tipo da cobrança. Nesse caso, “billet”
charge_config_id integer identificador da configuração de cobrança a qual esta cobrança pertence
due_date date data de vencimento da cobranca
document_kind string espécie do documento, podendo ser DM (Duplicata Mercantil), DS (Duplicata de Serviço), NP (Nota Promissória) ou DV (Diversos)
document_date date data de emissão do documento
document_number string número do documento é o número utilizado e controlado pelo beneficiário para identificar o título de cobrança.
our_number string nosso número
our_number_digit integer digito do verificador do nosso número
custom_our_number boolean indica se a cobrança utiliza um “nosso número” customizado. O valor padrão é false, mas caso definido true, o campo ‘our_number’ se torna requerido
charged_amount decimal valor cobrado no boleto
interest_amount_per_month decimal porcentagem de juros mensal que deve ser aplicado em caso de atraso. No boleto será mostrado o valor diário de juros que será calculado
mulct_type string indica o tipo de multa que deve ser aplicada em caso de atraso (“percentage” para porcentagem, “currency” para valor em reais)
mulct_value decimal valor da multa que deve ser aplicada em caso de atraso, com base em seu tipo
instructions string instruções de pagamento do boleto
demonstrative string demonstrativo do Boleto
notification_emails array of strings emails que receberão notificações sobre a cobrança
payer_emails array of strings (DEPRECATED: use notification_emails) emails que receberão notificações sobre a cobrança
received boolean (DEPRECATED: use paid_at) indica se a cobrança foi recebida
received_amount decimal (DEPRECATED: use paid_amount) valor pago
received_at datetime (DEPRECATED: use paid_at) date e horário em que a cobrança foi paga
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

Cobranças via Gateway de Pagamento

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

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

Cartão de crédito

Parâmetros

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

Boleto

Parâmetros

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

Cobrança via Conta Bancária

Boleto

Parâmetros

Campo Tipo Comentário
charge_config_id integer (requerido) código de identificação da configuração de cobrança da qual a cobrança irá pertencer
due_date date (requerido) data de vencimento da cobrança
document_kind string (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 - requerido caso auto_send_billet seja true) emails que receberão notificações sobre a cobrança
payer_emails array of strings (DEPRECATED: use notification_emails) (opcional - requerido caso auto_send_billet seja true) emails que receberão notificações sobre a cobrança
document_date date (opcional) data de emissão do documento
our_number string (opcional) nosso número. Caso não informado, é atribuído automaticamente pelo sistema
our_number_digit integer (opcional) digito do verificador do nosso número
custom_our_number boolean (opcional) indica se a cobrança utiliza um “nosso número” customizado. O valor padrão é false, mas caso definido true, o campo 'our_number’ se torna requerido
interest_amount_per_month decimal (opcional) porcentagem de juros mensal que deve ser aplicado em caso de atraso. No boleto será mostrado o valor diário de juros que será calculado
mulct_type string (opcional) indica o tipo de multa que deve ser aplicada em caso de atraso (“percentage” para porcentagem, “currency” para valor em reais)
mulct_value decimal (opcional) valor da multa que deve ser aplicada em caso de atraso, com base em seu tipo
instructions string (opcional) instruções de pagamento do boleto. As linhas devem ser separadas por “\n”. Deve ter no máximo 9 linhas com 65 caracteres cada, sendo que se tiver definido multa e juros para a cobrança, será permitido no máximo 6 linhas, pois 3 já serão utilizadas automaticamente.
demonstrative string (opcional) demonstrativo do Boleto. As linhas devem ser separadas por “\n”. Deve ter no máximo 9 linhas com 65 caracteres cada, sendo que se tiver definido multa e juros para a cobrança, será permitido no máximo 6 linhas, pois 3 já serão utilizadas automaticamente.
charge_template_id integer (opcional) número do modelo de cobrança a ser utilizado. A cobrança será criada com base nos atributos preestabelecidos do modelo. Contudo, os valores enviados na criação terão preferência
for_homologation boolean (requerido, se a configuração de cobrança não estiver homologada) indica se é uma cobrança para ser utilizada na homologação da Configuração de cobrança
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)

Cobranças via Gateway de Pagamento

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

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

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

Cartão de crédito

Parâmetros

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

payer_attributes

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)

Boleto

Parâmetros

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

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 Cobrança

Atualizar Cobrança

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Cobranças via Conta Bancária

Boleto

Parâmetros

Campo Tipo Comentário
due_date date (requerido) data de vencimento da cobrança
document_kind string (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)

Cobranças via Gateway de Pagamento

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

Cartão de crédito

Parâmetros

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

payer_attributes

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

credit_card_attributes

Campo Tipo Comentário
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)

Boleto

Parâmetros

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

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)

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

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

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

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

Exclusão de Cobrança

Excluir Cobrança

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

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

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

Cartão de crédito

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

Boleto via Gateway de pagamento

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

Boleto via Conta Bancária

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

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

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

Receber Cobrança (Boleto)

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Parâmetros (Boleto)

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

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

Desfazer Recebimento de Cobrança (Boleto)

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

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

Renovar Cobrança (Boleto)

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

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

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

Parâmetros (Boleto)

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

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

Mostrar Boleto da Cobrança (URL)

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE CORPO DA RESPOSTA COM SUCESSO

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

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

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

Enviar Boleto da Cobrança

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

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

      422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Parâmetros

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

Cancelar cobrança

Cancela Cobrança

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

Cancela determinada cobrança.

Cartão de crédito

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

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

Boleto via Gateway

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

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

Boleto via Conta Bancária

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

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

Revogar Cobrança

Revogar Cobrança

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA EXCLUÍDA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA CANCELADA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM COBRANÇA INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Configuração de Pagamento

Configuração de Pagamento

EXEMPLO

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

Informações da Configuração de Pagamento

Mostrar Configuração de Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Lista de Todas as Configurações de Pagamento

Listar Configurações de Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Criação de Configuração de Pagamento

Criar Configuração de Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Parâmetros

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

Atualização de Configuração de Pagamento

Atualizar Configuração de Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

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

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Parâmetros

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

Exclusão de Configuração de Pagamento

Excluir Configuração de Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

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

    404 Not Found

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

Pagamento

Pagamentos

EXEMPLO

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

Parâmetros

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

Informações do Pagamento

Mostrar Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Lista de todos os Pagamentos

Listar Pagamentos

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Criação de Pagamento

Criar Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Parâmetros comuns à todas as formas de pagamento

Campo Tipo Comentário
payment_config_id integer (requerido) código de identificação da configuração de pagamento à qual o pagamento irá pertencer
payment_method string (requerido) forma de pagamento ('credit_other_ownership’, 'credit_same_ownership’, 'credit_savings_account’, 'doc_other_ownership’, 'doc_same_ownership’, 'ted_other_ownership’, 'ted_same_ownership’, 'gps’, 'darf’, 'das’, 'ipva’, icms_sp’, 'dpvat’)
payment_type string (requerido) tipo de pagamento. Os possíveis valores variam de acordo com o “payment_method” (vide tabela 1)
amount decimal (requerido) valor do pagamento
date date (requerido) data do pagamento
note string (opcional) oberservação do pagamento
payee_name string (opcional) nome do beneficiário

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

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

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

Campo Tipo Comentário
account string (requerido) número da conta bancária para o pagamento
account_digit string (requerido) dígito da conta bancária para fazer o pagamento
agency string (requerido) número da agência da conta bancária para fazer o pagamento
payee_name string (requerido) nome do beneficiário
payee_document_type string (requerido) tipo do documento do beneficiário
payee_document string (requerido) número do documento do beneficiário

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

Campo Tipo Comentário
bank_code string (requerido) código de 3 dígitos do banco da conta bancária para o pagamento
doc_goal string (opcional) código referente ao objetivo do DOC. Possíveis valores na tabela 2

Parâmetros quando payment_method é 'ted_other_ownership’

Campo Tipo Comentário
bank_code string (requerido) código de 3 dígitos do banco da conta bancária para o pagamento
ted_goal string (opcional) código referente ao objetivo do TED. Possíveis valores na tabela 3

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

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

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

Campo Tipo Comentário
barcode string (requerido) Código de barras do boleto bancário
payee_name string (requerido) nome do beneficiário
payee_document_type string (requerido) tipo do documento do beneficiário ('cpf’ ou 'cnpj’)
payee_document string (requerido) número do documento do beneficiário
due_date date (opicional, já que é identificado no código de barras) Data de vencimento do boleto
discount_amount decimal (opcional) valor do desconto

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

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

Parâmetros quando payment_method é 'dealdership’ ou 'tribute_with_barcode’

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

Parâmetros quando payment_method é 'fgts’

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

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

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

Parâmetros quando payment_method é 'gps’

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

Parâmetros quando payment_method é 'darf’

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

Parâmetros quando payment_method é 'das’

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

Parâmetros quando payment_method é 'ipva’

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

Parâmetros quando payment_method é 'icms_sp’

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

Parâmetros quando payment_method é 'dpvat’

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

Atualização de Pagamento

Atualizar Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Parâmetros comuns a todas as formas de pagamento

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

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

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

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

Campo Tipo Comentário
bank_code string (requerido) código de 3 dígitos do banco da conta bancária para o pagamento
account string (requerido) número da conta bancária para o pagamento
account_digit string (requerido) dígito da conta bancária para fazer o pagamento
agency string (requerido) número da agência da conta bancária para fazer o pagamento
payee_name string (requerido) nome do beneficiário
payee_document_type string (requerido) tipo do documento do beneficiário
payee_document string (requerido) número do documento do beneficiário

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

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

Parâmetros quando payment_method é 'ted_other_ownership’

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

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

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

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

Campo Tipo Comentário
payee_name string (requerido) nome do beneficiário
payee_document_type string (requerido) tipo do documento do beneficiário ('cpf’ ou 'cnpj’)
payee_document string (requerido) número do documento do beneficiário
due_date date (requerido) Data de vencimento do boleto
discount_amount decimal (opcional) valor do desconto

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

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

Parâmetros quando payment_method é 'dealdership’ ou 'tribute_with_barcode’

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

Parâmetros quando payment_method é 'fgts’

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

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

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

Parâmetros quando payment_method é 'gps’

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

Parâmetros quando payment_method é 'darf’

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

Parâmetros quando payment_method é 'das’

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

Parâmetros quando payment_method é 'ipva’

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

Parâmetros quando payment_method é 'icms_sp’

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

Parâmetros quando payment_method é 'dpvat’

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

Exclusão de Pagamento

Excluir Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

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

Cancelamento de Pagamento

Cancelar Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

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

Marcar Pagamento como não autorizado

Marcar Pagamento como não autorizado

DEFINIÇÃO

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

  EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Marcar pagamento com Erro no Registro

Marcar pagamento com Erro no Registro

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM PAGAMENTO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

Marca o pagamento com Erro no registro manualmente.

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

Schema de Pagamento

Schema de Pagamento

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE CORPO DA RESPOSTA COM SUCESSO

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

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Parâmetros

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

Tabelas

Possíveis valores para payment_type (tabela 1)

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

Possíveis valores para doc_goal (tabela 2)

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

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

Possíveis valores para ted_goal (tabela 3)

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

Possíveis valores para payment_option (tabela 4)

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

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,
    "config_id": 1,
    "type": "charge",
    "file_name": "CI14058A.REM",
    "status": "processed",
    "_links":
      [
        {"rel": "self", "method": "GET", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1"},
        {"rel": "destroy", "method": "DELETE", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1"},
        {"rel": "config", "method": "GET", "href": "https://app.cobrato.com/api/v1/charge_configs/1"},
        {"rel": "file", "method": "GET", "href": "https://app.cobrato.com/api/v1/remittance_cnabs/1/file"},
        {"rel": "items", "method": "GET", "href": "http://localhost:3000/api/v1/remittance_cnabs/1/items"}
      ]
  }

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

Parâmetros

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

Informações do CNAB de Remessa

Mostrar CNAB de Remessa

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Lista de Todas as CNABs de Remessa

Listar CNABs de Remessa

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Criação de Arquivo CNAB de Remessa

Criar Arquivo CNAB de Remessa

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA

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

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

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

Parâmetros

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

Exclusão de CNAB de Remessa

Excluir CNAB de Remessa

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM CNAB DE REMESSA INEXISTENTE

    404 Not Found

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

Arquivo do CNAB de Remessa

Mostrar Arquivo do CNAB de Remessa (URL)

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM CNAB DE REMESSA INEXISTENTE

    404 Not Found

EXEMPLO DE CORPO DA RESPOSTA COM SUCESSO

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

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

Lista de Todas as Cobrança do Arquivo de Remessa

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Lista de Todos os items do Arquivo de Remessa

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA (COBRANÇAS)

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

EXEMPLO DE CORPO DA RESPOSTA (PAGAMENTOS)

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

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

CNAB de Retorno

CNAB de Retorno

EXEMPLO

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

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

Parâmetros

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

Informações do CNAB de Retorno

Mostrar CNAB de Retorno

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Lista de Todos os CNABs de Retorno

Listar CNABs de Retorno

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

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

Criação de CNAB de Retorno

Criar CNAB de Retorno

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    202 Accepted

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

Cria um CNAB de retorno inicia o processamento do arquivo.

Parâmetros

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

Exclusão de CNAB de retorno

Excluir CNAB de retorno

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM ARQUIVO DE RETORNO INEXISTENTE

    404 Not Found

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

Arquivo do CNAB de Retorno

Mostrar Arquivo do CNAB de Retorno (URL)

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM ARQUIVO DE RETORNO INEXISTENTE

    404 Not Found

EXEMPLO DE CORPO DA RESPOSTA COM SUCESSO

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

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

Webhook

Webhook

EXEMPLO

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

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

Parâmetros

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

Informações do Webhook

Mostra Webhook

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Lista de Todos os Webhooks


Listar Webhooks

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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

Criação de Webhook

Criar Webhook

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    201 Created

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

EXEMPLO DE CORPO DA RESPOSTA COM INSUCESSO

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

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

Parâmetros

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

Atualização de Webhook

Atualizar Webhook

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    200 OK

EXEMPLO DE ESTADO DA RESPOSTA COM BENEFICIÁRIO INEXISTENTE

    404 Not Found

EXEMPLO DE ESTADO DA RESPOSTA COM INSUCESSO

    422 Unprocessable Entity

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

Parâmetros

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

Exclusão de Webhook

Excluir Webhook

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA COM SUCESSO

    204 No Content

EXEMPLO DE ESTADO DA RESPOSTA COM WEBHOOK INEXISTENTE

    404 Not Found

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

Payloads

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

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

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
payment created quando o pagamento é criado
payment updated quando o pagamento é atualizado
payment canceled quando o pagamento é cancelado
payment destroyed quando o pagamento é excluído
payment unauthorized quando o pagamento é marcado como não autorizado
payment registered_with_error quando o pagamento é marcado com Erro no registro
regress_cnab created quando o arquivo de retorno é criado
regress_cnab updated quando o arquivo de retorno é atualizado

Cobrança criada

Cobrança Criada

EXEMPLO DE PAYLOAD

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

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

Cobrança Atualizada

Cobrança Atualizada

EXEMPLO DE PAYLOAD

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

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

Cobrança Excluída

Cobrança Excluída

EXEMPLO DE PAYLOAD

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

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

Cobrança Recebida

Cobrança Recebida

EXEMPLO DE PAYLOAD

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

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

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.

Pagamento criado

Pagamento Criado

EXEMPLO DE PAYLOAD

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

Informações enviadas quando um Pagamento é criado.

Pagamento Atualizado

Pagamento Atualizado

EXEMPLO DE PAYLOAD

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

Informações enviadas quando um Pagamento é atualizado.

Pagamento Excluído

Pagamento Excluído

EXEMPLO DE PAYLOAD

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

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

Pagamento Marcado como Não Autorizado

Pagamento Marcado como Não Autorizado

EXEMPLO DE PAYLOAD

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

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

Pagamento Marcado com Erro no Registro

Pagamento Marcado com Erro no Registro

EXEMPLO DE PAYLOAD

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

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

Arquivo de retorno criado

Arquivo de retorno Criado

EXEMPLO DE PAYLOAD

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

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

Arquivo de retorno Atualizado

Arquivo de retorno Atualizado

EXEMPLO DE PAYLOAD

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

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

Tipos de cobrança

Os tipos de cobrança implementados pelo Cobrato.

bank_billets (Boletos bancários)

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

Lista de Todos os Tipos de Cobrança

Listar Tipos de Cobrança

DEFINIÇÃO

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

EXEMPLO DE REQUISIÇÃO

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

EXEMPLO DE ESTADO DA RESPOSTA

    200 OK

EXEMPLO DE CORPO DA RESPOSTA

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

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