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

As aplicações Base44 lidam com processos de negócio 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 nenhuma. O Firma.dev preenche essa lacuna com uma API de assinatura eletrónica que pode ligar a qualquer aplicação Base44 numa tarde, em vez de uma sprint.

Como funciona (sem os pormenores técnicos)

O Firma.dev oferece-lhe duas formas de ligar uma aplicação Base44, e a sua escolha 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 a assinatura que retorna. A Base44 mantém a sua chave de API bloqueada num segredo, para que 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: um signatário abre o documento, assina-o incorporado diretamente dentro da sua aplicação, e um webhook avisa o seu backend no exato momento em que estiver concluído.

O que precisa primeiro

• Uma conta 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 Dashboard → Secrets, adicione um novo segredo e dê-lhe o nome de FIRMA_API_KEY. Nunca coloque a chave no código do frontend, apenas as funções de backend devem ter acesso a ela.

Escreva a função. Em Dashboard → Code → Functions, crie uma nova função (o chat de IA da Base44 pode gerar uma por si). 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 (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."

Monitorize as conclusões com um webhook. Crie uma função de backend para receber o evento e, em seguida, registe-a no Firma.dev em Settings → Webhooks, apontando para https://<your-app-domain>/functions/<function-name>.

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 configuração.

A partir do seu ícone de perfil, vá a Settings → Integrations → New Integration → From URL, e cole o URL da especificação OpenAPI do Firma.dev (verifique 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 — criar um pedido de assinatura a partir de um modelo ou documento

• POST /signing-requests/create-and-send — criar e enviar numa única chamada

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

• GET /signing-requests — listar pedidos de assinatura

• POST /templates/{id}/duplicate — duplicar um modelo para um pedido de assinatura

• GET /templates — listar modelos disponíveis

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

A partir daí, qualquer aplicação pode chamar 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 ao chat de IA da Base44 para ligar as chamadas do Firma.dev aqui também; ele deteta a integração do espaço de trabalho e utiliza-a autonomamente.

Assinatura incorporada

Para aplicações nas quais pretende que o signatário preencha 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-tenant, 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 os programadores

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 de ter sequer uma equipa completa. O Firma.dev cobra por envelope: 0,049 € (~5¢), num modelo pré-pago, sem consumo mínimo mensal, sem contrato. Face aos preços por utilizador da DocuSign, isto é entre 97% a 99% mais barato para qualquer volume que provavelmente atinja enquanto desenvolve.

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

Ambos os caminhos acima permitem copiar e colar, e a maioria dos criadores na Base44 terá isto a funcionar em menos de uma hora. Se pretender que o chat de IA faça a ligação, aponte-o para o guia de integração Base44 do Firma.dev e este poderá gerar as funções diretamente. O Firma.dev também dispõe de um servidor MCP de Docs que pode adicionar em Account Settings → MCP Connections para que o chat de IA possa obter detalhes precisos da API enquanto cria.

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