Saltar a contenido

Caso de uso: firmar un documento por coordenadas¶

Requisito previo: el dni que va a firmar debe tener un certificado principal cargado (ver Alta de usuario y certificado), y el dni enviado debe coincidir con el dni del claim del token.

Este modo se usa cuando se conoce de antemano la posición exacta (x, y, página) donde debe ir el bloque de firma, y permite controlar la apariencia del texto que lo acompaña (número de documento, ciudad, tamaños de fuente, etc.).

Request¶

curl -X POST http://localhost:8080/api/doc/sign-by-coord \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -F "file=@contrato.pdf;type=application/pdf" \
  -F "dni=12345678" \
  -F "coordX=120.5" \
  -F "coordY=680.0" \
  -F "page=1" \
  -F "reason=Aprobación de contrato" \
  -F "documentTextNumber=EXP-2026-001" \
  -F "documentTextNumberAlignment=LEFT" \
  -F "city=Lima" \
  -F "visibleSign=true" \
  -F "hasImageSignature=true" \
  -F "useTsa=false" \
  -o respuesta.json

Response (`200 OK`)¶

{
  "fileBase64Encode": "JVBERi0xLjcNCiXi48/TDQoxIDAgb2Jq...",
  "status": "SUCCESS",
  "message": "Document signed successfully"
}

jq -r '.fileBase64Encode' respuesta.json | base64 -d > contrato-firmado.pdf

Ajustando la apariencia del texto¶

Los siguientes parámetros opcionales controlan cómo se ve el bloque de texto junto a la firma (todos con valores por defecto si se omiten):

curl -X POST http://localhost:8080/api/doc/sign-by-coord \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -F "file=@contrato.pdf;type=application/pdf" \
  -F "dni=12345678" \
  -F "coordX=120.5" \
  -F "coordY=680.0" \
  -F "page=1" \
  -F "reason=Aprobación de contrato" \
  -F "documentTextNumber=EXP-2026-001" \
  -F "documentTextNumberAlignment=LEFT" \
  -F "city=Lima" \
  -F "visibleSign=true" \
  -F "documentTextNumberSize=12" \
  -F "signatureTextSpacing=25" \
  -F "documentTextNumberMultipliedLeading=1.2" \
  -F "cityAndDateTextSize=9" \
  -F "documentNumberTextFirst=false"

Si se omite city, no se pinta ni ciudad ni fecha en el bloque de firma.

Errores frecuentes¶

Situación	Respuesta
El `dni` del formulario no coincide con el `dni` del token	`401 UNAUTHORIZED` — `"The registered user cannot sign with that dni"`
El `file` no tiene `Content-Type: application/pdf`	`400 BAD_REQUEST` — `"The file must be a PDF"`
Falta algún campo obligatorio	`400 BAD_REQUEST` — `"All fields are required (file, coordX, coordY, page, reason, documentTextNumber, documentTextNumberAlignment, visibleSign, city)"`
El `dni` no tiene certificado principal cargado	`500 INTERNAL_SERVER_ERROR`

Variante: firmando con sello de tiempo (TSA)¶

Agregar useTsa=true y, opcionalmente, tsaAlias=<alias> (si se omite, se usa la TSA marcada isDefault). Ver Configurar y usar una TSA.