Gira API v1

Documents handled right inside your system.

Send files from your ERP and get the result by webhook. Same tools, limits, antivirus and privacy policies as the website. Available on Plus and Business.

Create my key See plans

1. Authentication

Create the key in My account, under Gira API. It is shown only once. Send it with every request:

Authorization: Bearer gira_xxxxxxxx_yyyyyyyyyyyyyyyy

Keep the key on your server (never in the browser or app). If it leaks, revoke it and create a new one.

2. Create a job

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

Response 202: {"job_id": "…", "status": "queued", "status_url": "/v1/jobs/…"}. Tool options go as extra fields (e.g., -F texto=CONFIDENCIAL on watermark-pdf). The full list is at GET /v1/tools.

3. Batches and 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]

Each file goes through every step; with more than one file, the result is a .zip. Up to 20 files on Plus and 100 on Business.

Available steps

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

4. Track and download

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 or failed. The result stays available for a few hours (or according to your company's retention policy) and is then deleted.

5. Webhooks

When the job finishes, we send a POST to your URL (HTTPS only, public address, port 443 or 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"}

Verify the signature with the key's webhook secret: HMAC-SHA256(segredo, "<t>." + corpo) must equal v1, and reject notifications with a t older than 5 minutes. We retry after 1 min, 5 min, 30 min and 2 h if your URL doesn't respond with 2xx.

# 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 and errors

  • 401 invalid or revoked key · 402 plan without API · 403 tool not in your plan or blocked by company policy
  • 413 file exceeds plan limit · 422 file blocked by antivirus · 429 too many requests in a row
  • AI (summary/translation) and password tools are not available through the API.