Docs

Começando

...

Nesta página

Primeiros passos

A iugu oferece automações financeiras e serviços de meios de pagamento, como geração de boletos e pagamentos via PIX. Este guia irá lhe orientar em todas as etapas necessárias para fazer sua primeira integração com os serviços iugu.


Se você só deseja utilizar um aplicativo instalado direto da app-store, recomendamos seguir esse guia até o passo 2. Caso você seja uma pessoa desenvolvedora e quer aprender a integrar uma API da iugu, recomendamos seguir esse guia até o fim.

1. Criando sua conta

Como criar uma conta iugu
  1. Acesse identity.iugu.com/register
  2. Preencha seu nome e email ou número de celular
  3. Leia e aceite os termos de uso
  4. Clique em
  5. Preencha o código enviado
  6. Clique em
  7. Defina uma senha
  8. Clique em
  9. O console irá criar sua área de trabalho e pedir para você adicionar um segundo fator de autenticação
  10. Adicione um segundo fator que pode ser o email ou telefone (o que você não adicionou anteriormente) ou um aplicativo autenticador (Google Authenticator, Microsoft Authenticator etc)

Pronto, agora você já tem acesso ao console e aos aplicativos do ecossistema iugu. Esses aplicativos serão acessados através da sua Área de trabalho, porém agora ela está vazia. Siga o passo 2 a seguir para aprender como instalar aplicativos na sua Área de trabalho

2. Instalando seu primeiro aplicativo

Vamos instalar seu primeiro aplicativo. É através da instalação de aplicativos, que você adiciona novas funcionalidades à sua área de trabalho. Siga os passos a seguir:

Como instalar seu primeiro o aplicativo
  1. Na barra superior, clique em Loja de apps ou App Store
  2. Na barra de busca, digite o nome do aplicativo que você gostaria de instalar. Ex: pix, boleto, etc.
  3. Dentre os apps encontrados, clique naquele que você quer instalar
  4. Você vai visualizar a tela de apresentação do app. Clique em
  5. Você será levado para a tela de autorização de acessos. Clique em novamente.
  6. Agora o app estará disponível na sua Área de trabalho. Para acessa-lo, clique no icone dele que apareceu na sua Área de trabalho.

Utilizando o aplicativo

Uma vez instalado, o aplicativo irá aparecer na sua Área de trabalho. Clique nele e você será direcionado para a página do aplicativo.

Sucesso

Se você chegou até aqui, parabéns! Você já pode começar a utilizar o console, organizar seus acessos no GIA e utilizar seus aplicativos. Caso você seja desenvolvedor(a) e quer integrar a API de um aplicativo, continue nesse guia pois iremos explicar como você fará sua integração.

3. Criando o seu aplicativo de integração

Porque criar um aplicativo de integração?

Como você viu no passo anterior, é possível que outro sistema externo autentique o seu usuário utilizando o sistema do console. Essa autenticação permite que o usuário acesse um sistema protegido através de um único login, feito diretamente em um servidor de acesso, parecido como é feito quando o você loga via “Google” ou “Facebook” na internet.


A iugu tem seu próprio servidor de acesso de login único. Para que você possa utilizar esse servidor corretamente, é necessário que você crie e configure um aplicativo de integração. O aplicativo de integração lhe dará acesso às credenciais de integração. Essas credenciais são o Client Id e o Client Secret, essenciais para a integração.

Criação e configuração do aplicativo de integração

Como criar um aplicativo de integração
  1. No Console, clique no botão com o nome da sua área de trabalho e clique em Gerenciar área de trabalho
  2. Vá para Desenvolvimento. Esta é a tela que lista seus aplicativos
  3. Clique em
  4. Dê um nome para seu aplicativo e clique em
  5. No menu Credenciais:
    • Anote o ID e a Chave do Cliente, que serão usadas posteriomente nas chamadas de integração
    • Preencha a URL do seu aplicativo. Não é necessário que esta URL esteja na Internet. Durante o desenvolvimento você pode usar seu domínio local, por exemplo http://localhost
    • Coloque as URLs de callback do seu aplicativo. Somente as URLs listadas aqui serão autorizadas a realizar o callback
  6. Clique em

Aviso

Sua chave do cliente deve ser mantida em segurança. Ela atua como uma chave de API e dá acesso aos aplicativos integrados.

Instalando o seu aplicativo

Para que você possa utilizar qualquer aplicativo, ele precisa antes ser instalado na sua Área de trabalho. Isso signifca que o seu aplicativo de integração também precisa ser instalado antes que você possa utilizá-lo.

Como instalar o aplicativo

Após isso o aplicativo deve aparecer na sua área de trabalho.

4. Integrando com o Oauth2

O Oauth2 é um protocolo de autorização. Ele permite que um usuário ou app autenticado tenha acesso aos seus recursos através de tokens de acesso (JWT). Esse guia irá lhe ensinar a gerar esses tokens e acessar recursos dentro do sistema iugu.

Neste guia, iremos gerar o token via postman. Caso ainda não tenha o postman, você pode instalar através desse link.


Além disso, recomendamos que você veja como executar em código, as chamadas feitas no postman, através da ferramenta Code. Ela fica à direita do botão e tem o símbolo </>. Nela é possível ver a implementação das chamadas, em diversas linguagens de programação, auxiliando no seu processo de implementar a integração no seu back-end.

Gerando o token (Authorization Code)

Antes de gerar o token, será necessário fazer uma configuração no seu app

Como configurar seu app para gerar o token com postman
  1. No menu Desenvolvimento do console, encontre seu aplicativo e clique no botão editar
  2. Acesse o menu Credenciais e coloque no campo Callbacks a url https://oauth.pstmn.io/v1/callback
  3. Clique em Atualizar Aplicativo
  4. Caso você não tenha salvo a chave do cliente, clique em Rotacionar Chave e guarde a chave gerada

Pronto, agora você pode gerar seu token.

Como gerar o token com postman
  1. No Postman, crie uma nova coleção ou requisição
  2. Acesse a aba Authorization e selecione o type Oauth2
  3. Role para baixo até encontrar a seção Configure New Token
  4. Em Token Name insira um nome para o seu token.
  5. Em Grant Type selecione Authorization Code
  6. Marque a caixa Authorize using browser
  7. Preencha as seguintes informações:
    • Auth URL: https://identity.iugu.com/authorize
    • Access Token URL: https://identity.iugu.com/token
    • Client ID: O id do Cliente que você salvou
    • Client Secret: A chave do cliente que você salvou
  8. Role para baixo até encontrar e clique nele.
  9. Você será redirecionado para o navegador e e será solicitado que você faça o login no console, ou caso esteja logado clique em permitir.
  10. Após isso você voltará para o postman e ele ira abrir um modal avisando que a autenticação está completa. Basta aguardar ou clicar em Proceed.
  11. O postman irá exibir seu token JWT anote-o ou clique no botão . Ele será necessário nas próximas etapas.

Lembre-se de que seu token expira em 5 minutos, então renove-o clicando em Get New Access Token quando expirar.

Aviso

Não se esqueça de trocar a url de callback no seu app quando terminar esse guia.

Utilizando o token (Authorization Code)

Com seu token em mãos, agora é possível acessar recursos protegidos do console. O acesso à esses recursos é feito através do seu aplicativo de integração juntamente com seu token.

Como utilizar seu token via postman
  1. Crie uma nova chamada no Postman, do tipo GET
  2. Preencha na url: identity.iugu.com/userinfo
  3. Caso tenha clicado em Use token no passo anterior, o token já foi adicionado na aba Authorization
    • Caso contrário, adicione na aba Authorization o seu token
  4. Clique em Send para fazer a chamada

Você deve ver a resposta do endpoint com seus dados de usuário. Caso você tenha algum erro, certifique-se de que seu token não expirou e que todos os valores foram inseridos corretamente.

Exemplo de resposta:

{
    "sub": "6Er5BfuQZeWh6yrSDk9fM8",
    "name": "Logitrack",
    "email": "[email protected]",
    "email_verified": true,
    "updated_at": "2024-03-19T19:17:44Z",
    "given_name": "Logitrack",
    "middle_name": "",
    "family_name": ""
}

O que você acabou de fazer no fluxo acima foi solicitar dados de usuário através de um aplicativo de integração. Em resumo, esse é o principio do fluxo “Authorization Code”, onde um aplicativo acessa recursos protegidos em nome de um usuário.

Gerando o token (Client Credentials)

Agora vamos gerar um token de acesso seguindo o fluxo Client Credentials. Esse token lhe dará acesso à recursos protegidos dentro de um app.

Iremos utilizar um app desenvolvido especificamente para esse guia. Ele permite que você possa testar seu token em um ambiente controlado. Para baixar esse app, siga os passos abaixo:

Como instalar o app Teste de integração iugu
  1. Busque pelo nome do aplicativo na Loja ou acesse diretamente a página do app
  2. Clique em
  3. Você será levado para a tela de autorização de acessos. Clique em Instalar novamente.
Como solicitar um token via postman
  1. No postman, crie uma nova requisição do tipo POST
  2. Preencha na url: identity.iugu.com/token
  3. Preencha esses dados na aba params:
    • client_id: seu client_id
    • client_secret: seu client_secret
    • grant_type: client_credentials
    • audience: Iugu.Platform.0GG0LHgBcinbYxIRVAjCuo, indicando que esse token servirá para se comunicar com o app de id 0GG0LHgBcinbYxIRVAjCuo (Teste de integração iugu)
  4. Clique em Send para fazer a chamada
  5. Você deve obter uma resposta no formato json com 3 chaves:
    • acces_token com o seu token
    • token_type do tipo “Bearer”
    • expires_in com o valor 300, indicando que o token expira em 5 minutos

Caso você queira ver as informações que esse token carrega, acesse jwt.io e insira seu token no painel Encoded.

Exemplo de resposta:

{
    "access_token": "eyJ0eXAiOiJhdCtKV1QiLCJraWQiOiJjZWI5NjBjOS1iODliLTQ4MWUtYjg2NS1kY2UyZTAyMTYzNDgiLCJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3MTA4ODYzMjQsImlhdCI6MTcxMDg4NjAyNCwic3ViIjoiYXBwOjM5ek0wNU04RDY2ZlZkZldMb29HWnEiLCJhdWQiOlsiSXVndS5QbGF0Zm9ybS4wR0cwTEhnQmNpbmJZeElSVkFqQ3VvIiwiMEdHMExIZ0JjaW5iWXhJUlZBakN1byIsIjM5ek0wNU04RDY2ZlZkZldMb29HWnEiXSwic2NvcGUiOiIiLCJjbGllbnRfaWQiOiIzOXpNMDVNOEQ2NmZWZGZXTG9vR1pxIiwiaXNzIjoiaHR0cHM6Ly9pZGVudGl0eS5pdWd1LmNvbS8ifQ.f3vtCT3aW0d4F55oN7YLpGL--ZNdeQWpINbJJnXW1Sk3VOaiJjJX6-RTR_-OyA6bD3J_YgeEKlP7qEdrSjgqTYaO_foMO2UYJXQVSeIqxnKxxi3XE6TAVKhjvK4U_ZZLGSq-shcutvAdECOieEbucH09CQm2YQaEs1JwkkYb5-6RCckhgWXZb0JD2z7Ci6Ficol1hTQuzqlggjHDlQO4GHMOrtuGAQvp0fgPeGIrW99OuUVXDlbQuB3ZDu7bEQoR4vgnevr6xdUhepISRAw03jNG5YWfm4i-PYQlUbaHjOnf6Pkex33r3KILbC85MkU2JJx0C8YXxiJUzRJjTNLJxQ",
    "token_type": "Bearer",
    "expires_in": 300
}

Utilizando o token (Client Credentials)

O app Teste de integração iugu tem um endpoint que funciona através de API para testar a comunicação do tipo Client Credentials Acesse esse endpoint com seu token seguindo os passos abaixo:

Como utilizar seu token criado em uma API
  1. No postman, crie uma nova requisição do tipo GET
  2. Preencha na url: https://platform2-integration-test-e36ca4223237.herokuapp.com/api/status
  3. Clique em Send
    • Você verá que o app retornou um erro 500.
    • Como você ainda não adicionou seu token de acesso, o app não te reconhece e não dá acesso aos recursos protegidos.
  4. Acesse a aba Authorization e adicione uma autorização do tipo Bearer Token
  5. Insira seu token no campo Token e clique novamente em Send
    • Você deve obter uma resposta do tipo 200 com a mensagem: status: ok

Exemplo de resposta:

{
    "status": "ok"
}

Pronto, você acabou de acessar um recurso protegido do app Teste de integração iugu utilizando o fluxo Client Credentials.

5. Consumindo uma ação implementada

Alguns aplicativos tem endpoints que não podem ser acessados livremente. Eles necessitam que o app explicite que deseja acessá-las por meio das suas configurações. Temos um guia dedicado explicando essas configurações. Você pode acessá-lo aqui.

O que são ações consumidas e implementada?

De forma resumida, uma ação implementada é todo endpoint que uma aplicação tem e que deseja ter um controle via permissionamento. Já a ação consumida, são as ações de outros apps que uma aplicação deseja acessar, também de forma controlada via permissionamento. Um ação implementada de um aplicativo será a ação consumida de outro.

Adicionando ações consumida no meu app

Como adicionar uma ação consumida no seu app
  1. No menu Desenvolvimento do console, encontre seu aplicativo e clique no botão editar
  2. Acesse o menu Permissões

  3. Logo abaixo da caixa Ações Consumidas, você deve ver um campo com o texto escrito Digite a ação.

    Digite teste-de-integracao-iugu:index. O campo tem um auto complete então você também pode só selecionar a ação quando ela aparecer.

  4. Depois de preencher a ação, clique em
  5. Por fim, clique em

Você acabou de adicionar uma ação consumida no seu aplicativo. Agora o seu app tem permissão para acessar essa ação no aplicativo de teste

Como consumir uma ação via postman
  1. Volte ao postman e crie uma nova requisição do tipo GET
  2. Preencha na url: https://platform2-integration-test-e36ca4223237.herokuapp.com/api/index_access
  3. Encontre no console, o id da sua Área de trabalho, disponível no menu Gerenciar área de trabalho.
  4. Na aba Headers, adicione um parâmetro novo chamado workspace-id com o valor do id que você encontrou no passo anterior.
  5. Na aba Authorization, selecione o tipo Bearer Token e preencha seu token no campo token. Caso ele tenha expirado, basta gerar um novo.
  6. Clique em Send.
    • Você deve obter uma resposta do tipo 200 com uma mensagem indicando que sua chamada foi feita com sucesso.

Exemplo de resposta:

{
    "teste_de_integracao_iugu:authorization_test.index": true
}

Info

Extra: Tente remover a ação das permissões do seu aplicativo e faça a chamada novamente. Você irá obter uma resposta com um erro 401, indicando que você seu app não está mais autorizado a executar aquela ação.


Isso conclui esse guia de primeiros passos. Agora você tem os pré-requisitos necessários para integrar com qualquer aplicativo iugu. Caso queira se aprofundar em outros assuntos, você pode consultar nosso outros guias no menu ao lado ou acessar direto a documentação do app que você deseja integrar.