Introdução da API
A iugu disponibiliza uma interface de programação web, no modelo REST, disponível em um endereço de web. Por meio desta interface é possível conversar com o sistema de iugu, comandando ações, verificando configurações e sincronizando com seu sistemas.
O endereço base de comunicação é api.iugu.com, sempre com o protocolo seguro https. Além disto, agrupamos a versão por diretório.
Endereço para comunicação / Endpoint API
Este documento trata da versão da API 1.0.
O endereço para se comunicar através desta versão é:
https://api.iugu.com/v1/
Exemplos da utilização prática das chamadas de nossa API podem ser conferidas na seção de conceitos técnicos.
Autenticação
A autenticação na iugu é feita através da utilização de uma chave de API. Esta chave serve para que o sistema identifique a sua conta, e concede permissões para que o sistema se comunique com a iugu em nome da conta em questão.
Há duas maneiras de se autenticar, sendo a primeira, e mais recomendada, utilizando HTTP Basic Auth. A outra maneira é enviar o API Token num parâmetro de nome api_token.
As chaves de API podem ser TEST (Teste) ou LIVE (Produção), sendo que cada chamada irá se comunicar com os respectivos ambientes e os dados também estarão disponíveis de forma isolada no painel, dependendo do modo que estiver ativado.
Toggle de Produção/Teste no painel
Este toggle não altera a comunicação da API e sim a visão e ações executadas exclusivamente através do painel.
Trate suas chaves de API como senhas
Não inclua sua chave de API publicamente em nenhum lugar do seu site ou javascript. Lembre-se que esta chave dá acesso total ao seus dados na iugu.
Para adicionar uma chave de API, acesse o endereço https://app.iugu.com e siga o tutorial abaixo
Para gerar o header de autenticação HTTP básico deve-se seguir os seguintes passos:
- Utilizar em nome de usuário seu API token e utilizar senha em branco separados por um dois pontos (:), exemplo: 2fd7f47f8b96c44e300a60ce35cfe414:
- Codificar a string resultante como uma sequência de octetos
- Codificar a string resultante utilizando Base64
- Concatenar a string resultando com o sufixo Authorization: Basic
- Resultar com uma string final parecida com Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
- Enviar essa informação no Header da request
HTTP Basic Auth
Você pode aprender mais sobre HTTP Basic Auth em https://en.wikipedia.org/wiki/Basic_access_authentication
As requests permitem o envio de um parâmetro chamado api_token onde pode ser enviado o API Token gerado anteriormente em vez de utilizar o HTTP Basic Auth.
Boas práticas
Como boa prática é interessante não misturar o que são de fato parâmetros da request da autenticação da mesma. Portanto, recomendamos a utilização de HTTP Basic Auth.
Resposta em JSON ou XML
Afim de facilitar a interoperabilidade entre sistemas, todas as nossas chamadas de API podem responder no formato JSON ou XML, conforme a sua escolha, sendo que o padrão é retornar em JSON. Isto é, quando não é especificado um formato.
Como especificar o formato de resposta
Você tem duas formas de especificar o formato de resposta:
- Adicionar a extensão ".xml" ou ".json" no final dos endereços de API
- Enviar um Header HTTP contento o tipo de conteúdo que você espera. Sendo "Accept: application/json" para JSON e "Accept: application/xml" para XML.
Erros
A Iugu API utiliza os próprios Códigos de Status HTTP para indicar sucesso ou falha da chamada. Em geral os códigos iniciados com 2 indicam sucesso, os iniciados com 4 indicam erro (Ex: Falta de parâmetro obrigatório) e iniciados com 5 indicam erro interno nos servidores da Iugu.
Pode conter tanto uma string de erro como um hash contendo o atributo e seus erros.
Formato para erros nos status 400, 401 e 404
{
"errors": "Unauthorized"
}Formato para erros status 422
{
"errors": {
"due_date": [
"should not be in the past"
]
}
}Erros mais comuns
não pode ficar em branco
can't be blank
não pode ficar vazio
can't be empty
deve ser maior que N
must be greater than N
deve ser maior ou igual a N
must be greater than or equal to N
não está incluído na lista
is not included in the list
não é válido
is invalid
deve ser menor que N
must be less than N
deve ser menor ou igual a N
must be less than or equal to N
não é um número
is not a number
não pode estar no passado
should not be in the past
Paginação
Em nossas APIs de listagem, usamos dois parâmetros que possibilitam a paginação em sua aplicação.
São eles:
start: Determina quantos registros no início da sua listagem serão ignorados.
limit: Determina o máximo de registros que serão retornados.
Obs.: Esse parâmetros funcionam mesmo que não sejam chamados simultaneamente.
Veja abaixo dois exemplos distintos da chamada de API para listagem de faturas:
1) Sem parâmetros de paginação
curl --request GET \
--url https://api.iugu.com/v1/invoices{
"facets": {
"status": {
"_type": "terms",
"missing": 0,
"total": 10,
"other": 0,
"terms": [
{
"term": "paid",
"count": 5
},
{
"term": "pending",
"count": 5
}
]
}
},
"totalItems": 2,
"items": [
#Fatura1, #Fatura2, #Fatura3, #Fatura4, #Fatura5, #Fatura6, #Fatura7, #Fatura8, #Fatura9, #Fatura10
]
}curl --request GET \
--url 'https://api.iugu.com/v1/invoices?start=0&limit=5'{
"facets": {
"status": {
"_type": "terms",
"missing": 0,
"total": 10,
"other": 0,
"terms": [
{
"term": "paid",
"count": 5
},
{
"term": "pending",
"count": 5
}
]
}
},
"totalItems": 2,
"items": [
#Fatura1, #Fatura2, #Fatura3, #Fatura4, #Fatura5
]
}curl --request GET \
--url 'https://api.iugu.com/v1/invoices?start=5&limit=5'{
"facets": {
"status": {
"_type": "terms",
"missing": 0,
"total": 10,
"other": 0,
"terms": [
{
"term": "paid",
"count": 5
},
{
"term": "pending",
"count": 5
}
]
}
},
"totalItems": 2,
"items": [
#Fatura6, #Fatura7, #Fatura8, #Fatura9, #Fatura10
]
}Criar Fatura
Cria uma Fatura para um Cliente (Podendo ser um objeto cliente ou apenas um e-mail).
Reembolsar Fatura
Efetua o reembolso de uma Fatura. Somente alguns meios de pagamento permitem o reembolso, como por exemplo o Cartão de Crédito. Após o reembolso, a Fatura fica com o status de "reembolsada" / "refunded".
Remover Fatura
Remove uma Fatura permanentemente.
Cuidado
Apenas faturas com o status "canceled" podem ser removidas. Embora não seja recomendado a remoção permanente da fatura.
Gerar Segunda Via de Fatura
Gera segunda via de uma Fatura. Somente faturas pendentes podem ter segunda via gerada. A fatura atual é cancelada e uma nova é gerada com status "pendente" / "pending".
Listar Faturas
Retorna uma lista com todas as faturas em sua conta ordenadas pela data de Criação, sendo a primeira a que foi criada mais recentemente. O campo "totalItems" contém sempre a quantidade de faturas cadastradas, independente dos parâmetros de pesquisa utilizados e o resultado da pesquisa fica sempre dentro de "items".
Tokenização e iugu.js
A maneira mais segura de criar tokens é através da biblioteca iugu.js, que garante a comunicação entre o navegador do usuário final diretamente com nossos servidores.
Saiba mais sobre o iugu.js e Tokenização.
Criar Token
O Token é uma representação do meio de pagamento do cliente (por ex: seu cartão de crédito), sendo totalmente seguro, de forma que não é possível que alguém consiga as informações do cartão de crédito do cliente utilizando esse token. O token é gerado para uma transação específica, tornando-o ainda mais seguro.
Cuidado
A API de Criação de Token não utiliza a autenticação via api_token.
Alerta de conformidade com PCI
Esta chamada API deve ser utilizada apenas em aplicações sem compatibilidade com JavaScript como por exemplo aplicações móveis. Se você efetuar esta chamada por dentro de seus servidores estará sujeito a uma auditoria do PCI. Para aplicações WEB, utilize a geração do token de cartão pelo iugu.js
Alterar Cliente
Alterar os dados de um Cliente. Quaisquer parâmetros não informados não serão alterados.
Remover Cliente
Remove permanentemente um cliente. Porém, não permite remover clientes com assinaturas ou faturas vinculadas.
Listar Clientes
Retorna uma lista com todos os clientes cadastrados em sua conta ordenados pela data de Criação, sendo o primeiro o que foi criado mais recentemente. O campo "totalItems" contém sempre a quantidade de clientes cadastrados, independente dos parâmetros de pesquisa utilizados e o resultado da pesquisa fica sempre dentro de "items".
Alterar Forma de Pagamento
Altera os dados de uma Forma de Pagamento, quaisquer parâmetros não informados não serão alterados.
Listar Formas de Pagamento
Retorna uma lista com todas as formas de pagamento de determinado cliente.
Alterar Plano
Altera os dados de um Plano, quaisquer parâmetros não informados não serão alterados. As alterações não irão mudar as Assinaturas que já utilizam o Plano, mas só as novas.
Buscar Plano pelo Identificador
Retorna os dados de um plano utilizando um identificador.
Listar Planos
Retorna uma lista com todos os planos em sua conta ordenadas pela data de Criação, sendo o primeiro o criado mais recentemente. O campo totalItems contém sempre a quantidade de planos cadastrados, independente dos parâmetros de pesquisa utilizados e o resultado da pesquisa fica sempre dentro de items.
Alterar Assinatura
Altera os dados de uma Assinatura, quaisquer parâmetros não informados não serão alterados.
Alterar Plano da Assinatura
Altera o Plano de uma Assinatura. Uma Fatura cobrando a mudança de plano poderá ser gerada para o cliente.
Listar Assinaturas
Retorna uma lista com todas as assinaturas em sua conta ordenadas pela data de Criação, sendo a primeira a que foi criada mais recentemente. O campo totalItems contém sempre a quantidade de assinaturas cadastradas, independente dos parâmetros de pesquisa utilizados e o resultado da pesquisa fica sempre dentro de items.
Criar Conta
Permite a criação das contas de pagamento (ou sub-contas). Apenas para clientes com permissão de marketplace ou parceiro de negócios.
Cuidado
Salve os dados de retorno em seu banco de dados, pois os dados de API_TOKEN da Conta de Pagamento não podem ser consultados via API após sua criação. São dados sensíveis e retornados uma única vez.
Cuidado
Contas de Pagamento "sub-contas" NÃO podem ser excluídas.
Enviar Verificação de Conta
Todas as contas devem ter sua documentação verificada antes de poder emitir faturas reais (porém permite criação de dados de teste). Essa API permite o envio da documentação da sub-conta criada.
Atenção
Essa API obriga a utilização do User API Token em vez do API Token de conta.
Adicionar Domicílio Bancário
Envia dados para alterar domicílio bancário. Destino de valores ao transferir ou sacar dinheiro.
Listar Eventos Disponíveis
Lista todos os eventos disponíveis para criação de um Gatilho
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
$.get('http://yoursite.com/test/' + id, function(data) {
console.log(data);
});Alterar Gatilho
Altera um gatilho
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
$.get('http://yoursite.com/test/' + id, function(data) {
console.log(data);
});Listar Identificadores de Email Disponíveis
Retorna lista de emails disponíveis para personalização