Criar um aplicativo

Esta página percorre a criação de um aplicativo do início ao fim — cadastro, credenciais, permissões, teste e publicação — primeiro pelas telas do Console e depois pela CLI iugu. As duas rotas produzem o mesmo resultado; escolha a que combina com o seu fluxo de trabalho.

Pelo Console

1. Cadastrar o aplicativo

1. Acesse Desenvolvimento na área de trabalho que vai publicar o app.
2. Clique em Novo Aplicativo e informe o Nome.
3. Salve: o aplicativo entra na lista.

O app nasce privado, na categoria Rascunho, e aparece na lista de Desenvolvimento. O Console deriva do nome o slug (usado na Loja de Apps) e a tag — o prefixo de todas as ações que o app implementar, no formato <tag>:<ação>.

2. URL, callbacks e credenciais

Na aba Credenciais:

1. Preencha a URL do aplicativo (a página inicial para os usuários) e os Callbacks — as URLs de retorno do fluxo OAuth (redirect_uri). Só callbacks cadastrados são aceitos em /authorize.
2. Clique em + Adicionar Chave para criar o primeiro par client_id/client_secret.

Pela CLI ou pela Lifecycle API uma chave pode nascer restrita a áreas de trabalho (iugu app credentials create --name dev --workspaces <ids>): os tokens emitidos com ela só valem nas áreas indicadas — o padrão para credenciais de desenvolvimento.

3. Permissões

Na aba Permissões:

O modelo completo — como o Console decide quem pode o quê e como verificar isso no seu código — está em Permissões e ações.

4. Privilégios e URL da API de Serviço

Só é necessário se o seu app expõe ações para o Workflow, o Iugu for AI e a CLI, ou oferece widgets para o painel das áreas de trabalho. Na aba Privilégios, marque Actions Provider e informe a URL da API de Serviço — a base a partir da qual o Console lê o manifesto em GET {URL da API de Serviço}/actions. O formato do manifesto está em Expor ações.

5. Listagem, imagens, contratos e proteção

6. Testar na própria área de trabalho

Instale o app na área de trabalho publicadora (na tela de Desenvolvimento ou na Loja de Apps) e percorra o fluxo de login:

1. Envie o usuário para https://identity.iugu.com/authorize com client_id, response_type=code, um redirect_uri cadastrado, code_challenge (PKCE S256) e, se precisar de um nível acima do padrão, acr_values=urn:iugu:grant_scopes:<nível>.
2. Troque o code em POST https://identity.iugu.com/token (grant_type=authorization_code, autenticando o app com HTTP Basic ou com client_id/client_secret no corpo).
3. Leia quem entrou em GET https://identity.iugu.com/userinfo e verifique o que a pessoa pode fazer com POST https://identity.iugu.com/verify — detalhes em Permissões e ações.

A referência dos endpoints está na seção API desta documentação: /authorize, /token, /userinfo e /verify.

7. Publicar na Loja de Apps

Na aba Listagens, marque Público, retire a categoria Rascunho e clique em Atualizar Aplicativo. O app aparece na Loja de Apps quando todas as condições abaixo valem:

As pendências que o Console mostra na tela de Pendências da área de trabalho não bloqueiam o app, mas indicam o que falta:

• Aplicativos sem URL não serão visíveis na App-Store — preencha a URL na aba Credenciais.
• Nível de integração mínimo deve ser ‘acesso a informações’ — marque ao menos um nível na aba Permissões.
• Aplicativos com cobrança devem ter um plano configurado e publicado — veja Cobrança.

Pela CLI

A CLI iugu faz o mesmo percurso em poucos comandos, com saída --json para uso por agentes. As mudanças sensíveis (a primeira credencial, a publicação) não são executadas na hora: a CLI devolve o código de saída 5 e uma approval.url que uma pessoa abre no navegador para aprovar com um segundo fator.

iugu login                                        # login no navegador + consentimento (escopos × áreas de trabalho)
iugu me                                           # quem sou eu e quais áreas de trabalho foram consentidas
iugu app init --name "Acme Invoices" --workspace <id da área de trabalho de desenvolvimento>
#   → cria o app (privado, rascunho), instala na área de trabalho, pede uma credencial
#     restrita a ela (uma aprovação humana: saída 5 com approval.url) e escreve iugu.toml
iugu changeset wait <id> --write-env .env.local   # espera a aprovação; o segredo vai para .env.local (0600)
iugu app permissions set --implemented invoice.create,invoice.read --consumed billing:event.create --grant-scopes informations
iugu test-principal create --name qa              # principal temporário com papéis ⊆ os seus, válido por 1 h
iugu verify --principal temp:… --action acme-invoices:invoice.create
iugu app env --format fly                         # variáveis de ambiente não secretas para o seu alvo de deploy
iugu changeset create \
  --op 'oauth.update:{"url":"https://acme.example","callbacks":["https://acme.example/oauth/callback"]}' \
  --op 'listing.publish:{"public":true,"draft":false}' --submit --wait

Um agente de código faz exatamente esses passos sozinho: o roteiro embutido na CLI (iugu docs) explica a ele o que precisa de uma pessoa, como esperar a aprovação e como tratar segredos sem os expor. Veja Agentes e aprovações.