> 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/api-rest/identity-api/identity-api-reference/digital-signatures/signer.md).

# Signer

Este servicio ejecuta el flujo completo de firma digital y retorna una respuesta `202 Accepted` inmediatamente. El servicio procesa la operación de firma de forma **asíncrona**.

Implementa Firma Electrónica Básica (AdES - BES), proporcionando una solución robusta y confiable con ventajas significativas en cumplimiento regulatorio, seguridad, interoperabilidad y facilidad de uso.

#### Callback asíncrono

Al completarse la operación — ya sea exitosa o fallida — el servicio envía una solicitud POST a la URL especificada en el parámetro `callbackUrl`. Si se proporcionan `callbackHeaders`, estos se incluirán en la solicitud de callback.

* **Firma exitosa**: Content-Type `multipart/form-data`. Retorna el documento PDF firmado como archivo adjunto.
* **Firma fallida**: Content-Type `application/json`. Retorna un objeto de error con `operationId` y mensaje de `error`.

{% hint style="warning" %}
Solo los formatos de imagen **JPEG** y **PNG** son soportados para la visualización de firma. Otros formatos resultarán en un error.
{% endhint %}

{% hint style="info" %}
**Recomendación de seguridad:** Siempre consumir esta API desde su infraestructura backend en lugar de aplicaciones frontend. Este enfoque protege datos sensibles, previene la exposición de credenciales y asegura el manejo seguro de documentos durante todo el proceso de firma.
{% endhint %}

### Endpoint

```
POST /signer
```

### Headers

| Nombre        | Tipo   | Requerido | Descripción                        |
| ------------- | ------ | --------- | ---------------------------------- |
| **x-api-key** | string | **Sí**    | API key de autorización de acceso. |

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro         | Tipo      | Requerido | Descripción                                                                                                                                                                                                                                                             |
| ----------------- | --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document`        | string    | **Sí**    | Documento PDF a firmar digitalmente, codificado en formato **Base64** (RFC4648).                                                                                                                                                                                        |
| `images`          | string\[] | No        | Array de imágenes de visualización de firma para incrustar en el documento. Cada imagen debe estar codificada en **Base64**. Formatos soportados: **JPEG**, **PNG**.                                                                                                    |
| `image`           | string    | No        | **Obsoleto.** Usar el array `images` en su lugar. Imagen única para incrustar como visualización de firma, codificada en **Base64**.                                                                                                                                    |
| `page`            | integer   | No        | Número de página destino para la colocación de la firma, indexado desde cero. **Valor predeterminado:** `0` (primera página).                                                                                                                                           |
| `position`        | string    | No        | Coordenadas del rectángulo de firma en píxeles a 72 DPI: X inferior izquierdo, Y inferior izquierdo, X superior derecho, Y superior derecho. Para páginas A4, rangos válidos: X: 0-595, Y: 0-842. Formato: `x1,y1,x2,y2`. **Valor predeterminado:** `"135,210,480,300"` |
| `timezone`        | string    | No        | Identificador de zona horaria IANA para el formato de fecha/hora en metadatos de firma. Ejemplos: `America/Lima`, `Europe/Madrid`, `Asia/Tokyo`. **Valor predeterminado:** `"UTC"`                                                                                      |
| `signature`       | string\[] | No        | Líneas de texto personalizadas para mostrar junto a la imagen de firma. Soporta placeholders dinámicos: `$(date)s` se reemplaza con la marca de tiempo actual formateada según `dateFormat` y `timezone`. Cada elemento del array representa una línea de texto.        |
| `dateFormat`      | string    | No        | Cadena de formato de fecha/hora siguiendo el estándar ISO 8601 con directivas strftime. Soporta `%z` para offset de zona horaria. Ejemplo: `%d/%m/%Y %H:%M:%S%z`. **Valor predeterminado:** `"%Y/%m/%d %H:%M:%S%z"`                                                     |
| `callbackUrl`     | string    | **Sí**    | URL del webhook para recibir el documento firmado o la notificación de error. El servicio enviará los resultados por POST a este endpoint de forma asíncrona.                                                                                                           |
| `callbackHeaders` | string    | No        | Headers HTTP opcionales para incluir en la solicitud de callback. Formato: pares clave=valor separados por punto y coma. Ejemplo: `Authorization=Bearer token;X-Custom=value`                                                                                           |

#### Ejemplo de solicitud

```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"
}
```

### Respuestas

#### `202` Accepted

La solicitud fue aceptada y la operación de firma se está procesando de forma asíncrona. El resultado será enviado a la URL de callback proporcionada.

#### Callback — Firma exitosa

Content-Type: `multipart/form-data`

El documento PDF firmado se retorna como archivo adjunto.

#### Callback — Firma fallida

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"
}
```