SignatureKit
APIs de provedores

ZapSign

Crie requests de PDF na ZapSign com credenciais Bearer e erros tipados do SignatureKit.

ZapSign faz upload do PDF, cria a lista de signatários e devolve a primeira URL de assinatura quando disponível. O provider possui a cerimônia externa; SignatureKit possui validação e erros tipados.

Instalação

npm install @signature-kit/http @signature-kit/zapsign

Quando usar

Use ZapSign quando o produto quer um link hospedado de assinatura após upload simples de PDF. Use A1/PDF local quando não há cerimônia upstream.

Mantenha credenciais Redacted

Tokens de provider entram como Redacted.make(...) e são abertos apenas dentro da fronteira HTTP do pacote. Nunca passe tokens remotos para componentes React ou logs.

Request mínimo

zapsign.ts
import * as Alchemy from "alchemy"
import { ZapSignSignatureRequest, providers as zapSignProviders } from "@signature-kit/zapsign"
import { signatureHttpClientLive } from "@signature-kit/http"
import { Effect, Layer, Redacted } from "effect"

export default class Contracts extends Alchemy.Stack<Contracts>()(
  "Contracts",
  {
    providers: Layer.merge(
      zapSignProviders({
        apiToken: Redacted.make(process.env.ZAPSIGN_API_TOKEN ?? ""),
        environment: "sandbox",
        locale: "pt-br",
      }),
      signatureHttpClientLive,
    ),
    state: Alchemy.inMemoryState(),
  },
  Effect.gen(function* () {
    return yield* ZapSignSignatureRequest("contrato-de-servico", {
      title: "Contrato de serviço",
      message: "Revise e assine este documento.",
      documents: [{ fileName: "contract.pdf", mimeType: "application/pdf", contentBase64: pdfBase64 }],
      recipients: [{ name: "Ana Silva", email: "ada@example.com", routingOrder: 1 }],
      send: true,
    })
  }),
) {}

Fatos do provider

  • A opção environment aceita "production", "sandbox" ou "brazil" (base URL https://br.api.zapsign.com.br/api/v1).
  • Aceita um único PDF por request, como o upload de documento da ZapSign.
  • Autorização usa bearer token em Redacted.
  • MIME inválido ou múltiplos documentos falham antes da chamada HTTP.

Erros

Input inválido, falhas HTTP remotas e shapes de resposta inválidos falham como SignatureKitError. Os campos provider, operation e status HTTP são preservados quando a resposta upstream expõe esses dados.

Relacionados

Aguardar um estado final

waitForZapSignSignatureRequest(options, id, pollInterval) consulta imediatamente e repete enquanto o pedido estiver em draft ou sent. O retorno preserva o estado final do provedor, inclusive cancelamento, recusa, exclusão ou expiração; confira state antes de baixar o documento. O intervalo deve ser positivo e finito. Falhas de consulta são propagadas sem retry automático. Interromper o Effect cancela a consulta ativa e impede novas consultas. O prazo fica com a aplicação:

import { waitForZapSignSignatureRequest } from "@signature-kit/zapsign";
import { signatureHttpClientLive } from "@signature-kit/http";
import { Duration, Effect } from "effect";
import type { ZapSignProviderOptions } from "@signature-kit/zapsign";

declare const options: ZapSignProviderOptions;
declare const requestId: string;

const program = waitForZapSignSignatureRequest(options, requestId, Duration.seconds(2)).pipe(
  Effect.timeout(Duration.minutes(5)),
  Effect.provide(signatureHttpClientLive),
);

Como está este guia?

Nesta página