Relatório de assinatura eletrónica: signatures[]

Cada passo de Assinatura eletrónica produz um resultado por signatário. Encontra-o como um item de signatures[] em:

GET /v3/session/{sessionId}/decision/, para sessões de Verificação de utilizadores (KYC) e Verificação de empresas (KYB).
Na decision dos webhooks de sessão V3, enviados quando a sessão está Approved, Declined, In Review ou Abandoned.
No separador Assinatura da sessão na consola e na secção de assinatura do relatório PDF.

signatures só está presente na decisão quando o fluxo tem um passo de Assinatura eletrónica. É uma matriz vazia até que um signatário chegue ao passo. Um passo de KYC tem um item; um passo de KYB tem um item por signatário.

Exemplo

{
  "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"
    }
  ]
}

O objeto de assinatura

Campo	Tipo	Descrição
`id`	string (UUID)	A assinatura do signatário. Passe-o como `signature_id` para descarregar o respetivo comprovativo ou validar a sua assinatura.
`node_id`	string	O passo do fluxo que a produziu.
`status`	string	Onde o signatário se encontra no passo: `intro`, `review`, `code`, `signing`, `signed` ou `declined`. Apenas `signed` significa que os documentos estão assinados.
`verdict`	string	O resultado do passo: `Not Finished`, `Approved`, `In Review` ou `Declined`. Uma assinatura recusada ou com falha assume o veredito da sua regra, e regras de estado personalizadas podem alterá-lo.
`level`	string	`simple` (predefinição) ou `aes`. `qes` é um suplemento que ainda não está disponível.
`format`	string	`pdf` para uma assinatura Simples, `pades` para Avançada (AES).
`profile`	string \| null	`PAdES-B-LT` assim que uma assinatura Avançada (AES) for assinada; caso contrário, `null`.
`signer`	object	Quem assinou. Consulte Signatário.
`identity_used`	object	A identidade verificada na qual a assinatura se baseia. Consulte Signatário. Vazio para uma assinatura Simples sem identidade verificada.
`certificate`	object \| null	O certificado com o qual os documentos foram assinados: `issuer`, `issued_to`, `serial`, `valid_from` e `valid_until`. `null` até ser assinado e sempre `null` para uma assinatura Simples.
`confirmation`	object	O código de utilização única: `channel` (`email` ou `sms`), `destination` (o contacto mascarado para onde foi enviado), `confirmed_at` e `attempts` (códigos introduzidos, incluindo o correto). Uma assinatura Simples não tem código, pelo que `channel` e `destination` são `null`.
`timestamp`	object \| null	O carimbo de data/hora RFC 3161 na assinatura, emitido pela Didit: `time`, `qualified` (sempre `false` para AES) e `valid`. `null` até ser assinado e sempre `null` para uma assinatura Simples.
`documents`	array	Um item por documento. Consulte Documentos.
`adopted_signature`	object \| null	A assinatura e as iniciais que o signatário adotou para os campos de assinatura e iniciais: `method` (`typed` ou `drawn`), `font` (o estilo caligráfico de uma assinatura digitada, ou `null` quando desenhada) e `adopted_at`. `null` até o signatário adotar uma.
`electronic_signature_consent_at`	string \| null	Quando o signatário concordou, no ecrã de revisão, em assinar eletronicamente os documentos. Definido quando qualquer documento tiver campos.
`evidence_file`	string \| null	Caminho para o PDF de prova deste signatário, assim que estiver assinado.
`warnings`	array	Itens `{ "code", "node_id" }` para cada aviso gerado.
`validation`	object \| null	A última verificação criptográfica dos documentos assinados. Consulte Validar novamente uma assinatura.
`declined_at`	string \| null	Quando o signatário recusou.
`declined_action`	string	A `signature_declined_action` do passo: o que uma recusa faz ao veredito.
`signed_at`	string \| null	Quando os documentos foram assinados.
`expires_at`	string	Quando a ligação de assinatura deixa de funcionar.
`email_sent_at`	string \| null	Quando a Didit enviou uma cópia assinada por e-mail ao signatário.
`email_unavailable_reason`	string \| null	Motivo pelo qual nenhuma cópia foi enviada por e-mail, quando solicitou uma.
`ip_address`	string \| null	O endereço IP do signatário quando solicitou o código.
`place`	string \| null	Não recolhido. Sempre `null`, com `place_unavailable_reason: "not_collected"`.

Nunca considere que um signatário assinou até que status seja signed. Numa assinatura Avançada (AES), um certificado, carimbo de data/hora ou signed_file com valor null significa que ainda não existe assinatura. Uma assinatura Simples assinada tem um signed_file, mas tem sempre um certificado e carimbo de data/hora null.

Signatário

Campo	Descrição
`signer.name`	O nome verificado do signatário, a partir da sua verificação de identidade aprovada. No nível Simples, é o nome da sessão verificada quando existir; caso contrário, é o nome introduzido pelo signatário, que não é verificado.
`signer.capacity`	`self` quando uma pessoa assina por si própria (KYC), `company` quando uma pessoa-chave assina por uma empresa (KYB).
`signer.company`	O nome da empresa, para KYB.
`signer.role`	A designação da pessoa-chave, conforme declarada, para KYB.
`signer.roles`	As funções estruturadas da pessoa-chave, tais como `representative` ou `authorized_signatory`, que a qualificaram como signatária. Estas são as funções declaradas para a empresa, e não uma confirmação de registo.
`signer.identity_session_id`	A sessão de KYC que verificou o signatário. Para KYB, a própria sessão de KYC da pessoa-chave. Ausente para uma assinatura Simples sem identidade verificada.
`identity_used.session_id`	Igual a `signer.identity_session_id`. `identity_used` está vazio para uma assinatura Simples sem identidade verificada, pelo que nenhum dos seus campos está presente.
`identity_used.kyc_id`	A verificação de identidade da qual o nome foi extraído.
`identity_used.verified`	`true` quando essa verificação de identidade foi aprovada.
`identity_used.expected_name`	O nome ao qual o signatário tinha de corresponder. Para KYB, o nome declarado para a pessoa-chave.

Documentos

Campo	Descrição
`id`, `uuid`	O documento. Utilize-o para descarregar o ficheiro assinado.
`title`, `file_name`	Conforme carregado ou enviado.
`pages`, `size_bytes`	Do documento que o signatário assinou. Para o Word, do PDF convertido.
`sha256_original`	SHA-256 do documento conforme apresentado ao signatário.
`sha256_signed`	SHA-256 do PDF assinado, assim que estiver assinado.
`status`	`signed`; `declined`; `not_signed` (aberto, não assinado); ou `not_reached` (nunca aberto).
`opened_at`	Quando o signatário o abriu pela primeira vez.
`read_at`, `read_to_end`	Quando o signatário chegou ao fim de um documento sem campos, caso exija a leitura até ao fim. Um documento com campos não necessita disto.
`consented_at`, `consent`	Quando o signatário aceitou um documento sem campos, caso exija consentimento por documento, ou preencheu os campos de um documento com campos.
`signed_file`	Caminho para o PDF assinado, assim que estiver assinado.
`mode`	`fields` para um documento com campos, `read_and_agree` para um documento sem campos.
`source_format`	`pdf`, ou `docx` para um documento Word convertido pela Didit.
`conversion`	`null` para um PDF. Para um documento Word, `{ "from": "docx", "file_name", "sha256", "size_bytes", "converter" }`: o seu ficheiro original, o respetivo SHA-256 e tamanho, e a versão do conversor.
`fields`	Os campos no documento, com os respetivos valores. Vazio para um documento sem campos.

Campos

Cada item de documents[].fields[] é um campo do documento, com o respetivo valor na cópia do signatário:

Campo	Descrição
`key`	A chave do campo, a mesma que utiliza em `sign.field_values`.
`type`, `role`, `label`, `required`	Conforme posicionados no documento.
`page`, `x`, `y`, `width`, `height`	Onde o campo se localiza, em frações da página tal como exibida.
`value`	Uma cadeia de carateres para campos `text`, `email`, `full_name`, `date_signed` e `data`, um booleano para uma caixa de seleção, e `true` para uma assinatura ou rubrica aplicada. `null` quando o campo está vazio.
`display_value`	O valor tal como é gravado na página: datas no formato `date_format` do campo, `Yes` ou `No` para uma caixa de seleção, e `Signed` para uma assinatura ou rubrica.
`value_source`	A origem do valor: `signer` (digitado, assinalado ou aplicado pelo signatário), `identity` (o documento de identificação verificado), `contact` (o e-mail ou telefone verificado), `company` (a empresa verificada), `session` (o `vendor_data` da sessão), `metadata` (os `metadata` da sessão), `api` (os seus `sign.field_values`) ou `signing_time` (a data de assinatura).
`filled_at`	Quando o valor foi definido.
`image_url`	Para uma assinatura ou rubrica, o caminho da imagem aplicada, um PNG. Consulte Descarregar a imagem da assinatura.
`value_unavailable_reason`	O motivo pelo qual um campo preenchido pela Didit não tem valor: `not_verified` (a identidade ou o contacto não foram verificados), `not_applicable` (um campo de empresa na assinatura da própria pessoa), `not_provided` (a origem não tem valor) ou `set_at_confirmation` (uma data de assinatura anterior à confirmação pelo signatário). Caso contrário, `null`.

Descarregar os documentos assinados

Utilize os caminhos em signed_file e evidence_file com a sua chave de API. Cada rota responde com o próprio 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

Rota	Referência
`GET .../documents/{document_id}/file/`	Descarregar um documento assinado
`GET .../evidence/`	Descarregar a evidência da assinatura
`GET .../fields/{field_id}/image/`	Descarregar uma imagem de assinatura
`POST .../validate/`	Validar assinaturas

Antes de responder, a Didit compara o ficheiro armazenado com o respetivo SHA-256 registado. Se divergirem, as rotas do PDF assinado e da evidência devolvem 409 e a rota da imagem devolve 400, cada uma com signature_document_changed. Transmita sempre o signature_id para a rota da evidência quando um passo de KYB tiver múltiplos signatários.

O PDF assinado

O PDF assinado contém, por ordem:

As páginas do documento que foram apresentadas ao signatário, com o valor de cada campo gravado no local onde o posicionou.
A página de evidência, a menos que tenha desativado a opção signature_evidence_page.
Apenas para a assinatura avançada (AES), a assinatura PAdES, com o carimbo de data/hora RFC 3161 emitido pela Didit e os dados de revogação necessários para a validar no futuro. Um PDF simples termina após a página de evidência e não contém assinatura digital, selo nem carimbo de data/hora.

Num PDF avançado (AES), a assinatura cobre todos os bytes anteriores, incluindo os valores dos campos e a página de evidência. Alterar qualquer elemento no ficheiro posteriormente invalida-o, e qualquer validador compatível com PAdES apresentará esse facto. Os detalhes da assinatura identificam o signatário e referenciam a respetiva sessão de identidade verificada e a confirmação por código. Os valores dos campos passam a fazer parte integrante do conteúdo da página e não de campos de formulário, pelo que não podem ser editados posteriormente e são visíveis em qualquer leitor de PDF. Uma caixa de seleção assinalada apresenta uma marca de seleção, e uma que não foi assinalada é mantida conforme desenhada no documento. Uma caixa de assinatura com mais de 24 pontos de altura inclui também uma pequena legenda sob a assinatura: Signed with Didit · seguida dos primeiros 8 carateres do id da assinatura. A Didit adiciona os valores dos campos, a página de evidência e a assinatura a seguir aos bytes do documento que foi apresentado ao signatário. Esse documento é um prefixo exato do ficheiro assinado, pelo que o sha256_original ainda pode ser verificado em relação ao PDF assinado.

O PDF de evidência

O PDF de evidência regista, para um determinado signatário:

O nível e o formato.
O nome do signatário, a qualidade em que assina e, para KYB, a empresa.
A sessão de identidade verificada (apenas para Advanced (AES)).
A confirmação: canal, destino mascarado e hora (apenas para Advanced (AES)).
O endereço IP do signatário.
Cada documento: título, número de páginas e SHA-256 do original. Para um documento Word, o nome e o SHA-256 do ficheiro Word, a versão do conversor e o SHA-256 do PDF.
A assinatura adotada: digitada (com o respetivo estilo de caligrafia) ou desenhada, quando foi adotada, e as imagens da assinatura e da rubrica.
Cada campo, por documento: a etiqueta, página e tipo, o respetivo valor (a imagem para uma assinatura ou rubrica), a origem do valor (por exemplo, Digitado pelo signatário, Documento de identificação verificado ou A sua API), quando foi preenchido (UTC) e, para um valor digitado pelo signatário, o respetivo endereço IP nesse momento.
O consentimento final: o texto que o signatário aceitou no ecrã de revisão e o momento em que o fez.
O SHA-256 de cada ficheiro assinado e, para a assinatura avançada (AES), o certificado (emitido para, entidade emissora, número de série e validade) e o carimbo de data/hora.

A página anexada a cada PDF assinado contém o mesmo conteúdo, exceto a secção do certificado, uma vez que a página é adicionada antes de a assinatura ser aplicada.

Validar novamente uma assinatura

O endpoint POST /v3/session/{session_id}/signatures/{node_id}/validate/ relê cada PDF assinado do passo e verifica o respetivo SHA-256. No caso de uma assinatura Avançada (AES), também valida a assinatura PAdES, o respetivo certificado, os dados de revogação e o carimbo de data/hora. Uma assinatura Simples não possui assinatura digital, pelo que a verificação incide unicamente na integridade do ficheiro. Guarda o resultado em validation e devolve o array signatures[] atualizado. Envie signature_id para verificar um único signatário. Requer write:sessions e, na consola, corresponde ao botão Validar novamente. Um PDF assinado armazenado que já não coincida com o respetivo sha256_signed devolve 400 com signature_document_changed. Até os documentos serem assinados, validation é null. Se a Didit não conseguir confirmar o resultado da assinatura, validation fica com { "valid": null, "reason": "signature_provider_outcome_unknown", "checked_at" } e status mantém-se em signing até estar resolvido: trate-o como não assinado.

Campo de `validation.documents[]`	Descrição
`valid`	`true` quando a assinatura e o carimbo de data/hora são ambos válidos e fidedignos. No caso de uma assinatura Simples, `true` quando o ficheiro permanece inalterado.
`integrity`	`true` quando o documento não foi alterado desde a assinatura.
`trusted`	`true` quando a cadeia do certificado de assinatura termina numa raiz de confiança. `null` no caso de uma assinatura Simples.
`revoked`	`true` quando o certificado de assinatura foi revogado. `null` no caso de uma assinatura Simples.
`trusted_list`	`{ "status": "not_applicable", "reason": "aes_not_qualified" }` para AES. A verificação da EU Trusted List aplica-se a assinaturas qualificadas. Uma assinatura Simples devolve `{ "status": "not_applicable", "reason": "simple_not_sealed" }`.
`certificate`, `timestamp`	Tal como encontrados no ficheiro.

No relatório em PDF

O relatório em PDF imprime uma secção de assinatura com o signatário, a confirmação, o certificado, o carimbo de data/hora e os documentos com os respetivos hashes. Quando os documentos contêm campos, segue-se uma página Assinatura eletrónica · campos, com uma tabela por documento: o valor de cada campo, as imagens da assinatura e das rubricas, as horas e as fontes. A secção de assinatura surge após a verificação bancária num relatório de KYC e após Documentos num relatório de KYB. Transmita pages=signature para imprimir apenas essa secção.

Autenticação

Verificação

Monitorização

Plataforma

Relatório de assinatura eletrónica: signatures[]

Exemplo

O objeto de assinatura

Signatário

Documentos

Campos

Descarregar os documentos assinados

O PDF assinado

O PDF de evidência

Validar novamente uma assinatura

No relatório em PDF

Relacionados

​Exemplo

​O objeto de assinatura

​Signatário

​Documentos

​Campos

​Descarregar os documentos assinados

​O PDF assinado

​O PDF de evidência

​Validar novamente uma assinatura

​No relatório em PDF

​Relacionados

Exemplo

O objeto de assinatura

Signatário

Documentos

Campos

Descarregar os documentos assinados

O PDF assinado

O PDF de evidência

Validar novamente uma assinatura

No relatório em PDF

Relacionados