Perguntas frequentes do Marketplace do Flowlu
Autenticação e autorização
Quais métodos de autenticação são suportados para apps do Marketplace?
A autenticação identifica o usuário atual da conta e funciona apenas por meio de um token de acesso obtido via OAuth 2.0.
Em nome de quem uma solicitação de API é executada?
Uma solicitação é executada em nome de qualquer usuário cujo token de acesso você passar no cabeçalho (header).
Se seu aplicativo estiver incorporado na interface e usar o JS SDK para fazer solicitações, essas solicitações sempre serão executadas com o token de acesso do usuário atualmente autorizado. Seu aplicativo também pode fazer solicitações com o token de qualquer usuário a partir de seu backend, de acordo com sua própria lógica.
Quando devo usar o OAuth 2.0 em vez de uma chave de API?
Uma chave de API é emitida por conta. Instalar um app público em muitas contas significaria emitir uma nova chave para cada conta, e seu aplicativo teria que rastrear qual chave pertence a qual conta. Além disso, uma chave de API não está vinculada a um usuário, portanto, você não pode autenticar um usuário específico com ela.
O OAuth 2.0 evita tudo isso: os tokens de acesso não estão vinculados a uma conta, mas ao usuário e ao aplicativo.
Posso fazer solicitações de API a partir do código frontend ou as operações sensíveis devem passar pelo backend?
Você pode chamar a API tanto pelo backend quanto pelo frontend, mas pelo frontend, use sempre o token do usuário atual. Os dados da solicitação, incluindo o token, ficam visíveis no navegador por meio das ferramentas de desenvolvedor, portanto, um usuário poderia ler o token de outro usuário e reutilizá-lo livremente.
Quando seu aplicativo usa o JS SDK, o token do usuário atualmente autorizado é sempre usado, e as solicitações de frontend são executadas em nome dele.
Como as permissões do manifesto correspondem ao acesso à API?
O manifesto do aplicativo declara uma lista de escopos (scopes). Cada escopo representa um conjunto de modelos (entidades) dentro de um módulo, além de um nível de acesso a eles. Existem dois níveis de acesso: apenas leitura (read) e acesso total (full). Cada escopo possui um código.
Os escopos controlam:
- os webhooks que seu aplicativo pode registrar,
- as configurações do aplicativo vinculadas aos modelos do módulo (usuários, contas de CRM, faturas e assim por diante),
- as solicitações de API que seu aplicativo está autorizado a fazer contra os modelos do módulo.
Escopos disponíveis:
| Scope (Escopo) | O que concede |
users | O modelo Usuário |
user.me | O modelo Usuário, restrito ao usuário atualmente autorizado |
crm | Todos os modelos no módulo CRM |
crm.accounts | crm.account, crm.company, crm.contact, crm.phone, crm.email |
crm.deals | crm.leads, crm.leadsitems |
products | Todos os modelos no módulo de produtos |
fin | Todos os modelos no módulo financeiro (fin) |
fin.invoices | fin.invoices , fin.items, fin.itemsrelation |
st | Todos os modelos no módulo de gestão de estoque (st) |
task | Todos os modelos no módulo de tarefas |
agile | Todos os modelos no módulo agile |
calendar | Todos os modelos no módulo de calendário |
timetracker | Todos os modelos no módulo de controle de tempo |
knowledgebase | Todos os modelos no módulo de base de conhecimento |
workspace | Todos os modelos no módulo de espaço de trabalho |
orgchart | Todos os modelos no módulo de estrutura organizacional |
customlists | Todos os modelos no módulo de listas personalizadas |
Precedência de escopo: Duas regras decidem o que se aplica quando os escopos se sobrepõem:
- Mesmo escopo, níveis diferentes. Se você declarar um escopo com
readefull, apenas o nível mais alto (full) será usado. - Geral e específico juntos. Se você declarar tanto um escopo de módulo quanto um mais restrito do mesmo módulo (por exemplo,
crmecrm.accounts), apenas o escopo geral (crm) será usado, e o específico será ignorado.
Apps privados e públicos
A moderação é necessária para apps privados?
Não. Apps privados não exigem moderação.
A nova moderação é necessária para cada atualização de um app público?
Alterações na descrição do aplicativo, informações de suporte, banners e logo do aplicativo não exigem nova moderação.
Toda nova versão do aplicativo exige. Revisamos a funcionalidade declarada, se o aplicativo funciona conforme descrito, a segurança e se os escopos solicitados são suficientes e justificados.
Ciclo de vida do aplicativo
Quais ações de ciclo de vida estão disponíveis?
No Console do desenvolvedor, você pode:
- criar um aplicativo,
- editar um aplicativo,
- desativar ou ativar um aplicativo,
- publicar ou ocultar um aplicativo no catálogo do Marketplace,
- excluir um aplicativo,
- criar uma nova versão,
- editar uma versão,
- enviar uma versão para moderação,
- publicar ou ocultar uma versão alterando seu status,
- instalar uma versão em outra conta através de um link,
- instalar uma versão na conta atual.
Para um aplicativo já instalado em uma conta, um administrador pode:
- desinstalá-lo,
- configurar acesso para funções de usuário e grupos,
- alterar configurações em nível de aplicativo,
- alterar configurações em nível de usuário.
O aplicativo instalado é incorporado em várias partes da interface e pode usar o JS SDK.
Quais dados o aplicativo recebe durante a instalação, atualização ou exclusão?
O framework genérico de miniapps não entrega eventos de instalação, atualização ou exclusão para o próprio aplicativo. Tipos de integração específicos, como telefonia ou canais de comunicação, definem seus próprios hooks de ciclo de vida, abordados em seus respectivos guias.
Assim que o aplicativo estiver rodando em uma conta na interface de um usuário, o endpoint do aplicativo no ponto de integração recebe:
- o protocolo (http/https),
- o domínio da conta (por exemplo,
minhaempresa.flowlu.com), - o código do idioma da interface (en/pt/es),
- o código de incorporação e seu ID exclusivo (do manifesto),
- o código exclusivo do aplicativo,
- o número da versão (por exemplo,
1.0.0).
Usando o JS SDK, o aplicativo também pode:
- obter os tokens de acesso e de atualização do usuário atual,
- obter configurações do aplicativo,
- obter configurações do usuário,
- fazer solicitações de API dentro dos escopos e permissões declarados no manifesto, para o usuário atual,
- exibir elementos de interface (notificações, alertas, janelas modais, painéis laterais, navegação e assim por diante).
O que acontece com a configuração e os dados de um aplicativo quando ele é excluído?
Quando um aplicativo é desinstalado de uma conta, o Flowlu remove:
- os valores de configurações do aplicativo e do usuário,
- arquivos das configurações do aplicativo,
- webhooks que o aplicativo registrou,
- configurações de funções de usuário e grupos para o aplicativo.
O aplicativo deixa de estar incorporado na interface.
Quando um aplicativo é excluído do Console do desenvolvedor, tudo o que foi mencionado acima acontece para cada conta onde ele está instalado, uma conta de cada vez. Os tokens de acesso e de atualização do aplicativo para todos os usuários também são excluídos.
O que acontece em uma atualização de aplicativo?
O Flowlu compara os manifestos da versão instalada e da nova versão, e então atualiza os webhooks registrados para corresponder ao novo manifesto: webhooks do manifesto antigo são removidos, e webhooks recém-especificados são registrados.
Configurações do aplicativo, funções de usuário e arquivos são preservados em uma atualização. O aplicativo deixa de ser incorporado em qualquer local removido do novo manifesto e passa a ser incorporado em qualquer local que o novo manifesto adicionar.
