Setzt ein Unterschriftsbild an eine wählbare Stelle in ein PDF — optional mit Name und Datum darunter. Verarbeitung in Deutschland, in-memory, keine Speicherung.
POSThttps://sign.bloc-apps.com/api/v1/run
Header Authorization: Bearer blk_live_…. Keys erstellst du im Dashboard. Ein Key lässt sich auf dieses eine Tool beschränken und mit einem eigenen Monats-Limit versehen.
Sende einen Idempotency-Key mit. Er steht für genau einen Vorgang.
Wird derselbe Schlüssel ein zweites Mal gesendet, antwortet die API mit 409 und führt die Verarbeitung nicht erneut aus. So kann dieselbe Anfrage weder doppelt abgerechnet noch — durch Wiederverwendung des Schlüssels — kostenlos wiederholt werden.
Für jeden neuen Vorgang einen neuen Schlüssel senden (etwa crypto.randomUUID()). Ohne Header erzeugen wir selbst einen. Wir speichern keine Ergebnisse — eine verlorene Antwort lässt sich deshalb nicht nachträglich abholen.
Alle Parameter werden als Query-String an die URL gehängt.
| Name | Werte | Standard | Bedeutung |
|---|---|---|---|
signature_urlPflicht | string (https) | — | Öffentliche https-URL des Unterschriftsbildes (PNG mit Transparenz empfohlen, oder JPEG). Über MCP alternativ signature_base64. |
page | 1-basiert · „last“ | last | Zielseite. Eine Seite außerhalb des PDF wird abgelehnt. |
x | 0–100 | 60 | X-Position in % der Seitenbreite, Ursprung unten links. |
y | 0–100 | 10 | Y-Position in % der Seitenhöhe, Ursprung unten links. |
width | 1–80 | 25 | Breite in % der Seitenbreite; die Höhe folgt dem Seitenverhältnis des Bildes. |
opacity | 0.1–1.0 | 1.0 | Deckkraft der Unterschrift. |
date | true · false | false | Heutiges Datum (TT.MM.JJJJ) unter die Unterschrift setzen. |
date_text | string | — | Datum überschreiben, z. B. 01.01.2026 (statt heute). |
label | string | — | Text unter der Unterschrift, z. B. Name (max. 120 Zeichen, nur Latin-1/WinAnsi — Umlaute gehen, Emoji nicht). |
Jede erfolgreiche Antwort sagt, was sie verbraucht hat:
X-Bloc-Ops — verbrauchte Kontingent-Einheiten dieser Anfrage (bei einem Bild: 1)X-Bloc-Overage-Ops — davon über dem Monatskontingent (0, solange Kontingent übrig ist)X-Bloc-Source — included (im Kontingent) · overage (auf die Monatsrechnung) · free (im Browser, kostenlos)401 | API-Key fehlt, ist ungültig oder wurde widerrufen |
402 | Monatskontingent des Plans (oder das Limit dieses Keys) erreicht |
409 | Idempotency-Key wurde schon verwendet — der Vorgang lief bereits |
413 | Datei zu groß (Bytes oder Pixel/Seiten) |
415 | Dateiformat wird nicht unterstützt |
429 | Rate-Limit je API-Key — je nach Plan 20 bis 120 Anfragen pro Minute |
502 / 504 | Verarbeitung fehlgeschlagen oder Zeitüberschreitung |
400 | ungültige Eingabe: signature_url fehlt, Seite außerhalb des PDF, Name über 120 Zeichen oder mit nicht darstellbaren Zeichen (Emoji), passwortgeschütztes PDF |
413 | PDF über 25 MB / 500 Seiten oder Unterschrift über 5 MB |
415 | PDF oder Unterschriftsbild nicht lesbar |
Der Body enthält immer error (Maschinen-Code) und message (deutscher Klartext).
curl -X POST "https://sign.bloc-apps.com/api/v1/run?page=last&x=60&y=10&width=25&signature_url=https://deine-domain.de/unterschrift.png" \
-H "Authorization: Bearer blk_live_DEIN_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
--data-binary "@vertrag.pdf" \
--output ergebnisconst res = await fetch("https://sign.bloc-apps.com/api/v1/run?page=last&x=60&y=10&width=25&signature_url=https://deine-domain.de/unterschrift.png", {
method: "POST",
headers: {
Authorization: "Bearer blk_live_DEIN_KEY",
"Content-Type": file.type,
// Ein neuer Schlüssel pro Vorgang. Derselbe Schlüssel zweimal → 409.
"Idempotency-Key": crypto.randomUUID(),
},
body: file,
});
if (res.status === 402) throw new Error("Monatskontingent aufgebraucht");
if (!res.ok) throw new Error((await res.json()).message);
console.log("verbraucht:", res.headers.get("X-Bloc-Ops"), "Operation(en)");
const ergebnis = await res.blob();BlocSign ist auch über den Bloc-Apps-MCP-Server nutzbar. Claude und andere Assistenten rufen es dann selbst auf — über dasselbe Konto und Kontingent. Einrichtung im Dashboard unter „API & KI“.
blocsign_place_signatureSetzt ein Unterschriftsbild an eine wählbare Stelle in ein PDF — der bequeme Weg, weil PDF und Unterschrift beide als Base64 oder URL gehen. Einfache elektronische Signatur nach eIDAS Art. 3 Nr. 10, keine qualifizierte (QES).
Eingabe
pdf_base64 (string) — PDF als Base64 (ohne data:-Präfix).pdf_url (string) — Alternativ: öffentliche https-URL des PDF (Weg für Dateien über 4,5 MB).signature_base64 (string) — Unterschriftsbild als Base64 (PNG mit Alpha empfohlen).signature_url (string) — Alternativ: öffentliche https-URL des Unterschriftsbildes.page (integer | string) — Zielseite, 1-basiert, oder „last“ (Standard).x (number) — X-Position in % (0–100, Standard 60), Ursprung unten links.y (number) — Y-Position in % (0–100, Standard 10), Ursprung unten links.width (number) — Breite in % (1–80, Standard 25); Höhe folgt dem Seitenverhältnis.opacity (number) — Deckkraft 0.1–1.0 (Standard 1.0).date (boolean) — Heutiges Datum (TT.MM.JJJJ) darunter setzen (Standard false).date_text (string) — Datum überschreiben, z. B. 01.01.2026.label (string) — Name darunter (max. 120 Zeichen, nur WinAnsi).Rückgabe
{ pdf_base64, page_count, signed_page } plus charged_cents, source, balance_after_cents. signed_page ist 0-basiert.