Solavel Documentos
Português

Integrações

Última atualização

A guia Integrações do projeto conecta um projeto a outros sistemas:

  • Webhooks de saída enviam eventos do projeto (tarefa criada, sprint iniciada, documento criado...) para um endpoint HTTPS de sua propriedade, assinados para que o receptor possa confiar neles.
  • Tokens de webhook de entrada permitem que um sistema externo (uma ferramenta de formulário, GitHub, um script) crie tarefas ou comentários no projeto.
  • API Pública tokens dão a outro sistema acesso com escopo, leitura ou escrita às tarefas e tempo do projeto através da SolaProjects API.
  • Disponibilidade das integrações nativas mostra ligações prontas a usar (Slack, Microsoft Teams, GitHub, GitLab, Google Calendar, Google Drive, OneDrive, Zapier / IFTTT) e indica se cada uma pode ser ligada.

Use esta função quando um projeto precisa de comunicar com outra ferramenta, por exemplo enviar atualizações de tarefas para o painel de um cliente ou transformar contactos do site em tarefas. Os gestores de projeto e administradores configuram-na, normalmente uma vez por projeto com o apoio do seu contacto de informática.

Duas páginas chamam-se Integrações. Esta página descreve o separador do projeto. A opção Integrações na secção Espaço de trabalho da barra lateral (/projects/settings/integrations) corresponde à ligação SolaCount da organização — consulte Ligação SolaCount da organização abaixo e Orçamento e finanças.

#Onde encontrar

Barra lateral Seção Projeto → Integrações (entre Automações e IA)
URL /projects/{project}/integrations
Paleta de comandos Integrações · {project name} em Projeto atual

Quem vê:

  • Plano: integrações são um recurso do plano Premium (também Enterprise). Em planos inferiores, a aba fica oculta. Se um plano pago expirar, a aba desaparece e os webhooks deixam de ser oferecidos até que você renove.
  • Função: apenas pessoas que podem editar o projeto podem carregar a guia (veja Permissões). Outros veem "Não foi possível carregar as integrações." com Tentar novamente.

#Tour pela tela

#Cartão de cabeçalho

Integrações — Webhooks de saída, tokens de entrada e histórico de entrega.

Bloco Significado
Saída Webhooks de saída ativos.
Tokens de entrada Tokens de entrada ativos e não revogados.
Entregas recentes Tentativas de entrega listadas em Entregas recentes.
Entregas com falha Tentativas falhas entre elas (vermelho quando acima de zero).

#Cartão de webhooks de saída

POST de eventos do projeto para um endpoint HTTPS externo, assinado com HMAC-SHA256. Novo webhook no canto superior direito.

Cada cartão de webhook apresenta o nome, o URL do destino, um distintivo de estado (Ativo, Desativado ou Arquivado), uma etiqueta por evento subscrito e {n} entregas · {n} falhadas. Ações da linha (ausentes nos webhooks arquivados): Editar, Testar, Renovar segredo, Arquivar.

Estado vazio: Nenhum webhook de saída — Crie um para enviar eventos para um sistema externo.

#Cartão de tokens de webhook de entrada

Permita que sistemas externos criem tarefas/comentários enviando um POST com um token secreto. Novo token no canto superior direito.

Cada cartão de token: nome, provedor (Personalizado ou GitHub) · usado pela última vez em {date} ou nunca usado, selo Ativo, Inativo ou Revogado. Ações (não em tokens revogados): Rotacionar, Revogar.

Estado vazio: Nenhum token de entrada — Crie um token para aceitar webhooks de entrada.

#Cartão de API pública

Crie tokens de portador (bearer tokens) com escopo para endpoints documentados de projeto, tarefa e entrada de horas. Botões: Documentação (abre a referência OpenAPI em uma nova aba) e Novo token.

Cada cartão de token: nome, usado pela última vez em {date} / nunca usado, selo de status, um chip por habilidade. Ações: Rotacionar, Revogar.

Estado vazio: Nenhum token de API — Crie um token para a API pública.

#Cartão de entregas recentes

Tentativas de entrega de saída e seu resultado. Selo com a contagem.

Coluna Significado
Quando Data da entrega.
Webhook Nome do webhook, ou Webhook arquivado.
Evento Tipo de evento, ex: task.status_changed.
Estado Entregue (verde), Pendente (âmbar, aguardando ou tentando novamente), Falhou (vermelho), Ignorado.
Tentativas Quantas vezes SolaProjects tentou.
Resposta O código de status HTTP retornado pelo seu endpoint, erro quando nenhuma resposta foi recebida, ou —.
(botão) Repetir em qualquer entrega que não foi entregue.

Estado vazio: Nenhuma entrega ainda — As tentativas de entrega aparecerão aqui assim que um evento for disparado ou você enviar um teste.

#Cartão de prontidão do provedor nativo

Estado da conexão e pré-requisitos de configuração para integrações específicas do provedor. Um bloco por provedor:

Provedor O que faz
Slack Envie notificações do projeto para Slack e receba comandos de tarefa de Slack.
Microsoft Teams Envie notificações do projeto para canais do Teams e suporte a ações do Teams.
GitHub Vincule eventos de repositório, problemas, solicitações de pull e commits a tarefas do projeto.
GitLab Vincule solicitações de mesclagem, problemas e eventos de pipeline do GitLab a tarefas do projeto.
Google Calendar Sincronize marcos do projeto e datas de tarefas com o Google Calendar.
Google Drive Anexe ou sincronize documentos do projeto com pastas do Google Drive.
OneDrive Anexe ou sincronize documentos do projeto com pastas do OneDrive.
Zapier / IFTTT Exponha gatilhos e ações SolaProjects para plataformas no-code.

Cada mosaico apresenta um estado (Disponível, Pendente, Ativo, Falhou), a funcionalidade e Configuração do fornecedor em produção detetada. ou O simulador local está disponível; as credenciais de produção são definições de ativação. (o fornecedor ainda não está ativo na organização). Pode também apresentar Bloqueado por configuração em falta: …, Notas de ativação: …, Retorno OAuth pendente., Último erro: …, a última mensagem ou o último evento recebido.

#Eventos que você pode enviar

Selecione um ou mais no formulário de webhook:

Evento Enviado quando
task.created Uma tarefa é criada (incluindo a partir de um webhook de entrada).
task.updated Uma tarefa é editada.
task.status_changed O status de uma tarefa é alterado.
task.completed Uma tarefa é marcada como concluída.
task.blocked Uma tarefa é marcada como bloqueada.
comment.created Um comentário de tarefa é adicionado.
doc.created Um documento de projeto é criado.
time_entry.created O tempo é registrado.
milestone.completed Um marco é concluído.
sprint.started / sprint.completed Uma sprint começa / é concluída.
share_link.created Um link de compartilhamento para convidados é criado.
automation.run_failed / automation.rule_failed Uma execução de automação falha.
ai.suggestion_applied Uma sugestão de IA é aplicada.

Cada pedido é um POST JSON com os cabeçalhos X-SolaProjects-Event (tipo de evento), X-SolaProjects-Delivery (identificador de entrega), X-SolaProjects-Signature (HMAC-SHA256 do corpo original com o segredo de assinatura) e User-Agent: SolaProjects-Webhooks/1.0. Verifique a assinatura antes de confiar num pedido.

Retentativas. Uma entrega com falha é tentada novamente de forma automática após cerca de 1, 5, 15 e 60 minutos; após a quinta tentativa, ela permanece como Falha. Use Tentar novamente para tentar manualmente.

#Tarefas

#Criar um webhook de saída

  1. Abra o projeto → Integrações → Novo webhook.

  2. Preencha Novo webhook de saída:

    Campo Obrigatório Regras / padrões Notas
    Nome Sim Até 160 caracteres. ex: Painel do cliente.
    URL do endpoint (HTTPS) Sim URL válida, de até 2.048 caracteres, HTTPS pública. Espaço reservado https://example.com/hooks/solaprojects. Endereços locais e de rede privada são recusados: "Use um endpoint HTTPS público. URLs de redes locais e privadas são bloqueadas."
    Eventos Sim Pelo menos um. Veja a tabela acima.
    Ativo — Marcado por padrão. Desmarque para salvar como Desativado.
  3. Clique em Criar. Surge Webhook de saída criado. e a janela Segredo de assinatura: «Guarde-o agora — é mostrado apenas uma vez e não pode ser recuperado mais tarde.» Clique em Copiar (Copiado para a área de transferência.), guarde o segredo no sistema recetor e clique em Concluído.

#Editar, testar, rotacionar e arquivar um webhook

Ação Passos Resultado
Editar Alterar nome, URL, eventos ou Ativo → Salvar. Webhook de saída atualizado.
Teste Clique em Testar. Teste de entrega na fila. Uma linha aparecerá em Entregas recentes.
Rotacionar segredo Confirmar Rotacionar segredo — "O segredo atual deixará de funcionar. Atualize os serviços conectados com o novo segredo." Segredo rotacionado. e o novo segredo é mostrado uma vez.
Arquivo Confirmar Arquivar webhook — "Este webhook de saída deixará de entregar eventos do projeto." Webhook arquivado. Selo Arquivado; sem novas entregas; histórico mantido.

#Criar um token de webhook de entrada

  1. Clique em Novo token em Tokens de webhook de entrada.
  2. Nome (obrigatório, até 160 caracteres) e Provedor: Personalizado (padrão) ou GitHub.
  3. Clique em Criar → Token de entrada criado. Copie o Token de webhook de entrada exibido uma única vez: "Use isto como o token na sua URL de webhook de entrada. Exibido apenas uma vez."

O sistema externo então envia POST /api/projects/webhooks/incoming/{token} com um corpo JSON (limite de 60 solicitações por minuto por remetente):

Provedor Corpo O que acontece
Personalizado {"title": "...", "description": "...", "priority": "high"} Cria uma tarefa privada em A fazer (a prioridade padrão é medium; o título é cortado em 180 caracteres). A resposta inclui o novo task_key.
Personalizado {"task_key": "ALN-14", "comment": "..."} Adiciona um comentário interno a essa tarefa.
GitHub Evento de issue ou comentário de issue Uma issue torna-se uma tarefa; um comentário em uma issue cujo título contenha uma chave de tarefa (ex: ALN-14) torna-se um comentário nessa tarefa.

Qualquer outra coisa é recusada com "Webhook rejeitado."; um token revogado ou incorreto recebe a mesma resposta. As tarefas e comentários são criados pela pessoa que criou o token.

Rotacionar emite um novo token e revoga imediatamente o anterior (Token rotacionado.). Revogar pede Revogar token — «Os pedidos que utilizem este token deixarão de ter acesso.» → Token revogado.

#Criar um token de API pública

  1. Clique em Novo token em API Pública.

  2. Nome (obrigatório, até 120 caracteres) e Habilidades (pelo menos uma; projects:read, tasks:read e time:read já estão selecionadas):

    Habilidade Permite
    projects:read Ler este projeto.
    tasks:read / tasks:write Ler / criar e atualizar tarefas.
    time:read / time:write Ler / criar registros de tempo.
  3. Criar → Token de API criado. Copie o Token de API do projeto: "Use isto como um token Bearer para /api/v1. Mostrado apenas uma vez."

As tarefas criadas pela API acionam as mesmas automatizações e webhooks que as criadas na aplicação. Rotacionar → confirmar Rodar token («O token atual deixará de funcionar. Atualize os serviços ligados com o novo token.») → Token de API rotacionado. Revogar → Token de API revogado.

#Repetir uma entrega com falha

Em Entregas recentes, clique em Repetir na linha → Entrega repetida. Verifique o Status e o Resposta após um momento.

#Conectar um provedor nativo

  1. No bloco do provedor, escolha o canal (ex: #projetos para Slack) e clique em Conectar → {Provider} conexão iniciada.
  2. Conclua a caixa de diálogo de autorização {Provider} autorização com Concluir retorno de chamada (ou Mais tarde) → Integração nativa conectada.
  3. Uma vez conectado, use Enviar teste ({Provider} mensagem de teste enviada.), Atualizar ({Provider} atualizado.) ou Desconectar ({Provider} desconectado.).

Blocos em modo de simulador também mostram Simular evento e Erro para verificar a configuração antes que o provedor entre em operação; eles não contatam o serviço real.

#Status

Objeto Status
Webhook de saída Ativo, Desativado (salvo com Ativo desmarcado), Arquivado
Entrega Pendente, Entregue, Falhou, Pular
Entrada / Token de API Ativo, Inativo, Revogado
Provedor nativo Disponível, Pendente, Ativo, Falha

#Permissões

Função Abrir a aba Criar / alterar webhooks, tokens, provedores
Proprietário da organização Sim Sim
Administrador de Projetos Sim Sim
Gerente de projetos que é um Gerente de projeto aqui Sim Sim
Membro do Projeto, projeto Visualizador, convidados Não Não

Se a edição de integrações estiver desativada na organização, o separador fica só de leitura, sem Novo, ações de linha ou Tentar novamente. Uma alteração recusada mostra «As alterações de integração estão desativadas ou não são permitidas.»; uma página desatualizada mostra «Recarregue e tente novamente.» Segredos e tokens nunca voltam a ser mostrados depois da janela inicial, nem aos proprietários.

#Conexão da SolaCountorganização

O item Integrações da barra lateral do espaço de trabalho (/projects/settings/integrations) é outra página. Indica se o SolaProjects está ligado ao SolaCount (Ligado, Pronto para ligar, Integração em pausa, Desligado — histórico preservado, etc.) e permite a um proprietário ou administrador financeiro ligar, pausar, desligar ou verificar a ligação. Um projeto pode optar por não a utilizar no separador Definições (cartão Integrações → Projeto interno / finanças desativadas). Consulte Orçamento e finanças e a Visão geral do SolaProjects.

#Exemplos práticos

#Exemplo 1 — Consultas tornam-se tarefas (cotidiano)

{User 1 name} quer que as consultas do site para {Showroom project name} (DEMO-FIT) cheguem como tarefas.

  1. Novo token → Nome Consultas do site, Provedor Personalizado → Criar; ela entrega o token ao desenvolvedor web.
  2. O site contabiliza {"title": "Quote request – reception desk", "priority": "high"}.
  3. A tarefa ALN-31 Solicitação de orçamento – recepção aparece em A fazer, privado, prioridade Alta. O cartão do token mostra Ultimo uso em 6 de out.

#Exemplo 2 — Feed do painel do cliente com uma falha (cenário completo)

{User 2 name} conecta o painel do site da {Organization name}.

Passo Ação Resultado
1 Novo webhook: Painel do site, https://hooks.company.example.com/projects, eventos task.status_changed, task.completed, milestone.completed. Webhook de saída criado.; segredo de assinatura copiado para o painel.
2 Teste. Entrega de teste na fila.; linha Entregue, Resposta 200.
3 {User 1 name} move ALN-12 para Concluído. Duas entregas: task.status_changed e task.completed, ambas Entregues.
4 O painel está em manutenção. A próxima entrega mostra Pendente, então Falha com Resposta 503; cabeçalho Entregas com falha 1 em vermelho; é tentado novamente em ~1, 5, 15, 60 minutos.
5 Painel restaurado; {User 2 name} clica em Tentar novamente. Entrega reenviada. → Entregue.
6 O TI suspeita que o segredo vazou. {User 2 name} clica em Rotacionar segredo e confirma. Segredo rotacionado.; novo segredo mostrado uma vez; TI atualiza o painel.

#Como se conecta

Onde Link
Tarefas Tokens de entrada e a API criam tarefas e comentários; alterações de tarefas enviam eventos.
Planejamento Conclusão de marco e início/conclusão de sprint enviam eventos.
Automações Aja dentro do SolaProjects; execuções com falha podem ser enviadas como eventos.
Links de compartilhamento para convidados Evento share_link.created.
IA Evento ai.suggestion_applied.
Rastreamento de tempo evento time_entry.created; capacidades de tempo da API.
Configurações Alternância financeira SolaCountpor projetoq4.

#Dicas e problemas comuns

Problema Causa Solução
Guia ausente. Plano abaixo do Premium ou expirado. Atualize ou renove.
Use um endpoint HTTPS público… A URL é http, localhost ou um endereço privado. Use uma URL HTTPS pública.
Segredo ou token perdido. Exibido apenas uma vez. Rotacionar e atualize o outro sistema.
Entregas Falha com um código 4xx. Seu endpoint rejeitou a solicitação (frequentemente verificação de assinatura). Verifique se o endpoint utiliza o segredo atual.
Webhook rejeitado. em chamadas de entrada. Token revogado/incorreto, ou o corpo não tem title ou task_key + comment. Verifique o token e o corpo.
Comentário não adicionado de GitHub. O título do problema não tem chave de tarefa. Coloque a chave (ex: ALN-14) no título do problema.
A API retorna acesso negado. O token não possui a habilidade ou está revogado. Crie um token com as habilidades corretas.
O provedor diz Simulador local está disponível… Ainda não está ativo para sua organização. Peça ao Solavel suporte sobre a ativação.