foolscap-sdk

SDK Python oficial do Foolscap — geração de documentos: template + JSON → PDF, direto da sua aplicação.

pip install foolscap-sdk

from foolscap_sdk import Foolscap

client = Foolscap(api_key="fsk_...")  # crie a key no painel, seção API Keys

doc = client.render(
    template_id="tpl_...",
    data={"contratante": {"nome": "Maria Silva"}},
    document_name="Contrato — Maria Silva",
)
print(doc.pdf_url)  # PDF pronto, URL assinada

render() cuida do ciclo assíncrono inteiro (a API responde 202 e o SDK acompanha até o documento ficar pronto — segundos). Retry de rede é seguro por padrão: todo render envia uma chave de idempotência, então reenvio nunca duplica documento.

Controle fino

accepted = client.render_nowait(template_id="tpl_...", data={...})
# ... sua fila, seu ritmo ...
doc = client.wait_for_document(accepted.document_id)  # ou get_document(), 1 consulta seca
pdf_bytes = client.download_pdf(doc.id)

Descoberta e histórico

for template in client.list_templates():
    print(template.id, template.name, template.sample_data)  # sample_data = contrato do `data`

for doc in client.iter_documents():  # paginação automática
    print(doc.created_at, doc.name, doc.status)

conta = client.account()
print(conta.plan, conta.usage.documents, "/", conta.usage.limit)

Erros

Tudo herda de FoolscapError:

from foolscap_sdk import FoolscapError, QuotaExceededError, TemplateRenderError

try:
    doc = client.render(template_id="tpl_...", data=dados)
except TemplateRenderError as e:
    print("variável faltando ou template inválido:", e.detail)
except QuotaExceededError:
    print("cota do mês esgotada — hora do upgrade :)")
except FoolscapError as e:
    print("qualquer outra falha do SDK/API:", e)

Referências

• Guia de integração: https://foolscap.app.br/guia
• Referência completa da API: https://api.foolscap.app.br/docs

Python ≥ 3.10 · tipagem completa · dependência única (httpx2) · MIT