Briefing de integração: como pedir ao time técnico sem retrabalho

O Studio Vela (fictício) pediu a um fornecedor “integrar o sistema de propostas com o de projetos”. Três semanas depois, veio uma integração que criava o projeto, mas sem o nome do cliente, e duplicava tudo quando a proposta era editada. O fornecedor entregou o que entendeu. O que faltou foi o briefing.

Por que um briefing evita o retrabalho em integrações?

Porque integração parece simples na cabeça de quem pede e esconde decisões na cabeça de quem faz. Quando o pedido não diz o que acontece com dado repetido, campo vazio ou erro, o técnico decide sozinho, e quase nunca decide igual a você.

Antes do briefing, vale entender o que é webhook e como integrar sistemas sem programar, para saber o que o seu caso realmente exige.

O que não pode faltar no briefing de integração?

São oito partes: objetivo, evento, dados, frequência, dono, erro, segurança e teste de aceite. Cada uma responde a uma pergunta que o técnico faria de qualquer jeito. Respondê-las antes é o que corta a semana de idas e vindas.

• Objetivo. O resultado de negócio, em uma frase: “o projeto nasce sozinho quando a proposta for aprovada”.
• Evento. O que dispara: proposta aprovada, formulário enviado, reunião analisada. Em que sistema acontece.
• Dados. Que campos vão, de onde, para onde, com exemplo real fictício. É o mapa de campos.
• Frequência e volume. Na hora ou uma vez ao dia; dezenas ou milhares por dia.
• Dono. Quem decide as regras, quem recebe o alerta se falhar, quem fala com o fornecedor.
• Erro. O que fazer se o destino estiver fora do ar, se o dado vier vazio, se o aviso chegar duas vezes.
• Segurança. Onde a chave fica, quem pode vê-la, o que nunca pode sair de um sistema.
• Teste de aceite. Os casos que provam que está pronto, com o resultado esperado de cada um.

Como descrever dados e erros sem ser técnico?

Descreva com exemplos, não com termos. Mostre um caso real fictício e diga o resultado esperado. Em erro, responda três perguntas: o que fazer se falhar, quantas vezes tentar de novo e quem avisar. O técnico traduz isso para o código.

• Dado repetido. “Se a mesma proposta for aprovada duas vezes, criar um projeto só.” Diga qual campo identifica o registro.
• Campo vazio. “Se não houver e-mail do contato, criar o projeto mesmo assim e avisar o responsável.”
• Sistema fora do ar. “Tentar de novo por algumas horas, com espera maior a cada tentativa; depois, avisar [nome].”
• Volume. Se houver picos (fim do mês, campanha), diga. Há limites de chamadas por minuto em quase todo sistema.

Como tratar segurança e acesso no briefing?

Peça chave com o mínimo de permissão, guardada fora de chat e planilha, com dono e data de revisão. Defina quem pode trocar a chave e como o outro lado é avisado. Se houver assinatura do conteúdo (como HMAC), diga que ela deve ser conferida sobre o corpo recebido, antes de aceitar o aviso.

Quem integra com o Mentrun encontra na página Desenvolvedores exemplos para tratar chaves, avisos, assinatura e erros, com tudo o que o time técnico precisa considerar no desenho.

Como escrever o teste de aceite da integração?

Escreva uma lista de casos com o dado de entrada e o resultado esperado. Inclua o caminho feliz, o dado repetido, o campo vazio e o destino fora do ar. A integração está pronta quando todos passam, e não quando o fornecedor diz que está.

BRIEFING DE INTEGRAÇÃO

1. OBJETIVO
Quando [evento] acontecer em [sistema A], [sistema B] deve [resultado].
Por que isso importa: [uma frase].

2. EVENTO
O que dispara: [evento]
Onde acontece: [sistema A, tela ou ação]
Quem ou o que gera: [pessoa, formulário, rotina]

3. DADOS (anexar mapa de campos)
| Campo na origem | Exemplo (fictício) | Campo no destino | Formato | Se vier vazio |
| [campo] | [exemplo] | [campo] | [formato] | [regra] |
Campo que identifica o registro: [campo]
O que NÃO pode sair do sistema A: [lista]

4. FREQUÊNCIA E VOLUME
Na hora / a cada [intervalo] / uma vez por dia
Volume médio: [n] por dia. Picos: [quando, quanto]

5. DONO
Decide as regras: [nome]
Recebe o alerta se falhar: [nome]
Fala com o fornecedor: [nome]

6. ERRO
Destino fora do ar: [quantas tentativas, com espera crescente; quem avisar]
Dado repetido: [ignorar | atualizar | avisar]. Identificado por: [campo ou cabeçalho Idempotency-Key]
Campo obrigatório vazio: [parar e avisar | seguir sem o campo]

7. SEGURANÇA
Onde a chave fica guardada: [local]
Permissão mínima da chave: [só ler | criar | alterar]
Assinatura do conteúdo: [sim, conferir antes de aceitar | não se aplica]
Quem troca a chave e como o outro lado é avisado: [nome / forma]

8. TESTE DE ACEITE
| Caso | Entrada | Resultado esperado | Passou? |
| Caminho feliz | [dado] | [resultado] | [ ] |
| Dado repetido | [mesmo dado duas vezes] | [um registro só] | [ ] |
| Campo vazio | [dado sem campo] | [regra do item 6] | [ ] |
| Destino fora do ar | [simulado] | [nova tentativa e alerta] | [ ] |

9. PRAZO E ENTREGA
Prazo: [data]. Entrega: [ambiente de teste primeiro | direto]. Documentação: [sim/não].

Como o briefing vira uma automação no Mentrun?

Em muitos casos, o briefing já descreve a automação: o evento é o gatilho, os dados são os campos do aviso e o erro é o responsável que recebe o alerta. Quem monta no Mentrun pode testar o desenho antes de passar qualquer trabalho ao time técnico.

• Receber: o gatilho Ao receber de outro app gera chave e endereço; Escutar um exemplo mostra os campos que chegaram.
• Enviar: o passo Enviar aviso para outro app leva os dados do gatilho; Testar a chamada mostra a resposta de verdade.
• Dono: cada automação tem um responsável, que recebe o aviso no sino quando uma execução falha.
• Falhas: depois de 5 falhas seguidas a automação pausa sozinha e avisa o responsável e os Donos.

Um exemplo prático do desenho pronto está em enviar o resumo da reunião para outro sistema. Para mais gatilhos e passos, veja o recurso Automações.