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 com chamadas fetch escritas à mão, esse trabalho agora é opcional. O SDK oficial em TypeScript do Firma.dev está disponível no npm. Um cliente tipado, todos os 66 endpoints da API de parceiros, sem dependências de runtime. Instale-o e comece a assinar.

npm install @firma-dev/sdk

npm install @firma-dev/sdk

npm install @firma-dev/sdk

O que vem incluído no SDK de assinatura eletrónica em TypeScript

O @firma-dev/sdk é o cliente oficial em TypeScript, totalmente tipado, para a API do Firma.dev. Cada endpoint é exposto como um método tipado, agrupado por recurso, para que tenha autoconclusão no editor e segurança em tempo de compilação, em vez de ligações HTTP brutas. O cliente cobre todos os 66 endpoints: modelos, pedidos de assinatura, webhooks, áreas de trabalho, campos personalizados, domínios de email, modelos de email, 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, vem com zero dependências de runtime e tem licença MIT. A versão atual é a 0.2.0.

Por que razão um cliente de API de assinatura eletrónica tipado é importante

O SDK é gerado diretamente a partir da mesma especificação OpenAPI que alimenta a referência da API. Isso significa que as estruturas de pedido e resposta correspondem sempre à API em tempo real. Quando um endpoint muda, os tipos mudam com ele, pelo que um campo incorreto se torna num erro de compilação no seu editor, em vez de um erro 400 que tem de depurar em produção.

Para uma equipa de SaaS que integra assinaturas no seu próprio produto, isto remove toda uma categoria de código de ligação. Acabou-se a manutenção de uma camada HTTP personalizada, as suposições sobre as estruturas de payload e a releitura da referência sempre que mexe num endpoint. As agências que automatizam os fluxos de trabalho de assinatura de clientes obtêm o mesmo benefício: desenvolva a integração uma vez com métodos tipados e deixe o compilador detetar divergências.

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 analisada. Quando precisar do estado HTTP ou dos cabeçalhos, 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 lançam um erro tipado FirmaError que transporta o código de estado e o corpo do erro analisado, mantendo a gestão 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;
  }
}

Guarde 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, gestão de erros e paginação estão todos cobertos 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 de registo de alterações v1.28.0 para ver o resumo completo da versão v01.28.00.

Começar a utilizar o SDK da Firma.dev

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

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