Integração de Apps do Marketplace

Se você está desenvolvendo um aplicativo e deseja integrá-lo ao Workflow, esta documentação mostra como fazer isso.

Para que o Workflow consiga identificar e utilizar seu app como parte de um fluxo de automação, é obrigatório que seu aplicativo exponha a rota HTTP /service/workflow/actions, retornando as ações (actions) e gatilhos (triggers) disponíveis no formato esperado.

Essa rota será consultada automaticamente pelo Workflow para que as funcionalidades do seu app possam ser utilizadas como nós de ação ou evento em fluxos automatizados, conectando diferentes sistemas de maneira fluida, inteligente e personalizável.

Transformando funções do seu app em actions ou triggers

Nem toda funcionalidade precisa ser reescrita para ser integrada ao Workflow. Muitas vezes, você já possui métodos prontos que podem ser adaptados com facilidade para funcionar como actions ou triggers.

Exemplo 1 — Transformando uma função “baixa em conta corrente” em uma action

Suponha que você tenha a seguinte função no seu backend:

func BaixarConta(id string, valor float64) error {
    // lógica de baixa no sistema financeiro
}

Para que essa funcionalidade seja exposta ao Workflow como uma action, você deve:

1. Criar uma rota HTTP, por exemplo: /api/contas/:id/baixa
2. Estruturar os parâmetros como ParamInput, indicando se vêm do path, query ou body
3. Adicionar essa definição no JSON retornado pela rota /service/workflow/actions:

{
  "name": "baixar_conta",
  "title": "Baixar Conta Corrente",
  "label": "Realiza a baixa de uma conta corrente no sistema financeiro",
  "icon": "https://seusistema.com/icons/finance.svg",
  "url": "https://seusistema.com/api/contas/:id/baixa",
  "method": "POST",
  "parameters": [
    {
      "name": "id",
      "type": "string",
      "required": true,
      "direction": "ParamInput",
      "description": "ID da conta a ser baixada",
      "source": "path"
    },
    {
      "name": "valor",
      "type": "number",
      "required": true,
      "direction": "ParamInput",
      "description": "Valor a ser baixado",
      "source": "query"
    },
    {
      "name": "mensagem",
      "type": "string",
      "required": false,
      "direction": "ParamOutput",
      "description": "Confirmação de baixa"
    }
  ]
}

📬Exemplo 2 — Transformando uma função “ao receber mensagem” em um trigger

Se o seu app já possui uma funcionalidade que recebe mensagens (via webhook ou API), você pode transformá-la em um trigger para o Workflow.

Função original:

func ReceberMensagem(mensagem string) {
    // salva no banco, envia alerta, etc.
}

O que você precisa fazer:

1. Quando a mensagem for recebida, envie um evento para o Workflow:

POST https://workflow.iugu.com/services/event

Authorization: Bearer Content-Type: application/json

{
	"event": "on_new_message",
	"workspace_id": "",
	"payload": {
          "message": "Texto da mensagem recebida"
	}
}

1. Exponha esse trigger na rota /service/workflow/actions da seguinte forma:

{
  "name": "on_new_message",
  "title": "Ao receber nova mensagem",
  "label": "Dispara quando uma nova mensagem for recebida",
  "icon": "https://seusistema.com/icons/chat.svg",
  "parameters": [
    {
      "name": "message",
      "type": "string",
      "required": true,
      "direction": "ParamOutput",
      "description": "Conteúdo da mensagem recebida"
    }
  ]
}

🧠 Resumo

Estrutura esperada da resposta

A resposta da rota /service/workflow/actions deve ser um JSON contendo dois arrays:

• actions: lista de operações que o Workflow poderá executar.
• triggers: lista de eventos que poderão iniciar um fluxo.

{
  "actions": [ /* lista de ações disponíveis */ ],
  "triggers": [ /* lista de eventos disponíveis */ ]
}

🔗 Veja um exemplo real onde o aplicativo Google Sheets expõe suas actions e triggers para serem consumidas pelo Workflow

Campos comuns de uma ação ou trigger

Detalhamento dos parâmetros (parameters)

Cada item de parameters define um campo necessário para execução da ação ou evento gerado pelo trigger.

direction — Input vs Output

• ParamInput: são dados que o sistema precisa fornecer para que a ação seja executada.
• ParamOutput: são dados gerados ou retornados após a execução da ação ou trigger.

Em triggers, todos os parâmetros devem ser ParamOutput.

source — De onde vem o dado?

Para ParamInput, o campo source define a localização do dado dentro da requisição HTTP:

• query: Query string (?workspace_id=abc)
• path: Path parameter (/api/sheets/:spreadsheet_id/insert)
• body: Corpo da requisição (normalmente em JSON)

Em ParamOutput, o campo source pode ser omitido ou deixado em branco.

Autenticação e segurança

Para garantir que as comunicações entre o Workflow e o seu aplicativo sejam seguras e autenticadas, é essencial seguir as diretrizes abaixo:

Validação do access token nas chamadas recebidas

Sempre que o Workflow chamar uma action do seu aplicativo, ele incluirá um token JWT no header da requisição:

Authorization: Bearer

Seu app deve validar esse token antes de processar a requisição, garantindo que:

• O token seja assinado por uma autoridade confiável (ex: sistema OAuth interno ou provedor autorizado).
• O token esteja dentro do prazo de validade (exp).
• O audience (aud) corresponda ao seu aplicativo ou escopo esperado.

Isso protege sua aplicação contra chamadas não autorizadas.

Geração de access token ao executar um trigger

Quando seu app disparar uma trigger para o Workflow (por exemplo, notificando que uma nova mensagem foi recebida), é sua responsabilidade gerar um token de acesso válido com o audience correto (esperado pelo Workflow) e incluí-lo no header da requisição que entrega os dados da trigger.

Exemplo:

POST https://workflow.iugu.com/services/event

Authorization: Bearer Content-Type: application/json

{
	"event": "on_new_message",
	"workspace_id": "",
	"payload": {
          "message": "Texto da mensagem recebida"
	}
}

⚠️ Triggers disparadas sem um token válido serão rejeitadas pelo Workflow.

Resumo

Manter essas boas práticas garante segurança, rastreabilidade e compatibilidade total com o ecossistema do Workflow.

Boas práticas

• Use nomes de parâmetro curtos e significativos.
• Descreva cada parâmetro de forma objetiva.
• Prefira camel_case em name, mas Title Case em title e label.
• Sempre inclua um icon válido, especialmente para interfaces visuais.