Signature Validation API
Valida las firmas digitales de un PDF y recibe un reporte JSON en la misma solicitud, sin credenciales.
Signature Validation API comprueba las firmas de un PDF y devuelve un reporte JSON en la misma solicitud: quién firmó, si el contenido conserva su integridad y qué evidencias respaldan el resultado.
La API es pública y no requiere credenciales. Puedes llamarla desde servidores y navegadores en https://valida.digito.do.
Para qué sirve
Valida documentos recibidos antes de aprobar un trámite, comprueba las firmas de un acuerdo antes de continuar tu proceso o conserva el reporte junto con el PDF firmado. Puedes automatizar los casos que cumplen tus condiciones y enviar los demás a revisión.
Primera solicitud
Envía un único PDF en el campo file de un cuerpo multipart/form-data.
BASE_URL='https://valida.digito.do'
PDF='./documento firmado.pdf'
curl --silent --show-error --fail-with-body \
--form "file=@${PDF};type=application/pdf" \
"${BASE_URL}/validate"No configures manualmente el Content-Type general de la solicitud: cURL y FormData incluyen el delimitador multipart. El tipo de la parte del archivo sí debe ser application/pdf.
HTTP 200 no significa que todas las firmas sean válidas
200 confirma que la validación terminó. Para decidir si aceptas el documento, revisa summary.status y el resultado de cada firma.
Contrato HTTP y archivo de entrada
| Operación | Ruta de producción | Resultado |
|---|---|---|
| Validar un PDF | POST https://valida.digito.do/validate | Reporte JSON compacto o extendido. |
| Consultar OpenAPI 3.1 | GET https://valida.digito.do/api/v1/openapi.json | Operación y esquemas de respuesta para generar clientes. |
| Consultar encabezados del contrato | HEAD https://valida.digito.do/api/v1/openapi.json | Encabezados, sin cuerpo. |
Envía el PDF siguiendo estos requisitos:
| Requisito | Valor |
|---|---|
| Campo multipart | Exactamente un campo file con un archivo; no repitas el campo ni añadas otros. |
| Nombre del archivo | Termina en .pdf, sin distinguir mayúsculas y minúsculas. |
| Tipo de la parte | application/pdf. |
| Encabezado del archivo | Los primeros cinco bytes deben ser %PDF-. |
| Tamaño predeterminado del archivo | Hasta 100 MiB, inclusive: 104 857 600 bytes. |
| Margen del cuerpo multipart | Hasta 1 MiB adicional para encabezados y delimitadores. |
El límite de tamaño es configurable por el servicio. Envía los bytes originales: comprimir, editar o volver a guardar un PDF firmado puede afectar a sus firmas.
Qué información devuelve
El reporte reúne los resultados de las firmas encontradas. La información disponible depende del PDF, sus certificados y las evidencias que puedan comprobarse.
| Información | Qué puedes comprobar |
|---|---|
| Resultado e integridad | Estado de cada firma y si el contenido firmado mantiene su integridad. |
| Firmantes | Nombre e identificación del titular que figuran en su certificado. |
| Fechas y tiempos | Fecha declarada de firma, tiempo respaldado por evidencias y resultados de los sellos de tiempo. |
| Certificados | Entidad emisora y, en la vista extendida, cadena de confianza, vigencia y revocación. |
| Detalle técnico | Motivos, avisos y evidencias para explicar un resultado o investigar un caso. |
Vista compacta o extendida
| Consulta | Vista |
|---|---|
Sin parámetros, o ?include=none | Compacta: resultado, firmante, identificación, emisor, tiempos e integridad de cada firma. |
?include=evidence | Extendida: añade formato, nivel, diagnósticos, certificados, revocación, sellos de tiempo y resultados ETSI. |
Envía include como máximo una vez. Otros parámetros o valores no admitidos producen 400 invalid_query.
curl --silent --show-error --fail-with-body \
--form "file=@${PDF};type=application/pdf" \
'https://valida.digito.do/validate?include=evidence'Interpreta el resultado
summary.status | Significado |
|---|---|
valid | Todas las firmas del PDF son válidas según la política del validador. |
invalid | Al menos una firma es inválida. Este resultado prevalece sobre los demás. |
indeterminate | Ninguna firma es inválida, pero al menos una no tiene un resultado concluyente con la evidencia disponible. |
unsigned | No se encontraron firmas: los contadores son cero y signatures es una lista vacía. |
summary.signatureCounts contiene total, valid, indeterminate e invalid. El total cuenta firmas, no personas distintas; una persona puede haber firmado más de una vez.
validatedAt indica cuándo se realizó la validación. document.filename identifica el nombre enviado y document.sha256 contiene la huella de esos bytes en 64 caracteres hexadecimales minúsculos. Utiliza la huella para relacionar el reporte con el archivo exacto.
Cómo incorporarla a tu proceso
- Recibe y conserva el PDF original. Valida el archivo exacto que recibiste, sin modificarlo.
- Solicita la validación. Envía el PDF a
POST /validatey lee el reporte JSON. - Aplica tus condiciones. Comprueba los resultados de las firmas y contrasta las identidades con las personas que esperabas. Revisa fechas, certificados o representación según las necesidades del trámite.
- Continúa o solicita revisión. Si se cumplen tus reglas, avanza automáticamente. Si el resultado es inválido, indeterminado o falta una firma esperada, conserva el detalle y deriva el caso a revisión.
Ejemplo de automatización
Un portal recibe un acuerdo firmado y lo valida mediante la API. Comprueba que las firmas son válidas y corresponden a las personas previstas; después marca el acuerdo como verificado y activa el siguiente paso. La aplicación define esas reglas: una firma técnicamente válida no demuestra por sí sola la representación o autorización que el trámite exige.
Puedes combinar este control con Digito Link API o con una experiencia de firma construida sobre CSC.
Referencia del reporte
Ejemplo de vista compacta
Datos ficticios para ilustrar el contrato:
{
"validatedAt": "2026-11-19T14:32:08.000Z",
"document": {
"filename": "contrato-firmado.pdf",
"sha256": "ff05c1bc8e005406979d4582d757895ab198c18719dd49e61d39a311b22bee1c"
},
"summary": {
"status": "valid",
"signatureCounts": {
"total": 1,
"valid": 1,
"indeterminate": 0,
"invalid": 0
}
},
"signatures": [
{
"id": "S1",
"status": "valid",
"signer": {
"name": "Laura Marte",
"identification": {
"type": "national_id",
"countryCode": "DO",
"number": "001-1234567-8"
}
},
"certificateIssuer": "Digito Issuing CA DO 02",
"signingTime": {
"claimedAt": "2026-11-18T16:20:00.000Z",
"bestSignatureTime": "2026-11-18T16:20:04.000Z"
},
"integrity": {
"signedBytesIntact": true,
"disallowedChangesAfterSigning": false
}
}
]
}Identidad, fechas e integridad de cada firma
Campo de signatures[] | Cómo interpretarlo |
|---|---|
id | Identificador de la firma dentro del reporte. |
status | valid, invalid o indeterminate. |
reasonCode | Motivo ETSI específico, por ejemplo HASH_FAILURE; se omite cuando no está disponible. Su ausencia no demuestra validez. |
signer.name | Nombre obtenido del certificado, o null. |
signer.identification | Identificador del titular leído del certificado, o null cuando no está disponible. |
signer.identification.type | national_id, passport u other. |
signer.identification.countryCode | Código de país de dos letras para formatos reconocidos, o null. |
signer.identification.number | Número como texto, conservando ceros iniciales; con other conserva el identificador completo. |
certificateIssuer | Autoridad que emitió el certificado del firmante, cuando se conoce; puede ser null. |
signingTime.claimedAt | Fecha declarada por el firmante, o null. |
signingTime.bestSignatureTime | Mejor estimación respaldada por evidencia validada de que la firma ya existía, o null. |
integrity.signedBytesIntact | Si los bytes protegidos por esa firma mantienen su integridad. |
integrity.disallowedChangesAfterSigning | Si hay cambios posteriores prohibidos por la política de esa firma. Un PDF puede admitir firmas posteriores. |
Las fechas se devuelven en UTC, con formato ISO 8601 y sufijo Z. La fecha declarada y el tiempo respaldado por evidencias no son equivalentes.
El número de identificación del titular no es el número de serie que el emisor asignó al certificado. Por ejemplo, el identificador de sujeto IDCDO-001-1234567-8 produce type: "national_id", countryCode: "DO" y number: "001-1234567-8".
Comprueba el status de la firma antes de utilizar la identidad declarada en su certificado.
Vista extendida y evidencias
Con include=evidence, cada firma añade:
| Campo | Contenido |
|---|---|
format, level | Formato y nivel informados por el motor, como PAdES y PAdES_BASELINE_LT; pueden ser null. |
errors, warnings | Listas de diagnósticos del motor. Pueden estar en español o inglés; usa status para decisiones automáticas. |
evidence.certificateChain | Cadena ordenada desde la raíz hasta el certificado del firmante. |
evidence.timestamps | Sellos de tiempo y el resultado de validación de cada uno. |
evidence.etsi | indication y subIndication del resultado ETSI; pueden ser null. |
evidence.byteRange | Para PDF, [a,b,c,d] cubre b bytes desde a y d bytes desde c; puede estar vacío. |
evidence.coversWholeDocument | Si la revisión firmada llega al final del archivo, o null sin un rango de cuatro valores. |
En el nivel superior, evidence.etsiXml contiene el reporte XML ETSI del documento, o null cuando el motor no lo produjo.
Una revisión anterior puede seguir siendo válida
coversWholeDocument: false puede deberse a una firma posterior permitida. No lo interpretes por sí solo como una alteración inválida: utiliza el estado de la firma y sus comprobaciones de integridad.
Ejemplo de vista extendida
El mismo ejemplo con evidencias adicionales:
Ver reporte extendido completo
{
"validatedAt": "2026-11-19T14:32:08.000Z",
"document": {
"filename": "contrato-firmado.pdf",
"sha256": "ff05c1bc8e005406979d4582d757895ab198c18719dd49e61d39a311b22bee1c"
},
"summary": {
"status": "valid",
"signatureCounts": {
"total": 1,
"valid": 1,
"indeterminate": 0,
"invalid": 0
}
},
"signatures": [
{
"id": "S1",
"status": "valid",
"signer": {
"name": "Laura Marte",
"identification": {
"type": "national_id",
"countryCode": "DO",
"number": "001-1234567-8"
}
},
"certificateIssuer": "Digito Issuing CA DO 02",
"format": "PAdES",
"level": "PAdES_BASELINE_LT",
"signingTime": {
"claimedAt": "2026-11-18T16:20:00.000Z",
"bestSignatureTime": "2026-11-18T16:20:04.000Z"
},
"integrity": {
"signedBytesIntact": true,
"disallowedChangesAfterSigning": false
},
"errors": [],
"warnings": [],
"evidence": {
"certificateChain": [
{
"name": "Digito Root CA",
"trustAnchor": true,
"revocation": "trust_anchor",
"revokedAt": null,
"details": null
},
{
"name": "Digito Issuing CA DO 02",
"trustAnchor": false,
"revocation": "good",
"revokedAt": null,
"details": null
},
{
"name": "Laura Marte",
"trustAnchor": false,
"revocation": "good",
"revokedAt": null,
"details": null
}
],
"timestamps": [
{
"type": "SIGNATURE_TIMESTAMP",
"producedAt": "2026-11-18T16:20:04.000Z",
"issuer": "TSA de ejemplo",
"status": "valid",
"policyOid": null,
"accuracy": null,
"warnings": []
}
],
"etsi": {
"indication": "TOTAL_PASSED",
"subIndication": null
},
"byteRange": [
0,
900,
2900,
100
],
"coversWholeDocument": true
}
}
],
"evidence": {
"etsiXml": null
}
}Certificados, revocación y sellos de tiempo
Estas evidencias te ayudan a entender quién respalda la firma y qué se pudo comprobar sobre sus certificados y fechas.
| Qué quieres comprobar | Dónde mirarlo | Cómo leerlo |
|---|---|---|
| Qué certificados respaldan la firma | certificateChain | La lista empieza por la autoridad raíz y termina en el certificado del firmante. name identifica cada certificado y trustAnchor señala el ancla de confianza utilizada. |
| Si un certificado fue revocado | certificateChain[].revocation | good indica que no consta revocado; revoked, que fue revocado; unknown, que no se pudo determinar. trust_anchor identifica el certificado usado como ancla de confianza. Si hay fecha de revocación, aparece en revokedAt. |
| Qué evidencia de tiempo tiene la firma | timestamps | Cada sello incluye su fecha en producedAt, la autoridad en issuer y su resultado en status. Revisa el estado de cada sello para saber qué tiempos cuentan con evidencia válida. |
Si necesitas investigar un resultado, abre details dentro del certificado. Allí encontrarás su emisor, período de validez y los registros de revocación consultados. El contrato OpenAPI detalla todos los campos disponibles.
Límites, CORS y encabezados
La API y el formulario del sitio comparten los límites de validación. Los valores predeterminados por instancia del servidor son:
- 10 solicitudes por IP en una ventana móvil de 60 segundos.
- 2 validaciones simultáneas por IP.
- 4 validaciones simultáneas en total.
Los límites pueden variar según la configuración del servicio. Una IP pública compartida utiliza la misma cuota; una solicitud admitida puede consumirla aunque luego se rechace el archivo.
| Encabezado de respuesta | Uso |
|---|---|
X-Request-Id | Identificador generado por el servidor; consérvalo para informar de un fallo. |
X-RateLimit-Limit, X-RateLimit-Remaining | Cuota y solicitudes restantes, cuando se evalúa ese límite. |
X-RateLimit-Reset | Marca de la ventana en segundos Unix. Para reintentar tras un 429, utiliza Retry-After. |
Retry-After | Segundos de espera en un 429. |
Cache-Control | no-store para el reporte y el contrato. |
La API permite llamadas desde cualquier origen mediante CORS, sin credenciales. En el navegador usa credentials: 'omit'. JavaScript puede leer los encabezados de identificación, cuota y Retry-After de la tabla.
Los preflight OPTIONS /validate y OPTIONS /api/v1/openapi.json responden 204. Se admite Content-Type y el preflight puede almacenarse 600 segundos. Consultar el contrato o hacer preflight no consume la cuota de envíos.
El tiempo de espera predeterminado del motor es 120 segundos. Deja margen adicional en el cliente para cargar el PDF y recibir la respuesta.
Errores y reintentos
Los errores incluyen error.code y error.message. Decide según el estado HTTP y el código; el mensaje es explicativo. Este ejemplo corresponde a 422:
{
"error": {
"code": "unprocessable_pdf",
"message": "The PDF could not be validated."
}
}| HTTP | error.code | Qué hacer |
|---|---|---|
400 | invalid_query | Omite la consulta o envía include=none o include=evidence una sola vez, sin otros parámetros. |
400 | invalid_multipart | Deja que la biblioteca de carga construya el multipart y su delimitador. |
400 | invalid_file | Comprueba que haya un único archivo file y cumpla el nombre, tipo y encabezado requeridos. |
403 | forbidden | Usa el dominio público del validador. |
404 | not_found | La operación pública está deshabilitada en ese entorno; consulta con Digito. |
405 | method_not_allowed | Consulta Allow; utiliza POST para enviar el PDF. |
413 | file_too_large | Comprueba el tamaño del archivo y del multipart. No modifiques un PDF firmado para reducirlo sin evaluar el efecto en sus firmas. |
415 | unsupported_media_type | Envía la solicitud como multipart/form-data, con el PDF como parte. |
422 | unprocessable_pdf | Comprueba que el PDF se abra y que hayas enviado sus bytes originales. |
429 | rate_limited | Espera Retry-After y reduce los envíos simultáneos. |
500 | internal_error | Si persiste, informa a Digito con el ID de solicitud. |
502 | engine_unavailable | El motor no respondió correctamente o devolvió un reporte inutilizable. Reintenta con espera limitada. |
503 | service_busy | El servicio alcanzó su capacidad; espera antes de reintentar. |
503 | service_unavailable | La entrada pública no está disponible en ese entorno. |
503 | engine_unavailable | No hay un motor de validación configurado en ese entorno. |
504 | engine_timeout | Se agotó el tiempo del motor. Espacia y limita los reintentos. |
Cada reenvío del PDF inicia una validación nueva: no recupera un resultado anterior. Ante fallos transitorios, aplica esperas y un número limitado de intentos; no reintentes automáticamente errores de archivo o de consulta sin corregirlos.
Datos y conservación del reporte
Esta operación no guarda el PDF ni el reporte en el servicio, no crea un link público y no devuelve un identificador para consultarlo después. Si tu proceso necesita conservar el resultado, guarda la respuesta junto con la huella del archivo siguiendo las reglas de tu aplicación.
Ambas vistas pueden contener nombres e identificadores personales; la extendida también puede incluirlos en certificados y XML. No envíes los reportes completos a herramientas de analítica ni los publiques sin revisar su contenido.
Si quieres conversar sobre tu integración, escribe a soporte@digito.do.