Signaturit no Odoo: o que lhe dá um módulo nativo que o Zapier não dá

Resposta curta: o Zapier serve para disparar uma assinatura e saber que foi concluída. Não serve para refletir dentro do Odoo os estados intermédios por que passa um documento, nem para recuperar de um webhook perdido, nem para deixar o PDF assinado e o respetivo documento probatório arquivados no registo correto. Se o seu processo acaba quando o cliente assina, um Zap chega e é mais barato. Se o seu processo começa quando o cliente assina (faturar, abrir um processo, admitir um funcionário), precisa dos estados dentro do ERP.

O ponto de partida: o documento viaja por e-mail

O circuito habitual tem três passos manuais: alguém gera o PDF do orçamento no Odoo, carrega-o no painel da Signaturit e espera; quando o cliente assina, o PDF assinado chega à caixa de entrada de uma pessoa; essa pessoa volta a carregá-lo no Odoo, se se lembrar. Os sintomas são sempre os mesmos: ninguém sabe se o cliente o abriu, o PDF assinado acaba no ambiente de trabalho de alguém e, quando é preciso a prova (o documento probatório, o audit trail), não está junto da fatura, que é onde qualquer pessoa a procuraria.

Antes de mais, um requisito que afeta os três caminhos por igual: o seu plano da Signaturit tem de incluir acesso à API. A autenticação é um token Bearer que se obtém no painel, e sandbox e produção são dois registos distintos com dois tokens distintos. A Signaturit não publica abertamente que planos incluem esse acesso, por isso confirme-o com eles antes de desenhar o que quer que seja. Sem token não há Zap, nem n8n, nem módulo.

As três formas de os ligar, e onde basta o Zapier

A app da Signaturit no Zapier publica, à data de hoje, um único trigger («New Signed Document», ou seja, «um documento foi assinado») e cinco ações: criar um pedido de assinatura, criá-lo a partir de um modelo, cancelá-lo, enviar um lembrete e criar um e-mail certificado. A app do Odoo auto-alojado, por sua vez, expõe triggers e ações genéricos de registo (criar um registo, uma lead, uma tarefa…). Essa é toda a matéria-prima disponível.

Onde basta o Zapier (e pode parar de ler)

Se envia um único tipo de documento, poucos por mês, e só precisa de que, ao ser assinado, se crie uma tarefa ou se avise por chat, monte um Zap e não complique mais. Também basta se o documento não nasce no Odoo (um NDA preparado no painel da Signaturit). A regra é esta: se o estado da assinatura não altera nenhuma decisão dentro do ERP, o ERP não precisa de o saber.

Que documento sai de que modelo do Odoo

Esta é a parte que um passo genérico de «criar registo» não consegue fazer: não sabe renderizar o relatório QWeb de uma encomenda de venda. Cada modelo precisa de três coisas suas: o título que o signatário verá, o destinatário por defeito e a forma como o PDF é gerado. No conector que construímos, cada ponte resolve exatamente esses três pontos.

• Orçamento e encomenda de venda (sale.order): o relatório standard de encomenda de venda, com o cliente como signatário.
• Fatura (account.move) e ordem de compra (purchase.order), para aceitações e confirmações de fornecedor.
• Guia de remessa (stock.picking): o relatório de guia, que, depois de assinado, funciona como prova de entrega.
• Contrato de trabalho: hr.contract no Odoo 17 e 18, e hr.version no Odoo 19, onde o módulo de RH foi reformulado. O tipo de pormenor que obriga a manter três ramos do código, não um.
• Proposta a um candidato (hr.applicant), oportunidade de CRM (crm.lead), ticket (helpdesk.ticket) e projeto e tarefa, para aceitações de trabalho realizado.

O ciclo de estados completo, que é onde tudo o resto falha

A API v3 da Signaturit informa, por documento, de oito estados: in_queue, ready, signing, completed, expired, canceled, declined e error. Os seus eventos de webhook são ainda mais granulares: e-mail entregue, e-mail devolvido, documento aberto, documento assinado, documento de identidade adicionado, prazo alargado, audit trail gerado…

Dentro do Odoo isso tem de se converter em duas coisas distintas. Primeira: o pedido em si, com o seu próprio ciclo (rascunho, enviado, em curso, concluído, rejeitado, caducado, cancelado, erro). Segunda: um campo no documento de origem, para que o comercial que abre o orçamento veja o estado sem sair do orçamento. No nosso conector esse campo tem sete valores: por enviar, pendente de assinatura, assinado, rejeitado, caducado, cancelado e erro.

Com vários signatários, o estado tem de ser deduzido do conjunto: todos concluídos, concluído; um que rejeita, rejeitado; uns assinados e outros não, em curso. E há uma proteção que só se aprende a falhar: um pedido cancelado manualmente nunca deve deixar-se sobrescrever por um evento posterior, porque a Signaturit pode reportar error por documento num pedido que você já tinha cancelado. Sem ela, um cancelamento deliberado transforma-se sozinho num erro inexplicável.

A última peça: os três estados terminais maus (rejeitado, caducado e erro) não podem acabar só por mudar uma cor. No conector geram uma atividade pendente para a pessoa que criou o pedido, com a instrução de decidir se se reenvia, se se alarga o prazo ou se se substitui. Uma rejeição que ninguém vê é exatamente o mesmo que não ter conhecimento dela.

Novas tentativas e falhas: porque é que um webhook perdido é pior do que um erro visível

Um erro visível pára-o. Um webhook perdido deixa-o a acreditar que o documento continua pendente quando está assinado há dias: ou ao contrário. A segunda situação é muito mais cara, porque ninguém a procura.

As novas tentativas têm de ser assimétricas. No conector, cada chamada tem um tempo máximo de espera de 30 segundos por defeito, configurável. Uma leitura (GET) é repetida até duas vezes, com espera crescente, perante um 429, 500, 502, 503 ou 504. Uma escrita (POST, PATCH, DELETE) nunca é repetida: repetir uma criação que não é idempotente significa enviar o mesmo contrato duas vezes ao mesmo signatário. Mais vale um erro visível do que uma duplicação silenciosa. E uma regra que costuma faltar: um redirecionamento da API é tratado como erro grave e nunca é seguido, porque segui-lo com o cabeçalho de autorização presente é entregar o seu token ao endereço que o Location indicar.

O webhook não é a verdade: é uma campainha. A Signaturit não assina criptograficamente os seus webhooks (não há HMAC) e a sua documentação não descreve nenhuma política de nova tentativa automática; oferece, sim, um endpoint para relançar um evento manualmente. Com isto em cima da mesa, o evento recebido no conector é autenticado com um token por conta dentro do próprio URL, opcionalmente restringe-se ao IP de origem que a Signaturit publica (um só, o mesmo em sandbox e em produção), regista-se com uma chave de deduplicação SHA-256 do JSON canonizado e, então (e só então), volta a consultar-se a API autenticada. Uma entrega duplicada responde 200 e não é processada duas vezes.

E se o evento nunca chega, há uma rede de segurança: um cron horário percorre até 200 pedidos pendentes e volta a consultá-los. Essa linha é a diferença real face a um Zap. O Zap depende do webhook; se o webhook se perde, não há mais nada.

O anexo que regressa: onde se guarda, com que nome e com que auditoria

Quando o pedido chega a concluído, regressam dois ficheiros, não um. O PDF assinado é arquivado como <nombre>.signed.pdf e o documento probatório como <nombre>.audit_trail.pdf, ambos anexados ao registo do pedido, que por sua vez aponta para o orçamento, a fatura ou a guia de que saiu. Nenhum dos dois acaba na caixa de entrada de ninguém.

Um pormenor que só aparece em produção: o documento probatório nem sempre está pronto quando o documento é assinado. A Signaturit gera-o à parte e emite um evento próprio quando está disponível. Se o download falha, não se deve deixar um buraco: é preciso pedir explicitamente a sua geração e recuperá-lo no ciclo seguinte. Um conector que descarregue o PDF assinado e se esqueça do rasto deixa-o com metade da prova. E se pediu ao signatário que carregasse documentação (cartão de cidadão, comprovativo de morada), esses ficheiros são descarregados à parte, num ZIP, para o mesmo registo.

O que avaliar antes de escolher a abordagem

1. Quantos tipos de documento envia para assinatura? Um só, um Zap. Quatro ou mais, cada um com o seu PDF e o seu destinatário, e manter quatro Zaps já custa mais do que um módulo.
2. O estado da assinatura altera alguma decisão dentro do Odoo? Se, ao ser assinado, é preciso faturar, planear ou admitir alguém, o ERP precisa do estado. Se só é preciso avisar alguém, não.
3. Precisa do documento probatório arquivado? Se o tem de mostrar a uma inspeção ou num litígio, é melhor que esteja junto da fatura.
4. O que acontece se ninguém olhar para o painel durante duas semanas? Pergunte a quem aparece uma tarefa quando um contrato caduca sem assinatura. Se a resposta for «a ninguém», ainda não tem integração.
5. Quantas versões do Odoo tem de suportar? Um Zap não depende da versão; um módulo sim, e o salto de hr.contract para hr.version é o custo real disso.
6. O seu plano da Signaturit tem API? Sem token não funciona nenhuma das três opções. Confirme-o antes de mais.

De onde vem tudo isto

Construímos sete módulos sobre esta integração: o núcleo, que resolve contas, pedidos, destinatários, eventos e arquivo, e seis pontes para CRM, apoio ao cliente, RH, projetos, recrutamento e armazém. No total, 270 testes automatizados no ramo do Odoo 19, 262 no do 18 e 266 no do 17: o mesmo código é mantido em simultâneo para as três versões.

Nenhuma das decisões deste artigo resulta de ler a documentação. Resultam de rondas sucessivas de QA contra o conector real: numa só ronda foram corrigidos 23 defeitos encontrados a testá-lo em direto e mais 5 de uma auditoria adversarial contra a documentação da API; na seguinte, mais 17. O registo de alterações do módulo enumera-os um a um, com data. Uma ficha autogerada de «produto A × produto B» não tem nenhuma dessas cicatrizes, porque ninguém a usou alguma vez.

Ligações úteis dentro da FlexigoTech

Perguntas frequentes

O que fazemos sobre isto