O Cobre Grátis é um aplicativo na web para emissão e gerenciamento de boletos bancários.
Com a API é possível integrar qualquer sistema, seja ele uma loja virtual de e-commerce ou um sistema de ERP como Oracle, SAP, Microsiga para que ele emita boleto bancário automaticamente. É uma ferramenta realmente poderosa.
Ganhe dinheiro integrando o Cobre Grátis!
A API é para nerds. Se você não é um programador, e não tem nenhum na sua empresa, entre em contato com HE:labs.
A API do Cobre Grátis é baseada nos princípios RESTful e usa conexão HTTP com todos os seus verbos (GET/POST/PUT/DELETE). Com a nossa API o seu desenvolvedor poderá integrar facilmente um programa existente à plataforma de emissão de boleto bancário.
A URL Base da API é https://app.cobregratis.com.br/
As requisições só podem ser feitas com SSL (https:// na frente da URL Base)
É possível requisitar os dados no formato JSON ou XML.
Por padrão, a API deve ser acessada através das mesmas URLs e verbos HTTP da interface HTML normal, adicionando-se o formato desejado (.xml ou .json) ao final da URL, ou então passando os headers Content-type e Accept na requisição HTTP com os valores de acordo com o formato desejado (application/xml ou application/json, respectivamente).
Para utilizar a API é necessário ter contratado um plano com suporte a API.
Para conhecer os planos e preços, acesse http://cobregratis.com.br/planos
Na documentação da API, utilizamos as seguintes convenções:
export $TOKEN=zjuio96wkixkzy6z98syA API retorna os códigos de resposta HTTP. Estas são as informações mais relevantes:
O Cobre Grátis utiliza Certificados SSL 256 bits.
Toda requisição realizada através da API deve utilizar o protocolo HTTPS pois estará passando informações de autenticação no cabeçalho da requisição.
As requisições realizadas na porta 80, serão automaticamente redirecionadas para a porta 443. Esta medida garante que nenhuma requisição realizada na API estará fora do protocolo seguro.
Todas as requisições realizadas nos servidores do Cobre Grátis serão criptografadas.
Todo acesso à API do Cobre Grátis é feito do ponto de vista de um usuário. Assim sendo, toda requisição à API deverá ser autenticada. A autenticação é feita via HTTP Basic, porém ao invés de passar o login e senha do usuário, como é tradicional, deve-se fornecer o Token de Autenticação do usuário no campo ‘login’ e nada no campo ‘password’. Alguns clientes HTTP podem reclamar do fato do campo ‘password’ estar vazio, nesse caso pode-se informar ‘X’ como senha, que o sistema irá ignorar.
O Token de Autenticação pode ser obtido no link Minhas Informações dentro do Cobre Grátis.
Exemplo de chamada API autenticada (onde "zjuio96wkixkzy6z98sy" é o Token de Autenticação do usuário):
curl -i -u zjuio96wkixkzy6z98sy:X -X GET \
-H 'Content-Type: application/xml' \
-H 'User-Agent: MyApp (yourname@example.com)' \
https://app.cobregratis.com.br/bank_billets/1.xml
HTTP/1.1 200 OK
Date: Fri, 05 Nov 2010 12:00:00 GMT
Content-Type: application/xml; charset=utf-8
...
<?xml version="1.0" encoding="UTF-8"?>
<bank_billet>
<id type="integer">1</id>
...
</bank_billet>Já a mesma solicitação sem os parâmetros de autenticação (ou com valores errados), resultaria em:
curl -i -X GET \
-H 'Content-Type: application/xml' \
-H 'User-Agent: MyApp (yourname@example.com)' \
https://app.cobregratis.com.br/bank_billets/1.xml
HTTP/1.1 401 Unauthorized
Date: Fri, 05 Nov 2010 12:00:00 GMT
Content-Type: application/xml; charset=utf-8
...
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<error>Email ou senha inválidos.</error>
</hash>Para realizar uma requisição, é necessário concatenar a URL Base ao path da ação de um determinado recurso. Cada ação disponível de cada recurso, terá uma URL específica, documentada nas APIs Disponíveis.
Por exemplo, para fazer uma requisição para a ação 'listar' do recurso 'boletos bancários' (GET /bank_billets.[format]), você deve usar a URL: https://app.cobregratis.com.br/bank_billets.json
Você deve incluir o header User-Agent com o nome da sua aplicação e um link ou endereço de e-mail dela, para que possamos entrar em contato caso 1) você esteja fazendo algo errado, e possamos avisá-lo antecipadamente antes de você ser bloqueado, ou 2) esteja fazendo algo muito legal, e possamos dar-lhe os parabéns :)
Segue um Exemplo:
User-Agent: Landing Commerce (http://landingcommerce.com.br)Se você não informar este cabeçalho, você receberá um erro 400 Bad Request.
Atenção: Por uma questão de compatibilidade, este bloqueio será realizado somente a partir de 01/01/2013.
Você deve fazer uso dos cabeçalhos HTTP de cache para diminuir a carga em nossos servidores (e aumentar a velocidade do seu aplicativo!).
A maioria dos retornos das requisições irão incluir um header ETag ou Last-Modified. Quando você solicitar um recurso pela primeira vez, armazene esse valor e nos envie de volta nas requisições seguintes nos headers If-None-Match e If-Modified-Since. Se o recurso não foi alterado, você receberá uma resposta com o header 304 Not Modified, o que economiza tempo e largura de banda, por evitar de te enviar os dados que você já tem.
Mais informações sobre Cache HTTP (em inglês): http://www.mnot.net/cache_docs/
Se os nossos servidores estiverem com problema, sua requisição receberá um retorno de erro com status 5xx.
Erro 500 significa que a aplicação está completamente indisponível, mas você pode receber também outros erros da família 500 em casos específicos, tais como 502 Bad Gateway, 503 Service Unavailable ou 504 Gateway Timeout.
É de sua responsabilidade identificar o erro e lidar com esses casos, fazendo com que o aplicativo tente enviar a requisição novamente depois de alguns minutos.
Nós temos uma página que informa o status dos servidores do Cobre Grátis em http://status.cobregratis.com.br/
Existem dois tipos de limite de requisições. Em ambos os casos a contagem é feita para cada Token de Autenticação utilizado.
Cada usuário pode realizar uma requisição a cada 1 segundo.
Caso o usuário realize duas requisições simultâneas, o servidor retorna o status HTTP 429 Too Many Requests.
Neste caso, o servidor envia o header Retry-After com o número de segundos que você deve esperar até realizar a próxima requisição.
Cada usuário pode realizar no máximo 500 requisições por hora. O número de requisições feitas pelo usuário é zerada no primeiro minuto de cada hora.
A cada requisição realizada, o servidor retorna os headers X-RateLimit-Limit e X-RateLimit-Remaining com o número de requisições permitidas e o número de requisições restantes para aquela hora.
Exemplo:
curl -i -u zjuio96wkixkzy6z98sy:X -X GET \
-H 'Content-Type: application/xml' \
-H 'User-Agent: MyApp (yourname@example.com)' \
https://app.cobregratis.com.br/bank_billets/1.xml
HTTP/1.1 200 OK
Date: Fri, 05 Nov 2010 12:00:00 GMT
Content-Type: application/xml; charset=utf-8
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 486
...Caso atinja o número máximo de requisições dentro de uma hora, o servidor retorna o status HTTP 429 Too Many Requests. Neste caso, você deve esperar até o primeiro minuto da hora seguinte para realizar a próxima requisição.
Por favor, nos diga como podemos melhorar a API. Se você tem alguma necessidade específica ou se encontrou um bug, use o GitHub issues. Fique a vontade para forkar este projeto e enviar pull requests com melhorias.