O SDK de assinatura eletrónica em TypeScript da Firma.dev está aqui: tipado, sem dependências, com cobertura para todos os endpoints

Se tem vindo a integrar assinaturas eletrónicas no seu produto através de chamadas fetch escritas à mão, esse trabalho passa a ser opcional. O SDK TypeScript oficial da Firma.dev já está disponível no npm. Um cliente tipado, todos os 66 endpoints da API de parceiros, sem dependências de tempo de execução. Instale-o e comece a assinar.

npm install @firma-dev/sdk

npm install @firma-dev/sdk

npm install @firma-dev/sdk

O que inclui o SDK TypeScript para assinaturas eletrónicas

O @firma-dev/sdk é o cliente TypeScript oficial e totalmente tipado para a API Firma.dev. Cada endpoint é exposto como um método tipado, agrupado por recurso, para que tenha autocomplemento no editor e segurança em tempo de compilação, em vez de ligações HTTP brutas. O cliente abrange todos os 66 endpoints: modelos, pedidos de assinatura, webhooks, áreas de trabalho, campos personalizados, domínios de e-mail, modelos de e-mail, termos do signatário, gestão de JWT e definições.

É executado no lado do servidor em Node 18 ou posterior, utiliza o fetch integrado, não tem dependências de tempo de execução e possui licença MIT. A versão atual é a 0.2.0.

Por que motivo é importante um cliente de API tipado para assinaturas eletrónicas

O SDK é gerado diretamente a partir da mesma especificação OpenAPI que alimenta a referência da API. Isso significa que os formatos de pedido e resposta correspondem sempre à API ativa. Quando um endpoint muda, os tipos mudam com ele, de modo que um campo incorreto resulta num erro de compilação no seu editor e não num erro 400 para depurar em produção.

Para uma equipa de SaaS que incorpora a assinatura no seu próprio produto, isto elimina toda uma categoria de código de ligação. Acabou-se a manutenção de uma camada HTTP personalizada, as suposições sobre os formatos das cargas de dados ou a leitura repetida da referência sempre que altera um endpoint. As agências que automatizam os fluxos de trabalho de assinatura de clientes obtêm o mesmo benefício: desenvolvem a integração uma vez com métodos tipados e deixam que o compilador detete desvios.

Uma breve análise ao @firma-dev/sdk

Autentique-se com uma única chave de API. O cliente envia-a em cada pedido e analisa as respostas por si.

import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);

import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);

import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);

Aguardar por um método devolve diretamente o corpo da resposta analisado. Quando precisar do estado ou dos cabeçalhos HTTP, chame .withRawResponse():

const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));

const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));

const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));

Os pedidos com falha acionam um FirmaError tipado que contém o código de estado e o corpo do erro analisado, mantendo o tratamento de erros legível:

import { FirmaClient, FirmaError } from "@firma-dev/sdk";

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body);       // parsed error payload
  } else {
    throw err;
  }
}

import { FirmaClient, FirmaError } from "@firma-dev/sdk";

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body);       // parsed error payload
  } else {
    throw err;
  }
}

import { FirmaClient, FirmaError } from "@firma-dev/sdk";

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body);       // parsed error payload
  } else {
    throw err;
  }
}

Mantenha a sua chave de API numa variável de ambiente ou num gestor de segredos, nunca no código do lado do cliente. O SDK foi concebido para utilização no lado do servidor.

Leia o guia completo. Instalação, autenticação, início rápido, operações comuns, tratamento de erros e paginação estão todos explicados na documentação: docs.firma.dev/guides/typescript-sdk. Cada endpoint na referência da API inclui agora um exemplo de copiar e colar do @firma-dev/sdk, para que possa obter uma chamada funcional com os seus parâmetros exatos. Consulte a entrada do registo de alterações v1.28.0 para obter o resumo completo da versão v01.28.00.

Comece a utilizar o SDK da Firma.dev

Instale o SDK, introduza a sua chave de API e envie o seu primeiro pedido. A Firma.dev funciona sob um modelo de pagamento por utilização a 0,049 € por envelope (cerca de 5 cêntimos de dólar), sem contratos e sem mínimos mensais.

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