Digito

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ónRuta de producciónResultado
Validar un PDFPOST https://valida.digito.do/validateReporte JSON compacto o extendido.
Consultar OpenAPI 3.1GET https://valida.digito.do/api/v1/openapi.jsonOperación y esquemas de respuesta para generar clientes.
Consultar encabezados del contratoHEAD https://valida.digito.do/api/v1/openapi.jsonEncabezados, sin cuerpo.

Envía el PDF siguiendo estos requisitos:

RequisitoValor
Campo multipartExactamente un campo file con un archivo; no repitas el campo ni añadas otros.
Nombre del archivoTermina en .pdf, sin distinguir mayúsculas y minúsculas.
Tipo de la parteapplication/pdf.
Encabezado del archivoLos primeros cinco bytes deben ser %PDF-.
Tamaño predeterminado del archivoHasta 100 MiB, inclusive: 104 857 600 bytes.
Margen del cuerpo multipartHasta 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ónQué puedes comprobar
Resultado e integridadEstado de cada firma y si el contenido firmado mantiene su integridad.
FirmantesNombre e identificación del titular que figuran en su certificado.
Fechas y tiemposFecha declarada de firma, tiempo respaldado por evidencias y resultados de los sellos de tiempo.
CertificadosEntidad emisora y, en la vista extendida, cadena de confianza, vigencia y revocación.
Detalle técnicoMotivos, avisos y evidencias para explicar un resultado o investigar un caso.

Vista compacta o extendida

ConsultaVista
Sin parámetros, o ?include=noneCompacta: resultado, firmante, identificación, emisor, tiempos e integridad de cada firma.
?include=evidenceExtendida: 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.statusSignificado
validTodas las firmas del PDF son válidas según la política del validador.
invalidAl menos una firma es inválida. Este resultado prevalece sobre los demás.
indeterminateNinguna firma es inválida, pero al menos una no tiene un resultado concluyente con la evidencia disponible.
unsignedNo 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

  1. Recibe y conserva el PDF original. Valida el archivo exacto que recibiste, sin modificarlo.
  2. Solicita la validación. Envía el PDF a POST /validate y lee el reporte JSON.
  3. 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.
  4. 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
idIdentificador de la firma dentro del reporte.
statusvalid, invalid o indeterminate.
reasonCodeMotivo ETSI específico, por ejemplo HASH_FAILURE; se omite cuando no está disponible. Su ausencia no demuestra validez.
signer.nameNombre obtenido del certificado, o null.
signer.identificationIdentificador del titular leído del certificado, o null cuando no está disponible.
signer.identification.typenational_id, passport u other.
signer.identification.countryCodeCódigo de país de dos letras para formatos reconocidos, o null.
signer.identification.numberNúmero como texto, conservando ceros iniciales; con other conserva el identificador completo.
certificateIssuerAutoridad que emitió el certificado del firmante, cuando se conoce; puede ser null.
signingTime.claimedAtFecha declarada por el firmante, o null.
signingTime.bestSignatureTimeMejor estimación respaldada por evidencia validada de que la firma ya existía, o null.
integrity.signedBytesIntactSi los bytes protegidos por esa firma mantienen su integridad.
integrity.disallowedChangesAfterSigningSi 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:

CampoContenido
format, levelFormato y nivel informados por el motor, como PAdES y PAdES_BASELINE_LT; pueden ser null.
errors, warningsListas de diagnósticos del motor. Pueden estar en español o inglés; usa status para decisiones automáticas.
evidence.certificateChainCadena ordenada desde la raíz hasta el certificado del firmante.
evidence.timestampsSellos de tiempo y el resultado de validación de cada uno.
evidence.etsiindication y subIndication del resultado ETSI; pueden ser null.
evidence.byteRangePara PDF, [a,b,c,d] cubre b bytes desde a y d bytes desde c; puede estar vacío.
evidence.coversWholeDocumentSi 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 comprobarDónde mirarloCómo leerlo
Qué certificados respaldan la firmacertificateChainLa 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 revocadocertificateChain[].revocationgood 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 firmatimestampsCada 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 respuestaUso
X-Request-IdIdentificador generado por el servidor; consérvalo para informar de un fallo.
X-RateLimit-Limit, X-RateLimit-RemainingCuota y solicitudes restantes, cuando se evalúa ese límite.
X-RateLimit-ResetMarca de la ventana en segundos Unix. Para reintentar tras un 429, utiliza Retry-After.
Retry-AfterSegundos de espera en un 429.
Cache-Controlno-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."
  }
}
HTTPerror.codeQué hacer
400invalid_queryOmite la consulta o envía include=none o include=evidence una sola vez, sin otros parámetros.
400invalid_multipartDeja que la biblioteca de carga construya el multipart y su delimitador.
400invalid_fileComprueba que haya un único archivo file y cumpla el nombre, tipo y encabezado requeridos.
403forbiddenUsa el dominio público del validador.
404not_foundLa operación pública está deshabilitada en ese entorno; consulta con Digito.
405method_not_allowedConsulta Allow; utiliza POST para enviar el PDF.
413file_too_largeComprueba el tamaño del archivo y del multipart. No modifiques un PDF firmado para reducirlo sin evaluar el efecto en sus firmas.
415unsupported_media_typeEnvía la solicitud como multipart/form-data, con el PDF como parte.
422unprocessable_pdfComprueba que el PDF se abra y que hayas enviado sus bytes originales.
429rate_limitedEspera Retry-After y reduce los envíos simultáneos.
500internal_errorSi persiste, informa a Digito con el ID de solicitud.
502engine_unavailableEl motor no respondió correctamente o devolvió un reporte inutilizable. Reintenta con espera limitada.
503service_busyEl servicio alcanzó su capacidad; espera antes de reintentar.
503service_unavailableLa entrada pública no está disponible en ese entorno.
503engine_unavailableNo hay un motor de validación configurado en ese entorno.
504engine_timeoutSe 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.