Gira API v1

Des documents traités directement dans votre système.

Envoyez des fichiers depuis votre ERP et recevez le résultat par webhook. Mêmes outils, limites, antivirus et politiques de confidentialité que le site. Disponible sur Plus et Entreprise.

Créer ma clé Voir les plans

1. Authentification

Créez la clé dans Mon compte, rubrique API Gira. Elle n'est affichée qu'une fois. Envoyez-la à chaque requête :

Authorization: Bearer gira_xxxxxxxx_yyyyyyyyyyyyyyyy

Gardez la clé sur votre serveur (jamais dans le navigateur ou l'application). En cas de fuite, révoquez-la et créez-en une nouvelle.

2. Créer une tâche

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

Réponse 202 : {"job_id": "…", "status": "queued", "status_url": "/v1/jobs/…"}. Les options de l'outil vont dans des champs supplémentaires (par ex. -F texto=CONFIDENCIAL sur watermark-pdf). La liste complète est sur GET /v1/tools.

3. Lots et flux de travail

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]

Chaque fichier passe par toutes les étapes ; avec plusieurs fichiers, le résultat est un .zip. Jusqu'à 20 fichiers sur Plus et 100 sur Entreprise.

Étapes disponibles

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

4. Suivre et télécharger

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

Statut : queued, processing, completed ou failed. Le résultat reste disponible quelques heures (ou selon la politique de conservation de votre entreprise), puis il est supprimé.

5. Webhooks

Quand la tâche se termine, nous envoyons un POST à votre URL (HTTPS uniquement, adresse publique, port 443 ou 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"}

Vérifiez la signature avec le secret webhook de la clé : HMAC-SHA256(segredo, "<t>." + corpo) doit être égal à v1, et rejetez les notifications dont le t date de plus de 5 minutes. Nous réessayons après 1 min, 5 min, 30 min et 2 h si votre URL ne répond pas en 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"])

Limites et erreurs

  • 401 clé invalide ou révoquée · 402 plan sans API · 403 outil hors de votre plan ou bloqué par la politique de l'entreprise
  • 413 fichier au-delà de la limite du plan · 422 fichier bloqué par l'antivirus · 429 trop de requêtes d'affilée
  • L'IA (résumé/traduction) et les outils de mot de passe ne sont pas disponibles via l'API.