Informe de firma electrónica: referencia de signatures[]

Cada paso de Firma electrónica produce un resultado por firmante. Se encuentra como un elemento de signatures[] en:

GET /v3/session/{sessionId}/decision/, para sesiones de Verificación de usuarios (KYC) y Verificación de empresas (KYB).
La decision de los webhooks de sesión de V3, que se envían cuando la sesión está en Approved, Declined, In Review o Abandoned.
La pestaña Firma de la sesión en la consola y la sección de firma del informe en PDF.

signatures solo aparece en la decisión cuando el workflow tiene un paso de Firma electrónica. Es un array vacío hasta que un firmante llega al paso. Un paso de KYC tiene un elemento; un paso de KYB tiene un elemento por firmante.

Ejemplo

{
  "signatures": [
    {
      "id": "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
      "node_id": "feature_signature",
      "status": "signed",
      "verdict": "Approved",
      "level": "aes",
      "format": "pades",
      "profile": "PAdES-B-LT",
      "signer": {
        "name": "Jane Doe",
        "capacity": "self",
        "company": null,
        "role": null,
        "roles": [],
        "identity_session_id": "11111111-2222-3333-4444-555555555555"
      },
      "identity_used": {
        "session_id": "11111111-2222-3333-4444-555555555555",
        "kyc_id": "6f1e8f6c-1d2b-4c3a-9e8f-7a6b5c4d3e2f",
        "verified": true,
        "expected_name": "Jane Doe"
      },
      "certificate": {
        "issuer": "<certificate issuer>",
        "issued_to": "<certificate subject>",
        "serial": "5A3F9C21",
        "valid_from": "2026-01-01T00:00:00+00:00",
        "valid_until": "2028-01-01T00:00:00+00:00"
      },
      "confirmation": {
        "channel": "email",
        "destination": "j***@example.com",
        "confirmed_at": "2026-11-03T10:42:18.512Z",
        "attempts": 1
      },
      "timestamp": {
        "time": "2026-11-03T10:42:21+00:00",
        "qualified": false,
        "valid": true
      },
      "documents": [
        {
          "id": "9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b",
          "uuid": "9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b",
          "title": "Account agreement",
          "file_name": "agreement.pdf",
          "pages": 4,
          "size_bytes": 182344,
          "sha256_original": "3b8e5f0c2a9d4e7f1b6c0a5d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f",
          "sha256_signed": "a1f2e3d4c5b6a7980f1e2d3c4b5a69788f7e6d5c4b3a29180f1e2d3c4b5a6978",
          "status": "signed",
          "opened_at": "2026-11-03T10:40:02.118Z",
          "read_at": "2026-11-03T10:41:10.044Z",
          "read_to_end": true,
          "consented_at": "2026-11-03T10:41:12.730Z",
          "consent": true,
          "signed_file": "/v3/session/11111111-2222-3333-4444-555555555555/signatures/feature_signature/documents/9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b/file/",
          "mode": "fields",
          "source_format": "pdf",
          "conversion": null,
          "fields": [
            {
              "key": "full_name",
              "type": "full_name",
              "role": "verified_person",
              "label": "Full name",
              "page": 1,
              "x": 0.34,
              "y": 0.2326,
              "width": 0.57,
              "height": 0.0325,
              "required": true,
              "value": "Jane Doe",
              "display_value": "Jane Doe",
              "value_source": "identity",
              "filled_at": "2026-11-03T10:40:02.118Z",
              "value_unavailable_reason": null
            },
            {
              "key": "occupation",
              "type": "text",
              "role": "verified_person",
              "label": "Occupation",
              "page": 1,
              "x": 0.34,
              "y": 0.4618,
              "width": 0.57,
              "height": 0.0325,
              "required": true,
              "value": "Architect",
              "display_value": "Architect",
              "value_source": "signer",
              "filled_at": "2026-11-03T10:40:41.502Z",
              "value_unavailable_reason": null
            },
            {
              "key": "signature",
              "type": "signature",
              "role": "verified_person",
              "label": "Signature",
              "page": 4,
              "x": 0.09,
              "y": 0.5303,
              "width": 0.36,
              "height": 0.0849,
              "required": true,
              "value": true,
              "display_value": "Signed",
              "value_source": "signer",
              "filled_at": "2026-11-03T10:41:05.200Z",
              "image_url": "/v3/session/11111111-2222-3333-4444-555555555555/signatures/feature_signature/fields/c4d5e6f7-0a1b-4c2d-8e3f-4a5b6c7d8e9f/image/",
              "value_unavailable_reason": null
            }
          ]
        }
      ],
      "adopted_signature": {
        "method": "drawn",
        "font": null,
        "adopted_at": "2026-11-03T10:41:02.871Z"
      },
      "electronic_signature_consent_at": "2026-11-03T10:41:40.016Z",
      "evidence_file": "/v3/session/11111111-2222-3333-4444-555555555555/signatures/feature_signature/evidence/?signature_id=0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
      "warnings": [],
      "validation": {
        "valid": true,
        "checked_at": "2026-11-03T10:42:24.903Z",
        "documents": [
          {
            "id": "9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b",
            "checked_at": "2026-11-03T10:42:24.903Z",
            "valid": true,
            "integrity": true,
            "trusted": true,
            "revoked": false,
            "trusted_list": { "status": "not_applicable", "reason": "aes_not_qualified" },
            "certificate": {
              "issuer": "<certificate issuer>",
              "issued_to": "<certificate subject>",
              "serial": "5A3F9C21",
              "valid_from": "2026-01-01T00:00:00+00:00",
              "valid_until": "2028-01-01T00:00:00+00:00"
            },
            "timestamp": { "time": "2026-11-03T10:42:21+00:00", "qualified": false, "valid": true }
          }
        ]
      },
      "declined_at": null,
      "declined_action": "REVIEW",
      "signed_at": "2026-11-03T10:42:24.903Z",
      "expires_at": "2026-11-10T10:30:00.000Z",
      "email_sent_at": "2026-11-03T10:42:30.011Z",
      "email_unavailable_reason": null,
      "ip_address": "203.0.113.10",
      "place": null,
      "place_unavailable_reason": "not_collected"
    }
  ]
}

El objeto de firma

Campo	Tipo	Descripción
`id`	string (UUID)	La firma del firmante. Pasa este valor como `signature_id` para descargar su evidencia o validar su firma.
`node_id`	string	El paso del flujo que la generó.
`status`	string	En qué punto del paso se encuentra el firmante: `intro`, `review`, `code`, `signing`, `signed` o `declined`. Solo `signed` indica que los documentos están firmados.
`verdict`	string	El resultado del paso: `Not Finished`, `Approved`, `In Review` o `Declined`. Una firma rechazada o fallida adopta el veredicto de su regla, y las reglas de estado personalizadas pueden cambiarlo.
`level`	string	`simple` (predeterminado) o `aes`. `qes` es un complemento que aún no está disponible.
`format`	string	`pdf` para una firma simple, `pades` para una firma avanzada (AES).
`profile`	string \| null	`PAdES-B-LT` una vez firmada una firma avanzada (AES); en caso contrario, `null`.
`signer`	object	Quién firmó. Consulta Firmante.
`identity_used`	object	La identidad verificada en la que se basa la firma. Consulta Firmante. Vacío en una firma simple sin identidad verificada.
`certificate`	object \| null	El certificado con el que se firmaron los documentos: `issuer`, `issued_to`, `serial`, `valid_from` y `valid_until`. `null` hasta que se firma, y siempre `null` en una firma simple.
`confirmation`	object	El código de un solo uso: `channel` (`email` o `sms`), `destination` (el contacto enmascarado al que se envió), `confirmed_at` y `attempts` (códigos introducidos, incluido el correcto). Una firma simple no tiene código, por lo que `channel` y `destination` son `null`.
`timestamp`	object \| null	El sello de tiempo RFC 3161 incluido en la firma, emitido por Didit: `time`, `qualified` (siempre `false` en AES) y `valid`. `null` hasta que se firma, y siempre `null` en una firma simple.
`documents`	array	Un elemento por documento. Consulta Documentos.
`adopted_signature`	object \| null	La firma y las iniciales que el firmante adoptó para los campos de firma e iniciales: `method` (`typed` o `drawn`), `font` (el estilo caligráfico de una firma escrita con el teclado, o `null` si es dibujada) y `adopted_at`. `null` hasta que el firmante adopta una.
`electronic_signature_consent_at`	string \| null	Cuándo aceptó el firmante, en la pantalla de revisión, firmar los documentos electrónicamente. Se establece cuando algún documento tiene campos.
`evidence_file`	string \| null	Ruta al PDF de evidencias de este firmante, una vez firmado.
`warnings`	array	Elementos `{ "code", "node_id" }` por cada advertencia generada.
`validation`	object \| null	La última comprobación criptográfica de los documentos firmados. Consulta Validar una firma de nuevo.
`declined_at`	string \| null	Cuándo rechazó el firmante.
`declined_action`	string	El `signature_declined_action` del paso: qué efecto tiene un rechazo en el veredicto.
`signed_at`	string \| null	Cuándo se firmaron los documentos.
`expires_at`	string	Cuándo deja de funcionar el enlace de firma.
`email_sent_at`	string \| null	Cuándo Didit envió al firmante una copia firmada por correo electrónico.
`email_unavailable_reason`	string \| null	Por qué no se envió ninguna copia por correo electrónico, cuando la solicitaste.
`ip_address`	string \| null	La dirección IP del firmante cuando solicitó su código.
`place`	string \| null	No se recopila. Siempre `null`, con `place_unavailable_reason: "not_collected"`.

Nunca consideres que un firmante ha firmado hasta que status sea signed. En una firma avanzada (AES), un certificado, un sello de tiempo o un signed_file con valor null significa que aún no hay firma. Una firma simple ya firmada tiene un signed_file, pero siempre tiene el certificado y el sello de tiempo en null.

Firmante

Campo	Descripción
`signer.name`	El nombre verificado del firmante, procedente de su verificación de identidad aprobada. En el nivel simple, es el nombre verificado de la sesión cuando lo hay; si no, el nombre que escribió el firmante, que no está verificado.
`signer.capacity`	`self` cuando una persona firma en su propio nombre (KYC), `company` cuando una persona clave firma en nombre de una empresa (KYB).
`signer.company`	El nombre de la empresa, en KYB.
`signer.role`	El cargo de la persona clave, tal como se declaró, en KYB.
`signer.roles`	Los roles estructurados de la persona clave, como `representative` o `authorized_signatory`, que la convirtieron en firmante. Son los roles declarados para la empresa, no una confirmación del registro.
`signer.identity_session_id`	La sesión de KYC que verificó al firmante. En KYB, la propia sesión de KYC de la persona clave. No aparece en una firma simple sin identidad verificada.
`identity_used.session_id`	Igual que `signer.identity_session_id`. `identity_used` está vacío en una firma simple sin identidad verificada, por lo que ninguno de sus campos está presente.
`identity_used.kyc_id`	La verificación de identidad de la que procede el nombre.
`identity_used.verified`	`true` cuando esa verificación de identidad se aprobó.
`identity_used.expected_name`	El nombre con el que debía coincidir el firmante. En KYB, el nombre declarado para la persona clave.

Documentos

Campo	Descripción
`id`, `uuid`	El documento. Úsalo para descargar el archivo firmado.
`title`, `file_name`	Tal como se subió o se envió.
`pages`, `size_bytes`	Del documento que firmó el firmante. En Word, del PDF convertido.
`sha256_original`	SHA-256 del documento tal como se le mostró al firmante.
`sha256_signed`	SHA-256 del PDF firmado, una vez firmado.
`status`	`signed`; `declined`; `not_signed` (abierto, no firmado); o `not_reached` (nunca abierto).
`opened_at`	Cuándo lo abrió el firmante por primera vez.
`read_at`, `read_to_end`	Cuándo llegó el firmante al final de un documento sin campos, si exiges leer hasta el final. Un documento con campos no lo necesita.
`consented_at`, `consent`	Cuándo aceptó el firmante un documento sin campos, si exiges consentimiento por documento, o cuándo completó los campos de un documento con campos.
`signed_file`	Ruta al PDF firmado, una vez firmado.
`mode`	`fields` para un documento con campos, `read_and_agree` para un documento sin ellos.
`source_format`	`pdf`, o `docx` si se trata de un documento de Word que Didit convirtió.
`conversion`	`null` en el caso de un PDF. En el caso de un documento de Word, `{ "from": "docx", "file_name", "sha256", "size_bytes", "converter" }`: tu archivo original, su SHA-256 y su tamaño, y la versión del conversor.
`fields`	Los campos del documento, con sus valores. Vacío en un documento sin campos.

Campos

Cada elemento de documents[].fields[] es un campo del documento, con su valor en la copia de este firmante:

Campo	Descripción
`key`	La clave del campo, la misma que usas en `sign.field_values`.
`type`, `role`, `label`, `required`	Tal como se colocaron en el documento.
`page`, `x`, `y`, `width`, `height`	Dónde se encuentra el campo, expresado como fracciones de la página tal como se muestra.
`value`	Una cadena para los campos `text`, `email`, `full_name`, `date_signed` y `data`, un booleano para una casilla de verificación y `true` para una firma o unas iniciales aplicadas. `null` cuando el campo está vacío.
`display_value`	El valor tal como se estampa en la página: las fechas en el `date_format` del campo, `Yes` o `No` para una casilla de verificación y `Signed` para una firma o unas iniciales.
`value_source`	De dónde procede el valor: `signer` (escrito, marcado o aplicado por el firmante), `identity` (la identidad verificada), `contact` (el correo electrónico o el teléfono verificados), `company` (la empresa verificada), `session` (el `vendor_data` de la sesión), `metadata` (el `metadata` de la sesión), `api` (tu `sign.field_values`) o `signing_time` (la fecha de firma).
`filled_at`	Cuándo se estableció el valor.
`image_url`	En una firma o unas iniciales, la ruta de la imagen aplicada, en formato PNG. Consulta Descargar una imagen de firma.
`value_unavailable_reason`	Por qué un campo que rellena Didit no tiene valor: `not_verified` (la identidad o el contacto no se verificaron), `not_applicable` (un campo de empresa en la firma de una persona a título propio), `not_provided` (la fuente no tiene valor) o `set_at_confirmation` (una fecha de firma antes de que el firmante confirme). En cualquier otro caso, `null`.

Descargar los documentos firmados

Usa las rutas de signed_file y evidence_file con tu clave de API. Cada ruta responde con el propio PDF.

# Signed PDF of one document
curl -L 'https://verification.didit.me/v3/session/{session_id}/signatures/{node_id}/documents/{document_id}/file/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -o agreement-signed.pdf

# Evidence PDF of one signer
curl -L 'https://verification.didit.me/v3/session/{session_id}/signatures/{node_id}/evidence/?signature_id={signature_id}' \
  -H 'x-api-key: YOUR_API_KEY' \
  -o signature-evidence.pdf

Ruta	Referencia
`GET .../documents/{document_id}/file/`	Descargar un documento firmado
`GET .../evidence/`	Descargar la evidencia de firma
`GET .../fields/{field_id}/image/`	Descargar una imagen de firma
`POST .../validate/`	Validar firmas

Antes de responder, Didit comprueba el archivo almacenado con su SHA-256 registrado. Si no coinciden, las rutas del PDF firmado y de la evidencia devuelven 409 y la ruta de la imagen devuelve 400, en todos los casos con signature_document_changed. Pasa siempre signature_id a la ruta de la evidencia cuando un paso de KYB tenga varios firmantes.

El PDF firmado

El PDF firmado contiene, en este orden:

Las páginas del documento que se mostró al firmante, con el valor de cada campo estampado donde lo colocaste.
La página de evidencia, salvo que hayas desactivado signature_evidence_page.
Solo en el nivel Advanced (AES), la firma PAdES, con el sello de tiempo RFC 3161 emitido por Didit y los datos de revocación necesarios para validarla en el futuro. Un PDF Simple termina después de la página de evidencia y no tiene firma digital, sello ni sello de tiempo.

En un PDF Advanced (AES), la firma abarca todos los bytes anteriores a ella, incluidos los valores de los campos y la página de evidencia. Cualquier cambio posterior en el archivo la invalida, y cualquier validador compatible con PAdES lo muestra. Los detalles de la firma identifican al firmante y hacen referencia a su sesión de identidad verificada y a la confirmación mediante código. Los valores de los campos pasan a formar parte del contenido de la página, no de campos de formulario, por lo que no se pueden editar después y cualquier visor de PDF los muestra. Una casilla de verificación marcada muestra una marca, y una sin marcar se deja tal como la dibujó el documento. Un recuadro de firma de más de 24 puntos de alto también recibe un pequeño texto bajo la firma: Signed with Didit · seguido de los primeros 8 caracteres del id de la firma. Didit añade los valores de los campos, la página de evidencia y la firma a continuación de los bytes del documento que se mostró al firmante. Ese documento es un prefijo exacto del archivo firmado, por lo que sha256_original se puede seguir comprobando con el PDF firmado.

El PDF de evidencia

El PDF de evidencia registra, para un firmante:

El nivel y el formato.
El nombre del firmante, la calidad en la que firma y, en KYB, la empresa.
La sesión de identidad verificada (solo Advanced (AES)).
La confirmación: canal, destino enmascarado y hora (solo Advanced (AES)).
La dirección IP del firmante.
Cada documento: título, número de páginas y SHA-256 del original. En un documento de Word, el nombre y el SHA-256 del archivo de Word, la versión del conversor y el SHA-256 del PDF.
La firma adoptada: escrita (con su estilo caligráfico) o dibujada, cuándo se adoptó, y las imágenes de la firma y de las iniciales.
Cada campo, por documento: su etiqueta, página y tipo, su valor (la imagen en el caso de una firma o unas iniciales), de dónde procede el valor (por ejemplo, Typed by the signer, Verified ID o Your API), cuándo se rellenó (UTC) y, si el valor lo escribió el firmante, su dirección IP en ese momento.
El consentimiento final: el texto que el firmante aceptó en la pantalla de revisión, y cuándo.
El SHA-256 de cada archivo firmado y, en Advanced (AES), el certificado (emitido a, emisor, número de serie y validez) y el sello de tiempo.

La página que se añade a cada PDF firmado tiene el mismo contenido sin la sección del certificado, porque se añade antes de aplicar la firma.

Validar una firma de nuevo

POST /v3/session/{session_id}/signatures/{node_id}/validate/ vuelve a leer cada PDF firmado del paso y comprueba su SHA-256. En una firma avanzada (AES), también valida la firma PAdES, su certificado, los datos de revocación y el sello de tiempo. Una firma simple no tiene firma digital, así que solo se comprueba la integridad del archivo. El resultado se guarda en validation y la respuesta devuelve el signatures[] actualizado. Envía signature_id para comprobar un solo firmante. Requiere write:sessions y, en la consola, corresponde al botón Validar de nuevo. Si un PDF firmado almacenado ya no coincide con su sha256_signed, se devuelve 400 con signature_document_changed. Hasta que los documentos estén firmados, validation es null. Si Didit no puede confirmar el resultado de la firma, validation es { "valid": null, "reason": "signature_provider_outcome_unknown", "checked_at" } y status se mantiene en signing hasta que se resuelva: trátalo como no firmado.

Campo de `validation.documents[]`	Descripción
`valid`	`true` cuando la firma y el sello de tiempo son válidos y confiables. En una firma simple, `true` cuando el archivo no ha cambiado.
`integrity`	`true` cuando el documento no ha cambiado desde la firma.
`trusted`	`true` cuando el certificado de firma se encadena a una raíz de confianza. `null` en una firma simple.
`revoked`	`true` cuando el certificado de firma se revocó. `null` en una firma simple.
`trusted_list`	`{ "status": "not_applicable", "reason": "aes_not_qualified" }` para AES. La comprobación de la lista de confianza de la UE (EU Trusted List) se aplica a las firmas cualificadas. Una firma simple devuelve `{ "status": "not_applicable", "reason": "simple_not_sealed" }`.
`certificate`, `timestamp`	Tal como aparecen en el archivo.

En el informe PDF

El informe PDF incluye una sección de firma con el firmante, la confirmación, el certificado, el sello de tiempo y los documentos con sus hashes. Cuando los documentos tienen campos, a continuación aparece una página E-signature · fields, con una tabla por documento: el valor de cada campo, las imágenes de la firma y de las iniciales, las horas y las fuentes. La sección de firma va después de Verificación bancaria en un informe KYC y después de Documentos en un informe KYB. Pasa pages=signature para imprimir solo esa sección.

Autenticación

Verificación

Monitorización

Plataforma

Informe de firma electrónica: referencia de signatures[]

Ejemplo

El objeto de firma

Firmante

Documentos

Campos

Descargar los documentos firmados

El PDF firmado

El PDF de evidencia

Validar una firma de nuevo

En el informe PDF

Relacionado

​Ejemplo

​El objeto de firma

​Firmante

​Documentos

​Campos

​Descargar los documentos firmados

​El PDF firmado

​El PDF de evidencia

​Validar una firma de nuevo

​En el informe PDF

​Relacionado

Ejemplo

El objeto de firma

Firmante

Documentos

Campos

Descargar los documentos firmados

El PDF firmado

El PDF de evidencia

Validar una firma de nuevo

En el informe PDF

Relacionado