Gira API v1

Documentos resolvidos dentro do seu sistema.

Envie arquivos do seu ERP, receba o resultado por webhook. Mesmas ferramentas, limites, antivírus e políticas de privacidade do site. Disponível no Plus e no Empresarial.

Criar minha chave Ver planos

1. Autenticação

Crie a chave em Minha conta, na seção Gira API. Ela aparece uma vez só. Envie em todo pedido:

Authorization: Bearer gira_xxxxxxxx_yyyyyyyyyyyyyyyy

Guarde a chave no servidor (nunca no navegador ou no app). Se vazar, revogue e crie outra.

2. Criar um 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

Resposta 202: {"job_id": "…", "status": "queued", "status_url": "/v1/jobs/…"}. Opções da ferramenta vão como campos extras (ex.: -F texto=CONFIDENCIAL no watermark-pdf). A lista completa está em GET /v1/tools.

3. Lote e fluxos

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 arquivo passa por todas as etapas; com mais de um arquivo o resultado é um .zip. Até 20 arquivos no Plus e 100 no Empresarial.

Etapas disponíveis

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

4. Acompanhar e baixar

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 ou failed. O resultado fica disponível por algumas horas (ou conforme a política de retenção da sua empresa) e depois é apagado.

5. Webhooks

Quando o job termina, enviamos um POST para a sua URL (somente HTTPS, endereço público, porta 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"}

Confira a assinatura com o segredo de webhook da chave: HMAC-SHA256(segredo, "<t>." + corpo) deve ser igual a v1, e recuse avisos com t de mais de 5 minutos. Tentamos de novo em 1 min, 5 min, 30 min e 2 h se sua URL não responder 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 e erros

  • 401 chave inválida ou revogada · 402 plano sem API · 403 ferramenta fora do plano ou bloqueada pela política da empresa
  • 413 arquivo acima do limite do plano · 422 arquivo bloqueado pelo antivírus · 429 muitos pedidos seguidos
  • IA (resumo/tradução) e ferramentas com senha não estão disponíveis pela API.