Como Adicionar Assinaturas Eletrónicas à Sua Aplicação Base44

As aplicações Base44 lidam com processos de negócios reais: propostas, contratos de prestação de serviços, formulários de admissão, documentação de integração. Nada disso se fecha de forma limpa sem uma assinatura, e a Base44 não disponibiliza uma de raiz. O Firma.dev preenche essa lacuna com uma API de e-signature que pode ligar a qualquer aplicação Base44 numa tarde, e não num sprint.

Como funciona (sem os detalhes técnicos)

O Firma.dev oferece-lhe duas formas de ligar uma aplicação Base44, e a escolha de qual delas utilizar depende de quantas aplicações está a executar.

Se for uma única aplicação, escreve uma função de backend: um pequeno pedaço de TypeScript que chama a API REST do Firma.dev para criar um pedido de assinatura, enviá-lo e escutar o retorno da assinatura. A Base44 mantém a sua chave de API bloqueada num segredo, para que esta nunca toque no navegador.

Se estiver a executar um espaço de trabalho com várias aplicações, regista o Firma.dev uma vez como uma integração personalizada utilizando a sua especificação OpenAPI. Depois disso, todas as aplicações no espaço de trabalho podem chamar os endpoints do Firma.dev diretamente através do SDK da Base44, sem necessidade de uma função separada por aplicação.

Qualquer um dos caminhos termina da mesma forma: o signatário abre o documento, assina-o incorporado diretamente dentro da sua aplicação e um webhook avisa o seu backend no instante em que estiver concluído.

O que necessita primeiro

• Uma conta do Firma.dev com uma chave de API

• Uma aplicação Base44 no plano Builder ou superior (necessário para funções de backend e integrações personalizadas)

• Um modelo do Firma.dev com campos de assinatura já configurados

Caminho 1: funções de backend

Esta é a rota mais flexível, e aquela a que deve recorrer se estiver a ligar uma única aplicação.

Guarde a chave. No editor da Base44, vá a Painel de Controlo → Segredos, adicione um novo segredo e dê-lhe o nome de FIRMA_API_KEY. Nunca coloque a chave no código de frontend, apenas as funções de backend devem ter acesso à mesma.

Escreva a função. Em Painel de Controlo → Código → Funções, crie uma nova função (ou peça ao chat de IA da Base44 para gerar uma). Este é o exemplo exato da documentação do Firma.dev, criando e enviando um pedido de assinatura a partir de um modelo numa única chamada:

import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});

import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});

import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});

Se preferir rever um pedido antes de este ser enviado, a documentação do Firma.dev indica a alternativa: POST /signing-requests para criar um rascunho, e depois POST /signing-requests/{id}/send separadamente.

Ligue-o à Interface de Utilizador (UI). Chame a função a partir do frontend com o SDK da Base44:

import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});

import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});

import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});

Ou simplesmente diga ao chat de IA da Base44 o que pretende: "Quando o utilizador clicar em 'Enviar Contrato', chama a função sendSigningRequest com o ID do modelo, o email do signatário e o nome a partir do formulário."

Acompanhe as conclusões com um webhook. Crie uma função de backend para receber o evento, depois registe-a no Firma.dev em Definições → Webhooks, apontando para https://<seu-dominio-da-app>/functions/<nome-da-funcao>.

import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});

import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});

import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});

Caminho 2: integração OpenAPI ao nível do espaço de trabalho

Está a executar mais do que uma aplicação Base44? Configure isto uma vez e todas as aplicações no espaço de trabalho herdam a integração.

A partir do seu ícone de perfil, aceda a Definições → Integrações → Nova Integração → A partir de URL, e cole o URL da especificação OpenAPI do Firma.dev (consulte o registo de alterações da API do Firma.dev para obter a versão atual). Escolha os endpoints que necessita, até 30, sendo os mais comuns:

• POST /signing-requests — cria um pedido de assinatura a partir de um modelo ou documento

• POST /signing-requests/create-and-send — cria e envia numa única chamada

• GET /signing-requests/{id} — verifica o estado

• GET /signing-requests — lista os pedidos de assinatura

• POST /templates/{id}/duplicate — duplica um modelo num pedido de assinatura

• GET /templates — lista os modelos disponíveis

Para autenticação, defina o URL base para https://api.firma.dev/functions/v1/signing-request-api, depois adicione um cabeçalho personalizado com o nome Authorization e com a sua chave de API do Firma.dev como valor. A Base44 encripta e armazena-o ao nível do espaço de trabalho, pelo que nunca chega ao navegador.

A partir daí, qualquer aplicação chama o Firma.dev diretamente:

const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);

const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);

const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);

Peça também ao chat de IA da Base44 para ligar as chamadas do Firma.dev aqui; este deteta a integração do espaço de trabalho e utiliza-a por si próprio.

Assinatura incorporada

Para aplicações onde deseja que o signatário complete o documento sem sair da sua interface, extraia o signing_request_user_id da resposta da API e carregue-o num iframe:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

O que obtém de imediato

Cada pedido de assinatura criado desta forma herda o produto real do Firma.dev, e não um wrapper de API simplificado: um editor de modelos incorporável para criar documentos, Espaços de Trabalho de Clientes se estiver a executar uma aplicação Base44 multi-inquilino, e validade jurídica em mais de 55 países ao abrigo de SES e AES (alinhado com o eIDAS; o Firma.dev ainda não oferece QES).

O preço faz sentido para criadores

As aplicações Base44 encontram-se habitualmente numa fase inicial, o que torna as ferramentas de assinatura com preços por utilizador uma má opção antes mesmo de ter uma equipa completa. O Firma.dev cobra, em alternativa, por envelope: €0,049 (~5¢), pré-pago, sem mínimo mensal, sem contrato. Face ao preço por utilizador da DocuSign, isto é 97% a 99% mais barato em qualquer volume que provavelmente atinja enquanto desenvolve.

Envie isto ao seu programador (ou faça você mesmo)

Ambos os caminhos acima permitem copiar e colar, e a maioria dos criadores na Base44 conseguirá colocar isto a funcionar em menos de uma hora. Se quiser que o chat de IA faça as ligações por si, aponte-o para o guia de integração Base44 do Firma.dev para que este possa gerar as funções diretamente. O Firma.dev também dispõe de um servidor MCP de documentação que pode adicionar em Definições de Conta → Ligações MCP, para que o chat de IA possa obter detalhes precisos da API enquanto desenvolve.

Comece a utilizar o Firma.dev gratuitamente, sem necessidade de cartão de crédito.