Caso de uso: firmar un documento por coordenadas (apariencia simple)¶

Requisito previo: el dni que va a firmar debe tener un certificado principal cargado (ver Alta de usuario y certificado).

Este endpoint (/api/doc/sign-by-coord-simple) firma en una posición explícita (x, y, página), igual que /api/doc/sign-by-coord, pero usando la misma apariencia simple de /api/doc/sign-by-label (nombre del firmante, CQFP opcional, cargo, empresa, motivo y fecha), en lugar de la apariencia extendida en tabla que usa sign-by-coord (pensada para otro caso de uso, con número de documento, ciudad, alineaciones, etc.). Úsalo cuando ya conoces la posición exacta de la firma y solo necesitas los parámetros básicos.

Request¶

curl -X POST http://localhost:8080/api/doc/sign-by-coord-simple \
  -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 "typeSigner=1" \
  -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

Tamaño de firma personalizado y CQFP opcional¶

curl -X POST http://localhost:8080/api/doc/sign-by-coord-simple \
  -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 "typeSigner=1" \
  -F "hasImageSignature=true" \
  -F "signatureWidth=220" \
  -F "signatureHeight=120" \
  -F "printCqfp=false"

Si se omiten signatureWidth/signatureHeight, se usan los valores por defecto (180x100 puntos); si se omite printCqfp, se sigue pintando la línea CQFP: <matrícula>.

Ocultar cargo/empresa y formato de fecha personalizado¶

Igual que en sign-by-label: printJobTitle/printCompany (ambos true por defecto) controlan si se pintan el cargo y la empresa, y dateFormat cambia el patrón de fecha (patrón DateTimeFormatter de Java; con un valor personalizado no se agrega el sufijo " h" que sí trae el formato por defecto):

curl -X POST http://localhost:8080/api/doc/sign-by-coord-simple \
  -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 "typeSigner=1" \
  -F "hasImageSignature=true" \
  -F "printJobTitle=false" \
  -F "printCompany=false" \
  -F "dateFormat=dd/MM/yyyy HH:mm"

Un dateFormat con un patrón inválido hace que la firma falle con 500 INTERNAL_SERVER_ERROR.

Etiquetas de texto para cargo, empresa y fecha¶

Igual que en sign-by-label: printLabelJobTitle, printLabelCompany y printLabelDate (los tres false por defecto) anteponen "Cargo: ", "Empresa: " y "Fecha y hora: " a esas líneas cuando están en true:

curl -X POST http://localhost:8080/api/doc/sign-by-coord-simple \
  -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 "typeSigner=1" \
  -F "hasImageSignature=true" \
  -F "printLabelJobTitle=true" \
  -F "printLabelCompany=true" \
  -F "printLabelDate=true"

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.

Errores frecuentes¶

Al igual que sign-by-label, este endpoint no valida que el dni del token coincida con el dni enviado (a diferencia de sign-by-coord); ver decisiones de diseño.