> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/digital-signatures/signer.md).

# Signer

This service executes the full digital signature Flow and returns a response `202 Accepted` immediately. The service processes the signing operation in an **asynchronous**.

Implements Basic Electronic Signature (AdES - BES), providing a robust and reliable solution with significant advantages in regulatory compliance, security, interoperability, and ease of use.

#### Asynchronous callback

When the operation is completed — whether successful or failed — the service sends a POST request to the URL specified in the parameter `callbackUrl`. If `callbackHeaders`, these will be included in the callback request.

* **Successful signature**: Content-Type `multipart/form-data`. Returns the signed PDF document as an attachment.
* **Failed signature**: Content-Type `application/json`. Returns an error object with `operationId` and message of `error`.

{% hint style="warning" %}
Only image formats **JPEG** and **PNG** are supported for signature display. Other formats will result in an error.
{% endhint %}

{% hint style="info" %}
**Security recommendation:** Always consume this API from your backend infrastructure instead of frontend applications. This approach protects sensitive data, prevents credential exposure, and ensures secure handling of documents throughout the signing process.
{% endhint %}

### Endpoint

```
POST /signer
```

### Headers

| Name          | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| **x-api-key** | string | **Yes**  | Access authorization API Key. |

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter         | Type      | Required | Description                                                                                                                                                                                                                                      |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `document`        | string    | **Yes**  | PDF document to be digitally signed, encoded in format **Base64** (RFC4648).                                                                                                                                                                     |
| `images`          | string\[] | No       | Array of signature display images to embed in the document. Each image must be encoded in **Base64**. Supported formats: **JPEG**, **PNG**.                                                                                                      |
| `image`           | string    | No       | **Deprecated.** Use the array `images` instead. Single image to embed as signature display, encoded in **Base64**.                                                                                                                               |
| `page`            | integer   | No       | Target page number for placing the signature, zero-indexed. **Default value:** `0` (first page).                                                                                                                                                 |
| `position`        | string    | No       | Signature rectangle coordinates in pixels at 72 DPI: lower-left X, lower-left Y, upper-right X, upper-right Y. For A4 pages, valid ranges: X: 0-595, Y: 0-842. Format: `x1,y1,x2,y2`. **Default value:** `"135,210,480,300"`                     |
| `timezone`        | string    | No       | IANA time zone identifier for the date/time format in signature metadata. Examples: `America/Lima`, `Europe/Madrid`, `Asia/Tokyo`. **Default value:** `"UTC"`                                                                                    |
| `signature`       | string\[] | No       | Custom text lines to display alongside the signature image. Supports dynamic placeholders: `$(date)s` is replaced with the current timestamp formatted according to `dateFormat` and `timezone`. Each array element represents one line of text. |
| `dateFormat`      | string    | No       | Date/time format string following the ISO 8601 standard with strftime directives. Supports `%z` for time zone offset. Example: `%d/%m/%Y %H:%M:%S%z`. **Default value:** `"%Y/%m/%d %H:%M:%S%z"`                                                 |
| `callbackUrl`     | string    | **Yes**  | Webhook URL to receive the signed document or error notification. The service will send the results by POST to this Endpoint asynchronously.                                                                                                     |
| `callbackHeaders` | string    | No       | Optional HTTP headers to include in the callback request. Format: key=value pairs separated by semicolons. Example: `Authorization=Bearer token;X-Custom=value`                                                                                  |

#### Request example

```json
{
  "document": "JVBERi0xLjUKJbXtrvsKNCAwIG9iag...",
  "images": ["iVBORw0KGgoAAAANSUhEUgAAAEoAAABK..."],
  "page": 0,
  "position": "135,210,480,300",
  "timezone": "America/Lima",
  "signature": ["ID - 9999999", "Date - $(date)s"],
  "dateFormat": "%d/%m/%Y %H:%M:%S%z",
  "callbackUrl": "https://example.com/callback",
  "callbackHeaders": "Authorization=Bearer token123;Content-Type=application/json"
}
```

### Responses

#### `202` Accepted

The request was accepted and the signing operation is being processed asynchronously. The result will be sent to the provided callback URL.

#### Callback — Successful signature

Content-Type: `multipart/form-data`

The signed PDF document is returned as an attachment.

#### Callback — Failed signature

Content-Type: `application/json`

```json
{
  "operationId": "910e181e-305c-4d9b-b42b-f177bf3b06ef",
  "error": "image: formato desconocido"
}
```

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

```json
{
  "message": "Unauthorized"
}
```

#### `403` Forbidden

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "Endpoint request timed out"
}
```