=== Firma.dev – E-Signature & Document Signing ===
Contributors: firmadev
Tags: esignature, electronic signature, docusign alternative, contracts, woocommerce
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Send any document for e-signature from WordPress using Firma.dev. Pay-as-you-go pricing, no subscriptions, works with any plugin.

== Description ==

Firma.dev brings e-signature to any WordPress site: send a contract, waiver, or agreement for signature from a page, a form submission, or your own custom code, and track its status without leaving wp-admin.

Unlike most e-signature plugins, Firma.dev for WordPress isn't tied to one form builder or one workflow. It's built around a single, universal way to trigger a signature request, so it works with whatever you're already running.

**How it works**

1. Create your contract or document template in your Firma.dev dashboard (a free account takes a minute to set up).
2. For a one-off document to someone with no WordPress record, an outside vendor, a one-off client, use Firma → Send a Document: pick the template, type in who needs to sign, send.
3. For a document you'll send repeatedly to people who already have data in WordPress, customers, form entries, logged-in users, use Firma → Send Setup once to map the template's fields to that data.
4. Drop the `[firma_send_signature]` shortcode anywhere, or trigger it from any other plugin or custom code with a single WordPress action hook. Every send after that is automatic.
5. Track every sent document's status (Sent, Viewed, Completed, Declined) under Firma → Documents.

**Works with anything**

Every trigger in this plugin, including the shortcode, funnels through one action hook:

`do_action( 'firma_send_document', $mapping_id, $context );`

Any other plugin or custom theme code can fire this to send a document for signature. Firma.dev isn't limited to the integrations we've built, it works with your specific setup, out of the box.

**Why Firma.dev**

* Pay-as-you-go pricing (roughly €0.049 / ~5¢ per envelope), no monthly minimums, no per-seat fees. Send one document a year or ten thousand, you only pay for what you use.
* Legally valid e-signatures in 55+ countries.
* Built for developers and agencies as much as everyday site owners.

Firma.dev is a hosted service. A Firma.dev account is free to create and includes a no-cost test API key, so you can wire everything up and send a real test document before you commit to anything. Once you recieve your live key, you're ready to send for real.

Get started with Firma.dev for free, no credit card required: https://www.firma.dev

== Installation ==

1. Upload the plugin files, or install directly from the WordPress Plugin Directory.
2. Activate the plugin. You'll be taken straight to Firma → Settings.
3. Enter your Firma.dev API key.
4. For a one-off document, go to Firma → Send a Document. For a recurring, automated send, go to Firma → Send Setup, choose a template, and map its fields.
5. Add the `[firma_send_signature mapping="ID"]` shortcode to any page, or use the `firma_send_document` action from your own code.

== Frequently Asked Questions ==

= Do I need a Firma.dev account? =

Yes. Templates are created and managed in your Firma.dev dashboard; this plugin sends documents for signature using your account's API key. A free account includes a test API key that doesn't consume credits.

= Does this only work with WooCommerce / a specific form plugin? =

No. The core plugin works on any page via the shortcode, and exposes a `firma_send_document` action hook that any other plugin or custom code can call. Dedicated integrations for WooCommerce, Gravity Forms, WPForms, and Contact Form 7 are planned as fast-follow releases.

= What happens to my data if I uninstall the plugin? =

Nothing is deleted unless you check "Delete all Firma.dev mappings and document records" on the Settings page before removing the plugin. Deactivating never deletes data.

= Is my API key stored securely? =

Your API key and webhook secret are encrypted at rest in the WordPress database. This protects against someone reading your database directly; as with any plugin, it does not protect against a fully compromised server.

== External services ==

This plugin connects to the Firma.dev API (https://api.firma.dev) to send documents for e-signature and track their status. A Firma.dev account and API key are required for the plugin to function. This is a core, required part of what the plugin does, not an optional add-on.

What is sent, and when:

* When a document is sent (via the shortcode or the `firma_send_document` action), the plugin sends the signer's name and email address, plus any WordPress data you've chosen to map into template fields, to Firma.dev's API to create and deliver the signing request.
* Every API request includes your Firma.dev API key for authentication.
* Firma.dev sends status updates (viewed, signed, declined, etc.) back to this site via a webhook you configure, so the plugin does not need to repeatedly poll Firma.dev for status.

This service is provided by Firma.dev: [Terms of Service](https://firma.dev/legal/terms-conditions), [Privacy Policy](https://firma.dev/legal/privacy-policy).

== Screenshots ==

1. Firma → Send a Document: send a one-off document to anyone, no setup required.
2. Firma → Documents: track every sent envelope and its status.
3. Firma → Send Setup: map a Firma.dev template to WordPress data with dropdowns, no code required.
4. Firma → Settings: connect your API key and webhook.

== Changelog ==

= 1.0.1 =
* Added Firma → Send a Document, a one-off send screen for recipients with no WordPress record. No mapping required.
* Documents and Send Setup now show template names instead of raw template IDs.
* Send Setup now tells apart "no template selected" from "template has no signer roles or fields to map."
* Documents page reminds you to add a webhook secret when status auto-updates aren't set up yet.
* API error messages now lead with a plain-language summary ahead of the technical detail.
* First activation now goes straight to Settings.
* Saved Mappings list shows how many documents each mapping has actually sent, so unused test mappings are easy to spot before deleting.

= 1.0.0 =
* Initial release: settings, template-based send mapping, shortcode, `firma_send_document` action hook, webhook-driven status tracking, Documents list.

== Upgrade Notice ==

= 1.0.1 =
Adds a one-off "Send a Document" screen and several UX clarity fixes. No settings or mappings are affected by upgrading.

= 1.0.0 =
Initial release.
