Firma con posiciones personalizadas (CUSTOM)

Además de las posiciones automáticas (UPPER_RIGHT, UPPER_LEFT, LOWER_RIGHT, LOWER_LEFT), Verificamex permite que cada firmante coloque su firma en coordenadas exactas del PDF mediante el valor CUSTOM de sign_position. Esto es lo que usa nuestra propia app web en su editor visual de firma (“Firma Beta”), donde el usuario arrastra el recuadro de firma sobre el documento.

Requisito previo

El posicionamiento CUSTOM solo tiene efecto cuando sign_mode es PDF_SIGNATURE. Con CLASSIC o CLASSIC_BATCH la firma se agrega en una hoja de firmas independiente al final del documento, y el campo positions es ignorado.

---

Cómo activarlo

1. Al crear el documento, define sign_position: "CUSTOM" a nivel del documento.

2. Por cada firmante en el arreglo signatures, agrega el campo positions con la(s) coordenada(s) donde deseas que aparezca su firma.

3. Sube el PDF normalmente en el paso de subir documento.

---

El campo positions

positions es un arreglo de objetos, uno por cada lugar del documento donde ese firmante estampará su firma.

Campo	Tipo	Requerido	Default	Descripción
pos_x	float	No	100	Distancia desde el borde izquierdo de la página, en puntos PDF.
pos_y	float	No	100	Distancia desde el borde superior de la página, en puntos PDF.
width	float	No	140	Ancho del recuadro de firma, en puntos PDF.
height	float	No	80	Alto del recuadro de firma, en puntos PDF.
page	integer	No	1	Página donde se coloca la firma. Base 1 (la primera página es 1, no 0).
rotation	integer	No	0	Rotación del recuadro de firma en grados. Valores soportados: 0, 90, 180, 270.

`positions` viaja como texto, no como arreglo

En el endpoint de creación (POST /v1/documents, cuerpo JSON), positions debe enviarse como un string con el JSON ya serializado, no como un arreglo nativo dentro del JSON. Es el error de integración más común en este flujo.

❌ Incorrecto

{
  "name": "Juan Perez",
  "email": "juan@correo.com",
  "positions": [
    { "pos_x": 120, "pos_y": 650, "width": 180, "height": 70, "page": 1, "rotation": 0 }
  ]
}

✅ Correcto

{
  "name": "Juan Perez",
  "email": "juan@correo.com",
  "positions": "[{\"pos_x\":120,\"pos_y\":650,\"width\":180,\"height\":70,\"page\":1,\"rotation\":0}]"
}

---

Sistema de coordenadas

• Origen: esquina superior izquierda de la página (igual que un canvas o visor tipo PDF.js), no la esquina inferior izquierda que usa el estándar PDF internamente. La conversión la hace el backend por ti.
• Unidades: puntos PDF (1 punto = 1/72 pulgada) — el mismo tamaño real de la página, no píxeles de pantalla ni porcentajes. Por ejemplo, una página carta mide aproximadamente 612 x 792 puntos.
• El recuadro de firma se dibuja desde (pos_x, pos_y) extendiéndose width puntos a la derecha y height puntos hacia abajo.

Cómo obtener el tamaño real de la página

La petición de creación del documento (paso 2) se envía antes de subir el PDF (paso 3), por lo que el backend todavía no conoce el tamaño de tus páginas al momento de calcular positions. Antes de armar el payload, inspecciona tu propio PDF del lado del cliente (con cualquier librería de manejo de PDF: pdf-lib, PyPDF2/pypdf, PDFBox, iText, etc.) para obtener:

• El tamaño de página en puntos de cada página (puede variar si el PDF mezcla tamaños).
• El número total de páginas, para validar que el page que envías existe.

---

Firmas en múltiples posiciones

Un mismo firmante puede estampar su firma en más de un lugar del documento (por ejemplo, en varias páginas de un contrato) enviando más de un objeto en positions:

"positions": "[{\"pos_x\":100,\"pos_y\":700,\"width\":140,\"height\":80,\"page\":1,\"rotation\":0},{\"pos_x\":100,\"pos_y\":700,\"width\":140,\"height\":80,\"page\":3,\"rotation\":0}]"

Nota

La primera posición del arreglo es la que lleva el sello de tiempo (TSA) cuando el documento tiene más de un firmante — es la firma criptográfica principal. Las posiciones adicionales son estampas incrementales sobre el mismo PDF ya firmado. Para efectos prácticos de validez legal, todas las posiciones pertenecen a la misma firma del mismo firmante; la distinción solo importa si vas a inspeccionar el detalle criptográfico del PDF resultante.

---

Rotación

Valor	Descripción
0	Sin rotación (default).
90	Rotación 90° en sentido horario.
180	Firma invertida 180°.
270	Rotación 90° en sentido antihorario.

---

Comportamiento si falta información

CUSTOM no valida ni rechaza la petición si algo falta: si un firmante no incluye positions, o el JSON enviado no es válido, el sistema no genera un error — simplemente coloca esa firma con los valores default (pos_x=100, pos_y=100, width=140, height=80) en la última página del documento. Del mismo modo, no se valida que las coordenadas quepan dentro de la página.

Recomendación: valida en tu propia integración, antes de enviar la petición, que:

• pos_x + width y pos_y + height no excedan el tamaño real de esa página.
• page sea un número entre 1 y el total de páginas del PDF.

Esto evita firmas que terminan fuera del área visible o en una página inesperada.

---

Ejemplo completo de integración

JSON de Petición

{
  "company_id": "ac110005-9ae6-1318-819a-fc564ae00125",
  "tries": 3,
  "remember_every": 3,
  "remember_at": "16:54:00",
  "sign_mode": "PDF_SIGNATURE",
  "sign_position": "CUSTOM",
  "mode_logo": "FULL_BRANDING",
  "notification_mode": "ENABLED",
  "sign_ordered": "INACTIVE",
  "config": {
    "identity_providers": ["LOCAL", "VERIFICAMEX"],
    "allow_type_signatures": ["VERIFICAMEX", "EFIRMA"]
  },
  "signatures": [
    {
      "name": "Juan Perez",
      "email": "juanperez@gmail.com",
      "positions": "[{\"pos_x\":120,\"pos_y\":650,\"width\":180,\"height\":70,\"page\":1,\"rotation\":0}]"
    }
  ],
  "spectators": [],
  "webhook": "https://webhook.site/my-webhook"
}

cURL

curl --location 'https://api.digitafirma.com/v1/documents' \
--header 'X-Api-Key: {X-API-KEY}' \
--header 'Content-Type: application/json' \
--data '{
  "company_id": "ac110005-9ae6-1318-819a-fc564ae00125",
  "tries": 3,
  "remember_every": 3,
  "remember_at": "16:54:00",
  "sign_mode": "PDF_SIGNATURE",
  "sign_position": "CUSTOM",
  "mode_logo": "FULL_BRANDING",
  "notification_mode": "ENABLED",
  "sign_ordered": "INACTIVE",
  "signatures": [
    {
      "name": "Juan Perez",
      "email": "juanperez@gmail.com",
      "positions": "[{\"pos_x\":120,\"pos_y\":650,\"width\":180,\"height\":70,\"page\":1,\"rotation\":0}]"
    }
  ],
  "spectators": [],
  "webhook": "https://webhook.site/my-webhook"
}'

Con el uuid de la respuesta, continúa con Subir un documento para cargar el PDF y activar el proceso de firma.

---

Actualizar posiciones de firmantes existentes

El campo positions también está disponible al actualizar firmantes de un documento ya creado (PATCH /v1/documents/{uuid}), con el mismo formato de string JSON descrito arriba.

Próximos pasos

Antes de pasar a producción, descarga el PDF firmado (Descargar documento firmado) y verifica visualmente que las firmas caigan donde esperas, especialmente si tus documentos tienen páginas de distinto tamaño.