Gestión de firmas

/signer

Esta API permite firmar digitalmente documentos PDF.

Las operaciones soportadas son:

• Firmar documento: realiza todo el flujo y devuelve el identificador correspondiente. Se emplea la Firma Electrónica Básica (AdES - BES), proporcionando una solución robusta y confiable con ventajas significativas en términos de cumplimiento normativo, seguridad, interoperabilidad y facilidad de uso.

Flujo

Información Consumir la API desde el backend en lugar del frontend protege los datos y evita exponer credenciales sensibles, previniendo vulnerabilidades y asegurando un manejo seguro de los datos.

---

Firmar (Sign)

Solicitud de creación de firma:

bash

curl --location '{IDENTITY_API_BASE_URL}/signer' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {API_KEY}' \
--data '{
    "document": "{DOCUMENT}",
    "image": "{IMAGE}",   // Obsoleto, usar 'images' en su lugar
    "images": ["{IMAGE1}", "{IMAGE2}"],
    "page": "{PAGE}",
    "position": "{POSITION}",
    "timezone": "{TIMEZONE}",
    "signature": "{SIGNATURE}",
    "dateFormat": "{DATE_FORMAT}",
    "callbackUrl": "{CALLBACK_URL}",
    "callbackHeaders": "{CALLBACK_HEADERS}"
}'

Parámetros de la solicitud:

Campo	Requerido	Descripción
DOCUMENT	Sí	Documento PDF a firmar en formato Base64
*IMAGE	No	Obsoleto. Imagen para incrustar en el documento como parte de la prueba de firma. Formato: Base64
IMAGES	No	Un array de imágenes para incrustar en el documento como parte de la prueba de firma. Formato: Base64
PAGE	No	Página en la que se colocará la prueba de firma (indexada desde cero, valor por defecto: 0)
POSITION	No	Coordenadas de la esquina inferior-izquierda y superior-derecha del rectángulo de la imagen en píxeles, correspondientes a una resolución de 72DPI. Para una página de documento A4, los valores de X-Y van de 0-595 y 0-842 píxeles respectivamente. (Ejemplo: 300,100,500,150). Valor por defecto: 135;210;480;300
TIMEZONE	No	El identificador de zona horaria para manejar fechas en el proceso de firma. (Ejemplo: America/Lima) Valor por defecto: UTC. Lista de zonas horarias disponibles.
SIGNATURE	No	Un array de texto de forma libre que contiene los detalles de la firma. Cada línea se incluye junto a la imagen de firma. Puede incluir marcadores de posición como $(date)s, que se reemplazarán dinámicamente con la fecha y hora actual según la zona horaria y el formato especificados en los campos dateFormat y timezone. Ejemplo: ["ID - 9999999", "Date - $(date)s"]. Valor por defecto: ["Digitally signed by Facephi", "RUC:20000000000"]
DATE_FORMAT	No	La cadena de formato para representar fechas y horas, siguiendo el estándar ISO 8601. Además, admite el especificador "%z" para el desplazamiento de la zona horaria. Por ejemplo, "%d/%m/%Y %H:%M:%S%z" representa la fecha en el formato "DD/MM/AAAA HH:MM:SS±HHMM". Valor por defecto: %Y/%m/%d %H:%M:%S%z
CALLBACK_URL	Sí	URL a la que enviar el PDF firmado o el mensaje de error. No se requiere configuración adicional de Facephi para que sea funcional.
CALLBACK_HEADERS	No	Encabezados para agregar a la solicitud de la URL de callback (ejemplo: key1=value1;key2=value2)

Advertencia Los formatos de imagen admitidos son JPEG y PNG.

Ejemplo de respuesta:

202 Accepted

---

Evento de Callback

Cuando una operación se completa, ya sea exitosamente o con error, se envía una solicitud POST a la dirección en el campo callbackUrl. Si también se informa el campo callbackHeaders, se adjuntan a la solicitud.

En caso de éxito Content-Type: multipart/form-data

text

file=report-2242764658.pdf

En caso de error Content-Type: application/json

json

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

Campos de la respuesta:

Campo	Descripción
operationId	Identificador interno de la operación
error	Mensaje de error