Gira API v1

Documentos resueltos dentro de tu sistema.

Envía archivos desde tu ERP y recibe el resultado por webhook. Las mismas herramientas, límites, antivirus y políticas de privacidad del sitio. Disponible en Plus y Empresarial.

Crear mi clave Ver planes

1. Autenticación

Crea la clave en Mi cuenta, en la sección Gira API. Aparece una sola vez. Envíala en cada solicitud:

Authorization: Bearer gira_xxxxxxxx_yyyyyyyyyyyyyyyy

Guarda la clave en el servidor (nunca en el navegador ni en la app). Si se filtra, revócala y crea otra.

2. Crear un 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

Respuesta 202: {"job_id": "…", "status": "queued", "status_url": "/v1/jobs/…"}. Las opciones de la herramienta van como campos extra (ej.: -F texto=CONFIDENCIAL en watermark-pdf). La lista completa está en GET /v1/tools.

3. Lotes y flujos

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]

Cada archivo pasa por todos los pasos; con más de un archivo, el resultado es un .zip. Hasta 20 archivos en Plus y 100 en Empresarial.

Pasos disponibles

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

4. Seguimiento y descarga

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

Estado: queued, processing, completed o failed. El resultado queda disponible durante algunas horas (o según la política de retención de tu empresa) y luego se borra.

5. Webhooks

Cuando el job termina, enviamos un POST a tu URL (solo HTTPS, dirección pública, puerto 443 u 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 el secreto de webhook de la clave: HMAC-SHA256(segredo, "<t>." + corpo) debe ser igual a v1, y rechaza los avisos con t de más de 5 minutos. Reintentamos a los 1 min, 5 min, 30 min y 2 h si tu URL no responde 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"])

Límites y errores

  • 401 clave inválida o revocada · 402 plan sin API · 403 herramienta fuera del plan o bloqueada por la política de la empresa
  • 413 archivo por encima del límite del plan · 422 archivo bloqueado por el antivirus · 429 demasiadas solicitudes seguidas
  • La IA (resumen/traducción) y las herramientas con contraseña no están disponibles a través de la API.