Criar jobs no Operand a partir de um formulário de solicitação

Integração com n8n: cada resposta do formulário vira um job no Operand, com cliente encontrado ou cadastrado pelo CNPJ e aviso no Google Chat.

🚀

Com o n8n, cada resposta do formulário de solicitação de job da agência vira um job no Operand. O fluxo valida o CNPJ, encontra ou cadastra o cliente, cria o job no projeto definido (por exemplo, o projeto Geral) e avisa a equipe no Google Chat.

É uma alternativa para agências que preferem receber pedidos por formulário em vez de liberar o Acesso Cliente no Operand.

Baixe aqui o arquivo pronto com o fluxo descrito abaixo

O que o fluxo faz em cada situação

SituaçãoResultado
CNPJ inválidoExecução para com erro e nada é criado
Cliente com o CNPJ já existe no OperandJob criado para o cliente existente
Cliente não existeCliente cadastrado e job criado
Job criadoMensagem com o link do job no Google Chat

O que você aprenderá

  • Como o fluxo funciona e quais campos do formulário ele usa
  • Como instalar o fluxo e conectar o Google Forms com segurança
  • Como definir responsável, status e projeto do job
  • Como testar e evitar problemas comuns

Como funciona o fluxo

O formulário envia as respostas para o n8n com um header de autenticação. O fluxo valida os dados antes de qualquer chamada à API do Operand.

flowchart TD
  A[Google Forms + Apps Script] --> B[Webhook com Header Auth]
  B --> C[Campos do formulário] --> D{CNPJ válido?}
  D -- Não --> Z[Fim, nada é criado]
  D -- Sim --> E[Config] --> F[Buscar cliente pelo CNPJ]
  F -- 401 --> G[Login e salvar token] --> F
  F --> H{Cliente existe?}
  H -- Sim --> J[Criar job]
  H -- Não --> I[Criar cliente] --> J
  J --> K{Job criado?}
  K -- Sim --> L[Aviso no Google Chat]
  K -- Não --> M[Erro ao criar o job]

Gatilho

Webhook POST na URL de produção:

https://SEU-N8N/webhook/criar-job-cliente-op-quando-formulario-preenchido
  • Autenticação: Header Auth. Sem o header da credential [OPERAND] Webhook formulário, o n8n responde 403 e o fluxo não executa.
  • O webhook responde 200 antes de processar. Erros posteriores não voltam ao formulário: aparecem só em Executions no n8n.

Campos do formulário

O Apps Script envia cada resposta com o texto exato da pergunta como nome do campo.

Pergunta (campo do body)Uso
Qual o nome da sua empresa?Nome do cliente e mensagem
Informe o CNPJ da sua empresaBusca e cadastro do cliente
Qual o seu nome?Solicitante (descrição e mensagem)
Qual o seu e-mail?E-mail do cliente e contato
Qual o seu Whatsapp?Telefone do cliente e contato
Qual o título do job que você precisa?Título do job
Você precisa desse job pra quando?Prazo (deadline) do job
Nos diga qual sua ideia para esse job, com o máximo de informações possíveis :)Descrição do job
⚠️

Se o texto de uma pergunta mudar, ajuste o nó Campos do formulário. Caso contrário, o campo chega vazio.

Etapas

  1. Webhook recebe o POST autenticado.
  2. Campos do formulário extrai as respostas.
  3. Validar e formatar dados valida o CNPJ (numérico ou alfanumérico, padrão a partir de jul/2026), remove a pontuação de CNPJ e telefone e converte o prazo para AAAA-MM-DD HH:MM:SS. CNPJ inválido encerra a execução sem chamadas externas.
  4. Config reúne os parâmetros do fluxo.
  5. Ler Token Cache e Buscar Cliente na API Operand consultam os clientes filtrando pelo CNPJ (parâmetro term).
  6. Resposta da API decide o próximo passo:
    • HTTP 401 (token inválido ou expirado): Login Operand, Salvar Token Cache e nova consulta, uma única vez por execução.
    • Clientes recebidos: segue.
    • Outra resposta: para em Houve um erro ao consultar os clientes na API!
  7. Selecionar o registro do cliente procura, em records.items, o cliente cujo nationalDocument (sem pontuação) é igual ao CNPJ informado. O cliente existe?
    • Sim: usa o id encontrado.
    • Não: Criar Cliente na API Operand e usa o idPerson retornado. Falha para em Houve um erro ao criar o cliente na API!
  8. Criar job na API Operand cria o job com título, prazo, descrição (solicitante + ideia), responsável, status e projeto do Config.
  9. O job foi criado? confere meta.status = SUCCESS:
    • Sim: Ler URL do Google Chat e, se a URL existir, Enviar para Google Chat. Sem URL, para em URL do Google Chat não configurada!
    • Não: para em Houve um erro ao criar o job através da API!

Endpoints usados

OperaçãoEndpoint
Abrir uma sessãoGET /v1/login
Listar clientesGET /v1/entity/clients?term={CNPJ}
Criar um clientePOST /v1/entity/clients
Criar um jobPOST /v1/jobs

Instalação

Checklist

  • Importar o arquivo .json do fluxo
  • Criar as credentials [OPERAND] API token e [OPERAND] Webhook formulário e selecioná-las nos nós
  • Criar a data table OPERAND API (se ainda não existir) com a linha google_chat_form_cliente
  • Selecionar a data table nos 3 nós que a utilizam
  • Revisar o nó Config, principalmente responsibleId, statusId e projectId
  • Ativar o fluxo
  • Configurar o Apps Script do Google Forms (URL, header e propriedade WEBHOOK_TOKEN)
  • Rodar os testes sugeridos

1. Credentials

CredentialTipoUsada no nóPreenchimento
[OPERAND] API tokenQuery AuthLogin OperandName: tokenAccess · Value: token de acesso da API do Operand
[OPERAND] Webhook formulárioHeader AuthWebhookName: X-Webhook-Token · Value: valor secreto longo e aleatório

A credential de API é a mesma dos outros fluxos do Operand. Se já existir, basta selecioná-la.

2. Data table OPERAND API

Tabela chave e valor, compartilhada com os demais fluxos. Colunas: key e value (string).

keyvalueQuem preenche
operand_api_tokenToken de sessão da APIO próprio fluxo
google_chat_form_clienteURL do webhook do espaço que recebe os avisos de novo jobVocê

Depois de importar, selecione OPERAND API no campo Data table de: Ler URL do Google Chat, Ler Token Cache e Salvar Token Cache.

3. Apps Script do Google Forms

No Google Forms, abra ⋮ > Editor de scripts.

  1. Cole o script abaixo. Ajuste POST_URL para o domínio do n8n e HEADER_NAME para o Name da credential [OPERAND] Webhook formulário.
  2. Em Configurações do projeto > Propriedades do script, crie WEBHOOK_TOKEN com o mesmo Value da credential. Assim o segredo não fica no código.
  3. Em Acionadores, crie um acionador para a função onSubmit, origem Do formulário, evento Ao enviar o formulário.
var POST_URL = "https://SEU-N8N/webhook/criar-job-cliente-op-quando-formulario-preenchido";
var HEADER_NAME = "X-Webhook-Token";

function onSubmit(e) {
  var token = PropertiesService.getScriptProperties().getProperty("WEBHOOK_TOKEN");
  if (!token) throw new Error("Propriedade WEBHOOK_TOKEN não configurada no script.");

  var payload = {};
  e.response.getItemResponses().forEach(function (item) {
    payload[item.getItem().getTitle()] = item.getResponse();
  });

  var headers = {};
  headers[HEADER_NAME] = token;

  var res = UrlFetchApp.fetch(POST_URL, {
    method: "post",
    contentType: "application/json",
    headers: headers,
    payload: JSON.stringify(payload),
    muteHttpExceptions: true
  });

  var code = res.getResponseCode();
  if (code >= 300) {
    throw new Error("n8n respondeu " + code + ": " + res.getContentText());
  }
}
  • O script usa a resposta do próprio evento (e.response). Assim, dois envios simultâneos não se misturam.
  • Se o n8n recusar a requisição, o acionador falha e o Google avisa o dono do script por e-mail.
  • Se a pergunta de prazo for do tipo Data, o Google Forms envia no formato AAAA-MM-DD.

Configurações (nó Config)

Responsável, status e projeto do job são definidos no nó Config. É aqui que você direciona os pedidos para o atendimento analisar.

CampoUsoValor padrão
apiUrlEndereço da API do Operandhttps://api.operand.app/v1
appUrlBase do link do job (/jobs/)https://app4.operand.com.br
responsibleIdID do usuário responsável pelo job, por exemplo alguém do atendimento1102963
statusIdID do status inicial do job, por exemplo um status de triagem0
projectIdID do projeto onde o job é criado, por exemplo o projeto Geral0
googleChatChavekey da data table com a URL do Google Chatgoogle_chat_form_cliente
⚠️

projectId é um valor fixo: todos os jobs vindos do formulário entram no mesmo projeto, independentemente do cliente. Na v1, o projeto precisa pertencer ao mesmo cliente do job, senão a criação responde 422. Confira esse comportamento antes de usar com vários clientes.

⚠️

responsibleId, statusId e projectId são IDs da conta Operand de cada agência. Revise todos na instalação. Ao importar uma nova versão do fluxo, o Config volta aos valores do arquivo, então anote suas alterações.

📘

Os IDs de usuários e status podem ser consultados em Listar usuários internos da conta e Listar status de um tipo de documento.

O fluxo não depende de variáveis de ambiente nem do recurso Variables do n8n. Segredos ficam nas credentials, URLs e token na data table e parâmetros no Config.

Usar Slack, Discord ou outra ferramenta

Troque a URL na data table e ajuste o corpo JSON do nó Enviar para Google Chat ao formato da nova ferramenta (por exemplo, text no Slack e content no Discord).

Usar outro formulário

Qualquer ferramenta que envie um POST com o header de autenticação funciona (Typeform, Tally, formulário do site). Os nomes dos campos precisam bater com o nó Campos do formulário, ou o nó precisa ser ajustado.

Testes e pontos de atenção

Testes sugeridos

Com o fluxo ativo, enviando pela URL de produção:

CenárioResultado esperado
Requisição sem o header de autenticaçãoRecusada com 403, sem execução
CNPJ inválidoExecução para em Validar e formatar dados e nada é criado
CNPJ de cliente já cadastradoJob criado para esse cliente, sem cliente novo
CNPJ novoCliente e job criados, mensagem no Chat
Token em cache apagado ou inválidoLogin automático e linha operand_api_token atualizada

Pontos de atenção

  • Busca de cliente: a busca por term é por trecho de texto e pode trazer mais de um cliente. Por isso o fluxo compara o CNPJ completo, sem pontuação, antes de escolher o registro.
  • Sem deduplicação: envios repetidos do formulário criam jobs repetidos.
  • Prazo: a API espera AAAA-MM-DD HH:MM:SS. Use pergunta do tipo Data no formulário para garantir uma data válida.
  • Descrição: o texto da ideia entra no job sem tratamento, com as quebras de linha convertidas.
  • Erros silenciosos para o cliente: o formulário sempre mostra envio concluído. Falhas aparecem só no n8n. Acompanhe as execuções nas primeiras semanas.

Respostas que o fluxo espera da API

ChamadaSucessoOnde o fluxo lê o resultado
LoginHTTP 200Token no campo Op-Auth-Token
Buscar clientesHTTP 200, meta.status = SUCCESSLista em records.items, com id e nationalDocument
Criar clienteHTTP 200, meta.status = SUCCESSID em records.idPerson (o fluxo envia o header customResponse: recordCreated)
Criar jobHTTP 201, meta.status = SUCCESSJob em records[0] (id e title)

Token ausente, inválido ou expirado responde HTTP 401 em qualquer rota.

Erros comuns

SintomaCausa provávelComo resolver
E-mail de falha do Google Apps ScriptHeader errado ou fluxo inativoConfira HEADER_NAME, WEBHOOK_TOKEN e se o fluxo está ativo
Campos vazios no jobTexto da pergunta mudouAjuste Campos do formulário
Cliente duplicadoCNPJ cadastrado com outro valor no OperandConfira o cadastro e trate o duplicado no Operand
URL do Google Chat não configurada!Linha ausente na data tableCrie a linha com a key de googleChatChave
HTTP 400 ao criar o jobPrazo em formato não aceito ou campo obrigatório ausenteRevise o tipo da pergunta de prazo e o nó Validar e formatar dados
HTTP 422 ao criar o jobProjeto de outro cliente, fechado ou IDs inválidosRevise projectId, responsibleId e statusId no Config

Did this page help you?