Firma.dev

This connector drives Firma.dev (api.firma.dev), a developer-first e-signature API: templates, signing requests (envelopes), their recipients, audit trail and signed documents. 13 tools.

Setup

1. Sign up at https://firma.dev (free, no card) and open your workspace in the dashboard.
2. Copy an API key into FIRMA_API_KEY. Every workspace has two: the test key creates watermarked test requests and consumes no credits, the live key sends real, legally binding requests and consumes one credit per envelope (about €0.049). Start with the test key.
3. The key is sent as the Authorization header, without a Bearer prefix. It is stored encrypted.

A workspace key only sees that workspace's templates and requests. The account's main key (protected workspace) sees the company account too.

The usual flow: a document from a template

1. firma_list_templates (filter by name) and firma_get_template to find the template.
2. firma_list_template_recipients for its recipient slots: each has an id (use it as template_user_id), a designation (Signer, Approver, CC) and an order.
3. firma_create_signing_request_from_template with the real people for those slots. This creates a draft: nothing is emailed and no credit is used.
4. Show the user the draft (name, recipients, emails) and ask for confirmation. Then firma_send_signing_request: this emails every signer and, on a live key, consumes one credit. firma_get_company shows the remaining credits.
5. Track it with firma_get_signing_request (status flags and timestamps), firma_list_signing_request_recipients (who signed, who declined and why, who is still missing fields) and firma_get_signing_request_audit.
6. When it is finished, firma_get_signed_document_url returns a short-lived download URL for the signed PDF.

Rules

• Never send, resend or cancel without the user's explicit go-ahead: these email real people.
• firma_resend_signing_request only reaches recipients who are eligible to sign now (with a signing order, only the current step) and never people who already signed.
• firma_cancel_signing_request works only on sent requests that are not finished or cancelled; set notify_signers to tell them.
• Status values for filtering: not_sent, in_progress, finished, cancelled, declined, expired (comma-separated for several).
• Dates are ISO 8601. Lists are paginated: pagination.total_pages tells you whether to ask for the next page.

Errors: 401 INVALID_API_KEY = wrong or revoked key; 402 or a credits message = the account needs credits (or use the test key); 429 = rate limit (200 reads and 120 writes per minute per key), wait for Retry-After.