Introdução à API
A iugu disponibiliza uma interface de programação web, no modelo REST. Por meio dessa interface, é possível conversar com o sistema da iugu, comandando ações, verificando configurações e realizando a sincronização com os seus sistemas.
O endereço base de comunicação é api.iugu.com, acompanhado sempre do protocolo seguro https:// como prefixo. As versões da API são agrupadas por diretório, sufixadas ao endereço base (https://api.iugu.com/v1).
Endereço para comunicação com a 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 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
A fim de facilitar a interoperabilidade entre sistemas, todas as nossas chamadas de API respondem no formato JSON.
Como especificar o formato de resposta
Você tem duas formas de especificar o formato de resposta:
- Adicionar a extensão ".json" no final dos endereços de API.
- Enviar um Header HTTP contendo JSON como tipo de conteúdo: "Accept: application/json".
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
]
}Fluxos de Implementação
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".
Gerar 2ª via de fatura
Gera a segunda via de uma fatura com o status "pendente". A fatura atual é cancelada e uma nova é criada com o mesmo status.
Listar faturas
Retorna uma lista das faturas em sua conta ordenadas pela data de criação, da mais à menos recente. Por padrão, este endpoint retorna no máximo 100 registros. O campo "totalItems" contém sempre a quantidade total de faturas cadastradas, independentemente 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 a quantidade de clientes encontrados no sistema de acordo com os parametros query. O resultado da pesquisa fica 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 as assinaturas geradas pela sua conta, ordenadas pela data de criação, da mais nova para a mais antiga. O nó totalItems retorna sempre a quantidade total de assinaturas cadastradas, independentemente dos parâmetros de pesquisa utilizados, e o resultado da pesquisa fica sempre dentro de items. Por padrão, retorna no máximo 100 itens.
Listar Transferências
Retorna uma lista com as transferências efetuadas pela conta. Por padrão, retorna no máximo 100 registros.
Criar subconta
Permite a criação de subcontas (contas de pagamento) para contas com permissão de marketplace ou parceiro de negócios.
Atenção!
Salve os dados de retorno em seu banco de dados, principalmente o user_token, usado como api_token para autenticar as chamadas da API nas subcontas.
Cuidado
Subcontas NÃO podem ser excluídas.
Atualizar subconta
Atualiza os parâmetros de uma conta de pagamentos.
IMPORTANTE: Para esta chamada, no lugar do token de API da conta (api_token), deve-se utilizar o token de usuário (user_token), gerado no retorno da chamada de criação de subconta.
Enviar verificação de subconta
Permite enviar documentos para verificação de subcontas. Todas as subcontas devem ter sua documentação verificada para emitir faturas no modo de produção.
Atenção
Esta API obriga a utilização do user_token na autenticação da chamada. Prazo de aprovação: um dia útil.
Cuidado
No envio da verificação, é solicitado escolher entre conta PF ou PJ ("data.person_type").Se person_type == "Pessoa Física", é OBRIGATÓRIO informar números válidos de CPF e de conta bancária PF vinculada ao CPF cadastrado.Se person_type == "Pessoa Jurídica", é OBRIGATÓRIO informar números válidos de CNPJ válido e de conta bancária PJ vinculada ao CNPJ cadastrado.
Com toda chamada deste endpoint, a iugu valida, por padrão, o dígito verificador das informações bancárias enviadas. Veja na tabela abaixo o formato padrão esperado:
| Banco | Agência | Conta |
|---|---|---|
| Banco do Brasil | 9999-D | 99999999-D |
| Santander | 9999 | 99999999-D |
| Caixa Econômica | 9999 | XXX99999999-D (X: Operação) |
| Bradesco | 9999-D | 9999999-D |
| Itaú | 9999 | 99999-D |
| Banrisul | 9999 | 999999999-D |
| Sicredi | 9999 | 99999D |
| Sicoob (Bancoob) | 9999 | 999999999-D |
| Inter | 9999 | 999999999-D |
| BRB | 9999 | 999999999-D |
| Via Credi | 9999 | 99999999999-D |
| Neon | 9999 | 9999999-D |
| Nubank | 9999 | 9999999999-D |
| PagSeguro | 9999 | 99999999-D |
| Banco Original | 9999 | 9999999-D |
| Safra | 9999 | 99999999-D |
| Modal | 9999 | 999999999-D |
| Banestes | 9999 | 99999999-D |
| Unicred | 9999 | 99999999-D |
Informações da Conta
Retorna as informações de uma conta. Use o LIVE_API_TOKEN da sub-conta na autenticação.
Adicionar Domicílio Bancário
Envia dados para cadastrar ou alterar o domicílio bancário da conta que recebe saques e transferências.
Atenção
Informe uma conta bancária válida vinculada ao CPF/CNPJ cadastrado na verificação da subconta.Não é possível receber valores em uma conta bancária que tenha um titular diferente do cadastrado na subconta.
Formatação dos campos com automatic_validation
| Banco | Agência | Conta |
|---|---|---|
| Banco do Brasil | 9999-D | 99999999-D |
| Santander | 9999 | 99999999-D |
| Caixa Econômica | 9999 | XXX99999999-D (X: Operação) |
| Bradesco | 9999-D | 9999999-D |
| Itaú | 9999 | 99999-D |
| Banrisul | 9999 | 999999999-D |
| Sicredi | 9999 | 99999D |
| Sicoob | 9999 | 999999999-D |
| Inter | 9999 | 999999999-D |
| BRB | 9999 | 999999999-D |
| Via Credi | 9999 | 99999999999-D |
| Neon | 9999 | 9999999-D |
| Nubank | 9999 | 9999999999-D |
| PagSeguro | 9999 | 99999999-D |
| Banco Original | 9999 | 9999999-D |
| Safra | 9999 | 99999999-D |
| Modal | 9999 | 999999999-D |
| Banestes | 9999 | 99999999-D |
Verificar Envio de Domicilio Bancario
Consultar dados enviados para alterar domicílio bancário.
Criar API Token
Cria um "api_token" em uma subconta.
Atenção
Essa API obriga a utilização do "user_api_token" na autenticação da chamada.
Remover API Token
Remove um "api_token" em uma subconta.
Atenção
Essa API obriga a utilização do "user_api_token" na autenticação da chamada.
Listar API Tokens
Listar os "api_tokens" em uma subconta.
Atenção
Essa API obriga a utilização do "user_api_token" na autenticação da chamada.