Documentos (firma de PDF)¶

Hay tres endpoints de firma. Todos requieren token (Authorization: Bearer <token>) y que el dni indicado tenga un certificado principal cargado (ver Certificados). El archivo enviado en file debe tener Content-Type: application/pdf; cualquier otro tipo responde 400 BAD_REQUEST con "The file must be a PDF".

sign-by-coord-simple existe para los casos que necesitan firmar en una posición exacta (sin buscar un texto en el PDF) pero con la apariencia simple de sign-by-label, sin tener que usar los parámetros adicionales de sign-by-coord (pensado para otro caso de uso).

En sign-by-label y sign-by-coord-simple, las líneas CQFP: <matrícula>, cargo y empresa solo se pintan si además de no estar desactivadas (printCqfp, printJobTitle, printCompany, todos true por defecto) el dato correspondiente no está vacío: tuition (ver Autenticación, campo opcional en signup), jobTitle o company del certificado. Si el dato está vacío, la línea se omite automáticamente sin necesidad de pasar el flag en false.

Además, printLabelJobTitle, printLabelCompany y printLabelDate (todos false por defecto) anteponen una etiqueta a esas líneas cuando están en true: "Cargo: ", "Empresa: " y "Fecha y hora: " respectivamente. Con el valor por defecto (false) el texto se pinta igual que antes, sin etiqueta.

Los tres devuelven un SignResponse:

{
  "fileBase64Encode": "<PDF firmado, codificado en Base64>",
  "status": "SUCCESS",
  "message": "Document signed successfully"
}

Ver ejemplos completos, incluyendo cómo decodificar la respuesta, en Casos de uso: firmar un documento por etiqueta, Casos de uso: firmar por coordenadas (apariencia simple) y en Casos de uso: firmar un documento por coordenadas.

POST /api/doc/sign-by-label¶

Busca una etiqueta de texto dentro del PDF (recorriendo todas las páginas) y coloca ahí el bloque de firma.

Importante: este endpoint no valida que el dni del token coincida con el dni enviado — cualquier usuario autenticado puede firmar en nombre de cualquier dni que tenga certificado principal cargado. Si no se encuentra la etiqueta en el PDF o no existe certificado principal para el dni, la firma falla con 500 INTERNAL_SERVER_ERROR.

curl -X POST http://localhost:8080/api/doc/sign-by-label \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -F "file=@contrato.pdf;type=application/pdf" \
  -F "dni=12345678" \
  -F "label=FIRMA_AQUI" \
  -F "reason=Aprobación de contrato" \
  -F "typeSigner=1" \
  -F "hasImageSignature=true" \
  -F "useTsa=true" \
  -F "tsaAlias=tsa-prd" \
  -F "signatureWidth=200" \
  -F "signatureHeight=110" \
  -F "printCqfp=false" \
  -F "printJobTitle=false" \
  -F "printCompany=false" \
  -F "dateFormat=dd/MM/yyyy HH:mm" \
  -F "printLabelJobTitle=true" \
  -F "printLabelCompany=true" \
  -F "printLabelDate=true"

POST /api/doc/sign-by-coord-simple¶

Firma en una posición explícita (x, y, página), igual que sign-by-coord, pero usando la misma apariencia simple de sign-by-label (nombre, CQFP opcional, cargo, empresa, motivo y fecha) en lugar de la apariencia extendida en tabla. Usar este endpoint cuando ya se conoce la posición exacta de la firma y no se necesitan los parámetros adicionales de sign-by-coord (número de documento, ciudad, alineaciones, etc.).

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).

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"

POST /api/doc/sign-by-coord¶

Firma en una posición explícita (x, y, página), con control fino sobre la apariencia del bloque de texto de la firma.

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"

Comportamiento de useTsa / tsaAlias (ambos endpoints)¶

Códigos de respuesta¶