Como utilizar um aplicativo?

Depois de instalar um aplicativo em sua área de trabalho, você provavelmente vai querer usá-lo. Existem duas formas de fazer isso: via navegador, ou via API. A grande maioria pode ser usada das duas formas, mas alguns podem apenas ser usados via navegador ou API.

Usando seu aplicativo via navegador

O aplicativo vai estar disponível na sua área de trabalho. Apenas clique nele para acessar. Cada aplicativo tem sua própria forma de uso, que não será detalhada aqui.

Usando seu aplicativo via API

Para usar qualquer aplicativo via API, é necessário um setup inicial, que deverá ser feito apenas uma vez. Para usar outros aplicativos, provavelmente você poderá fazer a chamada diretamente, sem repetir os passos abaixo.

De forma resumida, para acessar um aplicativo via API, você precisa primeiro de credenciais de acesso, e que elas tenham o permissionamento correto. Com as credenciais, você deve obter um token JWT, e com o token gerado e válido, finalmente fazer a chamada.

Veja abaixo o passo a passo detalhado do setup inicial:

Setup inicial para uso de aplicativos via API

Obtendo credenciais de acesso

Como a plataforma iugu foi construída em torno do padrão OAuth 2.0, a forma de se obter credenciais de acesso para chamadas de API, é através da criação de um aplicativo de integração.

O aplicativo de integração

Toda vez que um aplicativo é criado, também é criado um Client ID e um Client Secret para ele. E estas são justamente as credenciais que precisamos para a integração. Então devemos apenas criar o aplicativo na plataforma iugu, e copiar seu Client ID e Client Secret. Para detalhes de como fazer isso, clique aqui

Vale lembrar que o aplicativo de integração criado pode (e deve) ser usado para acessar diversos aplicativos da plataforma. Ele deve ser usado como a ponte entre seu próprio software, e os aplicativos da plataforma iugu que você deseja usar.

Adicionando as permissões corretas ao aplicativo de integração

As credenciais não dão o acesso necessário, elas apenas ajudam a autenticar quem (ou o que) está fazendo a chamada. Este quem (ou o que) precisa ter a permissão certa.

A melhor forma de conceder o permissionamento correto, é através das ações consumidas. Ações consumidas são as ações que um aplicativo, ao ser instalado, vai solicitar para que funcione corretamente. Portanto, é uma boa ideia colocar diretamente no campo ações consumidas do seu aplicativo de integração, as ações que ele deve executar. Por exemplo, para fazer uma chamada ao aplicativo de cobranças (billing), para registrar um evento, a ação é billing:event.create.

Verifique na documentação do aplicativo que você quer usar, quais ações você precisa, e adicione-as ao campo ações consumidas. Clique aqui para mais detalhes

Instalando o aplicativo de integração

Este é o passo final do setup inicial. Instale o aplicativo de integração na sua área de trabalho. Clique aqui para mais detalhes

Como dito antes, você pode utilizar este aplicativo de integração para acessar diversos outros. Apenas tome o cuidado de colocar todas as ações desejadas no campo ações consumidas.

Fazendo um request via API

Obtendo um Access Token no formato JWT

Agora que você já tem um aplicativo de integração e copiou seu Client ID e Client Secret, você precisa fazer uma chamada padrão do OAuth 2.0, do tipo Client Credentials, para obter o token JWT para fazer a chamada desejada.

Clique aqui para maiores detalhes de como fazer esta chamada. Lembrando que se você estiver usando uma biblioteca OAUth 2.0, isto será feito automaticamente para você. Consulte a documentação da biblioteca.

Fazendo a chamada

Se estiver tudo certo até aqui, você agora tem um Access Token no formato JWT. Clique aqui para saber mais sobre tokens JWT, sua estrutura e informações (claims) que ele carrega. De posse do token, você já pode fazer sua chamada, passando o token no header. Um outro ponto a ser observado: a grande maioria das chamadas a qualquer aplicativo da plataforma iugu também é feita com o ID do sua área de trabalho no header da chamada.

Ciclo de vida de uma chamada de API na plataforma iugu

O diagrama abaixo mostra de forma visual o procedimento acima, e representa o funcionamento de qualquer chamada de API feita a qualquer aplicativo da plataforma iugu:

É solicitado o token JWT, depois a chamada é feita com o token e o ID da área de trabalho, e por fim, o resultado dela é retornado. Devemos lembrar também que o token pode ser usado repetidas vezes, enquanto for válido. Com o passar do tempo (alguns minutos) o token vai vencer, e um novo precisa ser solicitado. De novo: se você estiver usando uma biblioteca, este tratamento é automático.