Übersicht

Was Sie wissen müssen, bevor Sie anfangen

https://api.signido.de/api/v1

Die Basis-URL. Jeder Pfad in dieser Dokumentation ist relativ dazu.

Authorization: Bearer sg_…

Ein API-Schlüssel, nichts anderes. Ein Schlüssel wird nie automatisch vom Browser mitgeschickt — deshalb kann eine fremde Seite mit ihm nichts auslösen. Siehe Authentifizierung.

Eine Organisation

Ein Schlüssel gehört zu genau einer Organisation und kann keine andere adressieren. Es gibt keinen Parameter, mit dem das umgangen werden könnte.

application/json

Ein- und Ausgabe sind JSON — außer beim Upload (multipart/form-data) und beim Download (Binärdaten). Unbekannte Felder im Body werden abgelehnt, nicht ignoriert.

sg_test_ und sg_live_

Ein Test-Schlüssel erzeugt keine Rechnungen und keine echten Anbieter-Aufrufe. Ein Live-Schlüssel ist ausschließlich in der Produktionsumgebung gültig.

Der erste Aufruf

Ein Schlüssel im Header, ein GET. Die Antwort ist eine cursor-paginierte Seite: data mit den Datensätzen und pageInfo mit dem Cursor für die nächste.

curl https://api.signido.de/api/v1/documents \
  -H "Authorization: Bearer $SIGNIDO_API_KEY" \
  -H "Accept: application/json"

Von null zur verschickten Unterschrift

Vier Schritte, und einer davon ist unumkehrbar. Ein Signaturauftrag entsteht als Entwurf; Dokumente, Empfänger und Felder kommen über eigene Aufrufe dazu. Erst /send verschickt Einladungen an Fremde und schreibt den Preis fest.

• Dokument anlegen und hochladen. Zwei Aufrufe: der erste beantwortet Tariflimit und Größenobergrenze, der zweite überträgt die Bytes. Eine Ablehnung kostet so einen Roundtrip statt einer vollständigen Übertragung.
• Auftrag als Entwurf erzeugen. Titel, Sprache, gewünschtes Signaturniveau, optional eine Frist.
• Dokument, Empfänger, Felder. Feldkoordinaten sind PDF-Punkte gegen das normalisierte Dokument, Ursprung oben links.
• Prüfen, dann senden. GET /signature-requests/{id} liefert readiness — dieselbe Liste, mit der der Versand ablehnen würde.

import { readFile } from 'node:fs/promises';
import { Signido } from '@signido/sdk';

const signido = new Signido({ apiKey: process.env.SIGNIDO_API_KEY });

// 1. Dokument anlegen und die Bytes hochladen.
const document = await signido.documents.createAndUpload(
  { name: 'Mietvertrag', originalFilename: 'mietvertrag.pdf' },
  {
    file: await readFile('mietvertrag.pdf'),
    filename: 'mietvertrag.pdf',
    contentType: 'application/pdf',
  },
);

// 2. Auftrag als Entwurf erzeugen.
const request = await signido.signatureRequests.create({
  title: 'Mietvertrag Größenweg 3',
  requestedSignatureLevel: 'SES',
});

// 3. Dokument, Empfänger und ein Signaturfeld.
await signido.signatureRequests.attachDocuments(request.id, [document.id]);
const recipient = await signido.signatureRequests.addRecipient(request.id, {
  email: 'mieterin@example.org',
  firstName: 'Anna',
  lastName: 'Berger',
  role: 'SIGNER',
});
await signido.signatureRequests.replaceFields(request.id, [
  {
    documentId: document.id,
    recipientId: recipient.id,
    type: 'SIGNATURE',
    page: 1,
    x: 72,
    y: 640,
    width: 180,
    height: 60,
    required: true,
  },
]);

// 4. Erst prüfen, dann senden. `readiness` ist dieselbe Liste,
//    mit der der Versand ablehnen würde.
const detail = await signido.signatureRequests.get(request.id);
if (detail.readiness.length > 0) {
  throw new Error(detail.readiness.map((problem) => problem.message).join(' '));
}

await signido.signatureRequests.send(request.id, {}, {
  // Ein eigener Schlüssel dedupliziert auch über einen Prozess-Neustart hinweg.
  idempotencyKey: 'mietvertrag-groessenweg-3',
});

Signaturniveau: Wunsch und Nachweis sind zwei Felder

requestedSignatureLevel ist, was der Absender angefordert hat. Was eine Signatur tatsächlich erreicht hat, steht als actualLevel an der Signatur und stammt aus der Validierung — nie aus dem Wunschfeld. Ein Datenbankfeld macht aus einer Signatur keine QES. Oberflächen zeigen deshalb immer den Nachweis, nie den Wunsch.