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ção | Resultado |
|---|---|
| CNPJ inválido | Execução para com erro e nada é criado |
| Cliente com o CNPJ já existe no Operand | Job criado para o cliente existente |
| Cliente não existe | Cliente cadastrado e job criado |
| Job criado | Mensagem 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 empresa | Busca 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
- Webhook recebe o POST autenticado.
- Campos do formulário extrai as respostas.
- 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. - Config reúne os parâmetros do fluxo.
- Ler Token Cache e Buscar Cliente na API Operand consultam os clientes filtrando pelo CNPJ (parâmetro
term). - 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!
- Selecionar o registro do cliente procura, em
records.items, o cliente cujonationalDocument(sem pontuação) é igual ao CNPJ informado. O cliente existe?- Sim: usa o
idencontrado. - Não: Criar Cliente na API Operand e usa o
idPersonretornado. Falha para em Houve um erro ao criar o cliente na API!
- Sim: usa o
- Criar job na API Operand cria o job com título, prazo, descrição (solicitante + ideia), responsável, status e projeto do Config.
- 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ção | Endpoint |
|---|---|
| Abrir uma sessão | GET /v1/login |
| Listar clientes | GET /v1/entity/clients?term={CNPJ} |
| Criar um cliente | POST /v1/entity/clients |
| Criar um job | POST /v1/jobs |
Instalação
Checklist
- Importar o arquivo
.jsondo fluxo - Criar as credentials
[OPERAND] API tokene[OPERAND] Webhook formulárioe selecioná-las nos nós - Criar a data table
OPERAND API(se ainda não existir) com a linhagoogle_chat_form_cliente - Selecionar a data table nos 3 nós que a utilizam
- Revisar o nó Config, principalmente
responsibleId,statusIdeprojectId - Ativar o fluxo
- Configurar o Apps Script do Google Forms (URL, header e propriedade
WEBHOOK_TOKEN) - Rodar os testes sugeridos
1. Credentials
| Credential | Tipo | Usada no nó | Preenchimento |
|---|---|---|---|
[OPERAND] API token | Query Auth | Login Operand | Name: tokenAccess · Value: token de acesso da API do Operand |
[OPERAND] Webhook formulário | Header Auth | Webhook | Name: 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).
| key | value | Quem preenche |
|---|---|---|
operand_api_token | Token de sessão da API | O próprio fluxo |
google_chat_form_cliente | URL do webhook do espaço que recebe os avisos de novo job | Você |
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.
- Cole o script abaixo. Ajuste
POST_URLpara o domínio do n8n eHEADER_NAMEpara o Name da credential[OPERAND] Webhook formulário. - Em Configurações do projeto > Propriedades do script, crie
WEBHOOK_TOKENcom o mesmo Value da credential. Assim o segredo não fica no código. - 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.
| Campo | Uso | Valor padrão |
|---|---|---|
apiUrl | Endereço da API do Operand | https://api.operand.app/v1 |
appUrl | Base do link do job (/jobs/) | https://app4.operand.com.br |
responsibleId | ID do usuário responsável pelo job, por exemplo alguém do atendimento | 1102963 |
statusId | ID do status inicial do job, por exemplo um status de triagem | 0 |
projectId | ID do projeto onde o job é criado, por exemplo o projeto Geral | 0 |
googleChatChave | key da data table com a URL do Google Chat | google_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,statusIdeprojectIdsã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ário | Resultado esperado |
|---|---|
| Requisição sem o header de autenticação | Recusada com 403, sem execução |
| CNPJ inválido | Execução para em Validar e formatar dados e nada é criado |
| CNPJ de cliente já cadastrado | Job criado para esse cliente, sem cliente novo |
| CNPJ novo | Cliente e job criados, mensagem no Chat |
| Token em cache apagado ou inválido | Login 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
| Chamada | Sucesso | Onde o fluxo lê o resultado |
|---|---|---|
| Login | HTTP 200 | Token no campo Op-Auth-Token |
| Buscar clientes | HTTP 200, meta.status = SUCCESS | Lista em records.items, com id e nationalDocument |
| Criar cliente | HTTP 200, meta.status = SUCCESS | ID em records.idPerson (o fluxo envia o header customResponse: recordCreated) |
| Criar job | HTTP 201, meta.status = SUCCESS | Job em records[0] (id e title) |
Token ausente, inválido ou expirado responde HTTP 401 em qualquer rota.
Erros comuns
| Sintoma | Causa provável | Como resolver |
|---|---|---|
| E-mail de falha do Google Apps Script | Header errado ou fluxo inativo | Confira HEADER_NAME, WEBHOOK_TOKEN e se o fluxo está ativo |
| Campos vazios no job | Texto da pergunta mudou | Ajuste Campos do formulário |
| Cliente duplicado | CNPJ cadastrado com outro valor no Operand | Confira o cadastro e trate o duplicado no Operand |
| URL do Google Chat não configurada! | Linha ausente na data table | Crie a linha com a key de googleChatChave |
| HTTP 400 ao criar o job | Prazo em formato não aceito ou campo obrigatório ausente | Revise o tipo da pergunta de prazo e o nó Validar e formatar dados |
| HTTP 422 ao criar o job | Projeto de outro cliente, fechado ou IDs inválidos | Revise projectId, responsibleId e statusId no Config |
Updated 25 days ago

