# Advanced Electronic Signature

> What Advanced Electronic Signature (FEA) adds on top of the general Legaldoc.io v2 API flow, and how to orchestrate it.

This chapter explains how to integrate Advanced Electronic Signature (FEA) into your application: what you build, what Legaldoc does, and what you ultimately deliver to your user. It builds on the general flow you already saw in the [Integration Guide](/en/guides/integration-guide/) — creating an envelope, adding recipients and fields, distributing it — and describes what changes when that envelope needs FEA.

If you've never created a document with the API, start with the [Integration Guide](/en/guides/integration-guide/). This chapter assumes you already know how to create an envelope, add recipients and fields, and distribute it.

---

## 1. What FEA is and what changes

Advanced Electronic Signature certifies the signer's identity against an authorized certification authority, using their national ID (RUT) as credential. Unlike simple signing, the signer must verify their identity and confirm with a second factor before the signature is applied.

For your integration, this means three concrete differences from a normal envelope:

- The signer needs a **valid national ID (RUT)**.
- The **signing order must be sequential**, even with a single signer.
- Each signer has **exactly one signature field**.

The rest of the lifecycle —create, distribute, monitor, complete— is the same as any document. Document preparation (section 3 of the Integration Guide) also applies the same way: with FEA, even more so, the PDF must be in its final version before creating the envelope.

---

## 2. Create the envelope and recipients

On top of the general example, an envelope with FEA adds the signer's RUT and forces sequential order:

```jsonc
{
  "type": "DOCUMENT",
  "globalActionAuth": ["FAO_HASH"],
  "recipients": [
    {
      "name": "Recipient name",
      "email": "recipient@example.com",
      "rut": "12345678-9",
      "role": "SIGNER",
      "signingOrder": 1
    }
  ],
  "meta": {
    "signingOrder": "SEQUENTIAL"
  }
}
```

### The name you send vs. the verified name

The `name` field you send is informational: it identifies the recipient for email delivery and display in your own interface. **It's not the legal identity of the signature.**

When the signer completes verification with their certification authority, Legaldoc obtains the full name associated with that RUT, and that is the one stamped on the document and on the signing certificate. If the name you sent differs from the verified one, the signing certificate shows both, so it's explicit which is which.

<Aside type="tip" title="What to do">
	Don't assume the name visible on the final document is the same one you sent. If your application needs to show "who signed" after the fact, check the signing certificate ([section 4](#4-delivering-the-evidence)) instead of your own record.
</Aside>

### Validations that happen at distribution time

Legaldoc validates FEA rules (RUT, sequential order, one field per signer, allowed roles) at the moment you **distribute** the envelope, not when you create it. If your integration builds the envelope over several steps, verify these conditions in your own code before attempting to distribute, so you can give your user an early, clear error instead of a late one.

### Signature field placement

The [Integration Guide](/en/guides/integration-guide/#2-add-signature-fields) explains the two ways to specify where a field goes: placeholder or coordinates. With FEA, the risk of using coordinates is different —and lower— thanks to the same distribution-time validation mentioned above.

In a standard envelope, an invalid `page` in a coordinates call doesn't fail until the document is sealed, with the signer having already signed. With FEA, Legaldoc prepares the complete document —watermark, QR code, and the signature fields already placed— at the moment of `POST /envelope/distribute`, not when sealing. If a coordinate doesn't fit, `distribute` fails right there, still with no signers. It's still an avoidable error —the placeholder eliminates it before you even reach distribution— but if your PDF is fixed and you've already measured the position by hand, using coordinates in FEA doesn't carry the catastrophic risk it does in the standard flow.

One FEA-specific detail: remember that each signer must have **exactly one** signature field (section 1). If you use `matchAll: true` with a placeholder that appears more than once in the document, a field gets created for every occurrence — avoid `matchAll` in FEA unless the placeholder appears exactly once per signer.

---

## 3. The signing experience

Once distributed, redirect your user to the signing URL returned by the API (`recipients[].signingUrl`), same as the general flow.

From there, **the entire identity verification and confirmation process happens within the Legaldoc page**: enrollment with the certification authority (if it's the first time) and the second authentication factor. Your application doesn't participate in that exchange and doesn't need to build any screen for it.

If your user closes the browser before completing enrollment or signing, the envelope stays `PENDING` and they can resume it by returning to the same signing URL, if it's still valid, or by requesting that you resend the notification.

---

## 4. Delivering the evidence

When the envelope is `COMPLETED`, with FEA there are three artifacts available, not one:

| Artifact | Endpoint | Content |
|---|---|---|
| Signed document | `GET /envelope/item/{envelopeItemId}/download?version=signed` | The PDF with the applied signatures. |
| Signing certificate | `GET /envelope/{envelopeId}/certificate/download` | Who signed, with what verified identity, when, and with what authentication level. |
| Audit log | `GET /envelope/{envelopeId}/audit-log/download` | The complete trace of process events (sending, viewing, signing, completion). |

### Why they're separate files

In a simple signing flow, the certificate and audit log can be appended as additional pages of the same PDF, because they're added before any signature exists.

With FEA that's not possible: the certificate describes information that only exists **after** the signer signed (their verified identity, the exact time). There's no way to append it to the document without effectively invalidating the signature that was already applied.

<Aside type="tip" title="What to do">
	Offer all three as independent downloads in your interface. Don't try to combine them into a single file. The signed document is your primary deliverable; the certificate and audit log are its backing evidence, and it's worth presenting them as such —for example, as secondary actions next to the main download.
</Aside>

If you need the audit log as data instead of PDF (to integrate it into your own system instead of displaying it), it's also available as JSON at `GET /envelope/{envelopeId}/audit-log`.

---

## 5. Rejection

A signer can reject the document instead of signing it. When that happens:

- The envelope moves to `REJECTED` status.
- You receive the `DOCUMENT_REJECTED` event via webhook.
- The document and the signing certificate (if applicable) remain available reflecting the rejection and its reason.

If the rejection happens before any signature exists, there's no signature evidence to preserve. If it happens after another signer already signed (in a multi-signer flow), that prior signature is preserved intact as part of the document's history.

---

## 6. Endpoint summary

In addition to the general endpoints (create, add fields, distribute, check status — see the [Integration Guide](/en/guides/integration-guide/#10-endpoint-summary)), FEA adds downloading the certificate and audit log:

| Action | Endpoint |
|---|---|
| Download signing certificate | `GET /envelope/{envelopeId}/certificate/download` |
| Download audit log (PDF) | `GET /envelope/{envelopeId}/audit-log/download` |
| Get audit log (JSON) | `GET /envelope/{envelopeId}/audit-log` |

---

## Common errors

| Situation | Common cause |
|---|---|
| Distribution fails with a validation error | A signer is missing their RUT, the signing order isn't sequential, or a signer has more than one signature field. |
| Downloading the certificate or audit log returns an error | The envelope isn't in `COMPLETED` status yet. |
| The name on the document doesn't match what I sent | Expected: the document and certificate show the verified identity, not the one sent. See [section 2](#2-create-the-envelope-and-recipients). |