Gira API v1

Documenti gestiti direttamente nel tuo sistema.

Invia file dal tuo ERP e ricevi il risultato via webhook. Stessi strumenti, limiti, antivirus e policy sulla privacy del sito. Disponibile su Plus e Business.

Crea la mia chiave Vedi i piani

1. Autenticazione

Crea la chiave in Il mio account, nella sezione API Gira. Viene mostrata una sola volta. Inviala in ogni richiesta:

Authorization: Bearer gira_xxxxxxxx_yyyyyyyyyyyyyyyy

Conserva la chiave sul tuo server (mai nel browser o nell'app). Se viene esposta, revocala e creane una nuova.

2. Crea un'attività

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

Risposta 202: {"job_id": "…", "status": "queued", "status_url": "/v1/jobs/…"}. Le opzioni dello strumento vanno come campi extra (es. -F texto=CONFIDENCIAL in watermark-pdf). L'elenco completo è in GET /v1/tools.

3. Lotti e flussi di lavoro

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]

Ogni file passa per tutti i passaggi; con più file, il risultato è un .zip. Fino a 20 file su Plus e 100 su Business.

Passaggi disponibili

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

4. Monitora e scarica

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

Stato: queued, processing, completed o failed. Il risultato resta disponibile per alcune ore (o secondo la policy di conservazione della tua azienda) e poi viene eliminato.

5. Webhook

Quando l'attività termina, inviamo un POST al tuo URL (solo HTTPS, indirizzo pubblico, porta 443 o 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"}

Verifica la firma con il secret webhook della chiave: HMAC-SHA256(segredo, "<t>." + corpo) deve essere uguale a v1, e rifiuta le notifiche con un t più vecchio di 5 minuti. Riproviamo dopo 1 min, 5 min, 30 min e 2 h se il tuo URL non risponde con 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"])

Limiti ed errori

  • 401 chiave non valida o revocata · 402 piano senza API · 403 strumento non incluso nel tuo piano o bloccato dalla policy aziendale
  • 413 file oltre il limite del piano · 422 file bloccato dall'antivirus · 429 troppe richieste di fila
  • L'IA (riassunto/traduzione) e gli strumenti per password non sono disponibili tramite API.