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
-
Abra o projeto → Integrações → Novo webhook.
-
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. -
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
- Clique em Novo token em Tokens de webhook de entrada.
- Nome (obrigatório, até 160 caracteres) e Provedor: Personalizado (padrão) ou GitHub.
- 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
-
Clique em Novo token em API Pública.
-
Nome (obrigatório, até 120 caracteres) e Habilidades (pelo menos uma;
projects:read,tasks:readetime:readjá estão selecionadas):Habilidade Permite projects:readLer este projeto. tasks:read/tasks:writeLer / criar e atualizar tarefas. time:read/time:writeLer / criar registros de tempo. -
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
- No bloco do provedor, escolha o canal (ex: #projetos para Slack) e clique em Conectar → {Provider} conexão iniciada.
- Conclua a caixa de diálogo de autorização {Provider} autorização com Concluir retorno de chamada (ou Mais tarde) → Integração nativa conectada.
- 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.
- Novo token → Nome Consultas do site, Provedor Personalizado → Criar; ela entrega o token ao desenvolvedor web.
- O site contabiliza
{"title": "Quote request – reception desk", "priority": "high"}. - 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. |