Boa parte do meu trabalho com clientes na SquadHub é integrar as ferramentas que uma pequena empresa já usa: um ERP, uma plataforma de reservas, uma caixa de e-mail e o Monday.com como o lugar onde a equipe trabalha. Dois desses sistemas mostram bem o padrão.
1. Sincronização de estoque ERP → Monday.com
Contexto. Uma empresa mantém produtos, estoque, custo médio e preço de venda no ERP (OMIE). A equipe comercial trabalha em um quadro do Monday.com. Ela precisa do estoque atualizado no quadro e de um jeito seguro de corrigir o estoque sem abrir o ERP.
Desenho.
- Uma fonte da verdade. O ERP é dono de produtos, estoque e preços. O Monday é a camada de visibilidade e aprovação. A direção de cada campo está escrita, não subentendida.
- Lote agendado, sem endpoint público. O GitHub Actions roda a sincronização ERP → Monday de hora em hora. Nada fica exposto na internet.
- Escrita de volta só depois de aprovação humana. Um ajuste de estoque digitado no Monday só vai para o ERP depois que alguém marca a coluna de aprovação. Esse job roda duas vezes por dia, e o resultado e qualquer erro voltam para o próprio item, onde a equipe vai ver.
- Dry-run em tudo. Todo comando (
sync,process-monday-actions,resolve-stock-duplicates) tem--dry-run. O resolvedor de duplicados roda em dry-run por padrão no CI, então um disparo manual não altera dados por acidente. - Auditar antes de corrigir. Itens duplicados e defasados são apontados por um comando e resolvidos por outro.
Construí sozinho. O repositório tem 48 testes automatizados.
2. Confirmação de reserva → roteiro → documentos
Contexto. Uma empresa de treinamento envia professores para conduzir programas nos seus clientes e reserva as viagens deles em uma plataforma de reservas. Para cada viagem, alguém juntava as confirmações, montava um roteiro e mandava os documentos por e-mail ao professor e a cada prestador de serviço.
Desenho. É um pipeline serverless na Vercel, que construí com outro desenvolvedor.
- Um cron diário e um webhook do Monday disparam a execução. Um lock no Redis impede duas execuções ao mesmo tempo.
- Ele lê só os e-mails finais de confirmação, os que trazem o voucher em PDF ou ICS. A chave do voucher e o ID da mensagem no Gmail, juntos, impedem importar a mesma reserva duas vezes.
- A reserva é vinculada ao professor, às atividades correspondentes e a um item de deslocamento no Monday. Quando o status muda para “Gerar PDF”, os campos obrigatórios são validados e o PDF do roteiro é anexado ao item.
- Uma pessoa revisa o PDF e só então muda para “Enviar documentos”. “Aguardando” nunca autoriza envio.
- Cada prestador recebe um e-mail separado, só com os seus serviços. Um lock por item e um registro durável por destinatário impedem envios duplicados.
- Um envio incerto nunca expira. O operador confere a caixa de e-mail e reconcilia antes de qualquer nova tentativa, e envios já confirmados nunca se repetem.
Todos os endpoints exigem um token secreto. O envio fica desligado até o cliente autorizar a caixa remetente.
O padrão
Os dois sistemas seguem as mesmas regras, e eu as aplico em toda integração:
- Dizer quem é dono de cada dado.
- Tornar toda escrita idempotente, com uma chave que dê para explicar.
- Colocar aprovação humana na frente de tudo o que sai da empresa: uma escrita no ERP ou um e-mail.
- Oferecer dry-run em todo comando.
- Mostrar as falhas onde a equipe de operação já trabalha, e não só em um log.