Gira API v1

Dokumente direkt in Ihrem System verarbeitet.

Senden Sie Dateien aus Ihrem ERP und erhalten Sie das Ergebnis per Webhook. Dieselben Tools, Limits, Virenscanner und Datenschutzrichtlinien wie auf der Website. Verfügbar in Plus und Business.

Meinen Schlüssel erstellen Tarife ansehen

1. Authentifizierung

Erstellen Sie den Schlüssel unter Mein Konto im Bereich Gira-API. Er wird nur einmal angezeigt. Senden Sie ihn mit jeder Anfrage:

Authorization: Bearer gira_xxxxxxxx_yyyyyyyyyyyyyyyy

Bewahren Sie den Schlüssel auf Ihrem Server auf (nie im Browser oder in der App). Wird er bekannt, widerrufen Sie ihn und erstellen Sie einen neuen.

2. Auftrag erstellen

curl -X POST https://girapdf.com.br/v1/jobs \
  -H "Authorization: Bearer $GIRA_KEY" \
  -F operation=compress-pdf \
  -F [email protected] \
  -F webhook_url=https://erp.suaempresa.com.br/webhooks/gira

Antwort 202: {"job_id": "…", "status": "queued", "status_url": "/v1/jobs/…"}. Tool-Optionen gehen als zusätzliche Felder mit (z. B. -F texto=CONFIDENCIAL bei watermark-pdf). Die vollständige Liste finden Sie unter GET /v1/tools.

3. Stapel und Workflows

curl -X POST https://girapdf.com.br/v1/pipelines \
  -H "Authorization: Bearer $GIRA_KEY" \
  -F 'etapas=[{"operation":"xlsx-to-pdf"},{"operation":"compress-pdf"},{"operation":"watermark-pdf","options":{"texto":"INTERNO"}}]' \
  -F [email protected] -F [email protected] -F [email protected]

Jede Datei durchläuft alle Schritte; bei mehreren Dateien ist das Ergebnis ein .zip. Bis zu 20 Dateien bei Plus und 100 bei Business.

Verfügbare Schritte

docx-to-pdf (.docx in .pdf) · xlsx-to-pdf (.xlsx, .xls, .ods in .pdf) · pptx-to-pdf (.pptx, .ppt, .odp in .pdf) · html-to-pdf (.html, .htm in .pdf) · jpg-to-pdf (.jpg, .jpeg, .png, .webp in .pdf) · csv-to-xlsx (.csv in .xlsx) · ocr-pdf (.pdf in .pdf) · compress-pdf (.pdf in .pdf) · optimize-images (.pdf in .pdf) · repair-pdf (.pdf in .pdf) · rotate-pdf (.pdf in .pdf) · grayscale-pdf (.pdf in .pdf) · page-numbers (.pdf in .pdf) · watermark-pdf (.pdf in .pdf) · header-footer (.pdf in .pdf) · bates-numbering (.pdf in .pdf) · stamp-pdf (.pdf in .pdf) · resize-pdf (.pdf in .pdf) · flatten-pdf (.pdf in .pdf) · clean-pdf (.pdf in .pdf) · pdf-to-pdfa (.pdf in .pdf) · pdf-to-docx (.pdf in .docx) · pdf-to-xlsx (.pdf in .xlsx) · pdf-to-pptx (.pdf in .pptx) · pdf-to-text (.pdf in .txt) · pdf-to-markdown (.pdf in .md) · pdf-to-jpg (.pdf in .zip) · xlsx-to-csv (.xlsx in .csv)

4. Verfolgen und herunterladen

curl -H "Authorization: Bearer $GIRA_KEY" https://girapdf.com.br/v1/jobs/JOB_ID
curl -H "Authorization: Bearer $GIRA_KEY" -o resultado.pdf https://girapdf.com.br/v1/jobs/JOB_ID/download

Status: queued, processing, completed oder failed. Das Ergebnis bleibt einige Stunden verfügbar (oder gemäß der Aufbewahrungsrichtlinie Ihrer Firma) und wird dann gelöscht.

5. Webhooks

Wenn der Auftrag fertig ist, senden wir einen POST an Ihre URL (nur HTTPS, öffentliche Adresse, Port 443 oder 8443):

X-Gira-Event: job.completed
X-Gira-Signature: t=1696350000,v1=5f2c…

{"event": "job.completed", "job_id": "…", "operation": "compress-pdf", "status": "completed",
 "output_filename": "nota-fiscal.pdf", "output_size": 482113, "download_url": "/v1/jobs/…/download"}

Prüfen Sie die Signatur mit dem Webhook-Secret des Schlüssels: HMAC-SHA256(segredo, "<t>." + corpo) muss v1 entsprechen, und lehnen Sie Benachrichtigungen ab, deren t älter als 5 Minuten ist. Wir versuchen es nach 1 Min., 5 Min., 30 Min. und 2 Std. erneut, wenn Ihre URL nicht mit 2xx antwortet.

# Python
import hmac, hashlib, time
def assinatura_valida(segredo, cabecalho, corpo: bytes):
    partes = dict(p.split("=", 1) for p in cabecalho.split(","))
    if abs(time.time() - int(partes["t"])) > 300:
        return False
    esperado = hmac.new(segredo.encode(), f'{partes["t"]}.'.encode() + corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, partes["v1"])

Limits und Fehler

  • 401 ungültiger oder widerrufener Schlüssel · 402 Tarif ohne API · 403 Tool nicht in Ihrem Tarif oder durch Firmenrichtlinie gesperrt
  • 413 Datei überschreitet das Tariflimit · 422 Datei vom Virenscanner blockiert · 429 zu viele Anfragen hintereinander
  • KI (Zusammenfassung/Übersetzung) und Passwort-Tools sind über die API nicht verfügbar.