Demande des résultats NIGO

Les vérifications exécutées, et contre quels champs, dépendent entièrement du type de document :

Demande de validation

Les deux paramètres reposent sur une exigence d'attachement, qui est imbriquée à l'intérieur d'un rôle. Définissez-les lorsque vous créez ou mettez à jour le rôle, ou lorsque vous créez le package.

{
  "id": "role1",
  "type": "SIGNER",
  "signers": [
    { "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe" }
  ],
  "attachmentRequirements": [
    {
      "id": "attachment-1",
      "name": "Proof of address",
      "description": "Upload a recent bank statement",
      "required": true,
      "attachmentType": "BANK_STATEMENT",
      "extractionEnabled": true
    }
  ]
}

POST ou PUT à cela, /aws/rest/services/packages/{packageId}/roles[/{roleId}]ou l'inclure dans la charge utile de création de paquet.

extractionEnabled est un booléen nullable : null et false sont équivalents, et tous deux signifient faux. Il est nullable de sorte qu'un champ omis ne peut jamais permettre accidentellement l'extraction — seul un explicite true le fait.

Erreurs de validation

La demande est rejetée si vous demandez quelque chose auquel le compte n'a pas droit :

La détection de falsification n'a pas de champ par condition. Elle est contrôlée uniquement par le paramètre d'authenticité du document au niveau du compte, et s'applique à chaque pièce jointe éligible sur le compte.

Récupération des résultats

GET /aws/rest/services/packages/{packageId}/attachment/verifications

Notez que le segment de chemin est attachment, singulier.

La réponse est un tableau nu, pas un objet avec un champ nommé. Il n'y a pas de pagination.

Ce point de terminaison nécessite des privilèges d'édition de transaction — expéditeur, propriétaire ou délégué. Les signataires reçoivent 403. Les résultats de validation ne sont exposés nulle part dans l'API orientée vers le signataire.

La classification est synchrone ; l'extraction est asynchrone. La classification s'achève pendant le téléchargement, donc classificationResult disponible dès le retour du téléchargement. L'extraction s'exécute ensuite, et son résultat apparaît à ce point de terminaison une fois terminé — jusqu'à ce moment-là, les éléments du fichier rapportent extractionStatus: "NOT_PERFORMED" avec un null reasonCode et un non extractionResult. Les résultats sont assemblés à chaque requête : le résultat d'extraction est récupéré depuis le service de validation et les vérifications de contenu sont évaluées à ce moment-là, donc lisez ce point de terminaison lorsque vous avez besoin des résultats actuels plutôt que de le mettre en cache.

Détection de la complétion

L'extraction est asynchrone, aucun événement n'annonce sa fin (voir Rappels et événements), et PACKAGE_ATTACHMENT se déclenche avant de se terminer — un client qui a besoin de résultats d'extraction doit donc relire ce point de terminaison jusqu'à ce que chaque fichier atteigne un état final.

Ce point n'est pas limité en débit, alors limitez-vous. Chaque appel récupère le résultat d'extraction actuel pour chaque fichier validé sur la transaction depuis le service de validation et réévalue les vérifications de contenu. Ne boucle pas de façon serrée. Recommandé : commencer sur le PACKAGE_ATTACHMENT rappel (par téléversement) ou sur SIGNER_COMPLETE (une fois le signataire terminé), relire au maximum toutes les 10 secondes par transaction — un appel couvre tous les fichiers de la transaction — et arrêter après 5 minutes, en considérant tout fichier encore sans état final comme indisponible. Ce sont des recommandations, pas des limites mesurées : il n'y a pas de limite publiée sur le temps d'extraction.

Décidez par fichier, à chaque lecture :

Si vous n'avez besoin que de la classification, il n'y a rien à attendre.

Forme de réponse

Chaque élément du tableau :

classificationResult:

extractionResult:

Lequel et reasonCode lire. Les deux apparaissent deux fois — sur l'élément tableau et à l'intérieur de . Lisez les champs au niveau de l'élément : ils sont toujours présents. Lorsque  est non nul, its  et  sont identiques à ceux de l'élément (l'élément les copie de lui), et it  est simplement  ne pas être . Lorsque  est , les champs au niveau de l'élément sont les seuls, et expliquent pourquoi il n'y a pas de résultat. Un cas limite : si le service de validation rapporte un statut que extractionStatus cette version ne connaît pas, la valeur imbriquée est  et l'élément rapporte .

Les champs nuls sont présents dans le JSON, non omis. Ne considérez pas la présence d'une clé comme une preuve qu'elle a une valeur. Inversement, de nouveaux champs peuvent être ajoutés dans les versions ultérieures — ignorez les clés que vous ne reconnaissez pas.

Exemple — un résultat réussi

[
  {
    "attachmentUuid": "attachment-1",
    "fileName": "statement-june",
    "fileId": "8842",
    "extension": "pdf",
    "classificationResult": {
      "documentUuid": "9f2c1d84-3b7e-4a15-9c2d-6e8f1a4b7c30",
      "documentType": "BANK_STATEMENT",
      "confidenceScore": 0.95,
      "confidenceLevel": "HIGH",
      "providerName": "bedrock",
      "failed": false,
      "errorCode": null,
      "failureMessage": null
    },
    "extractionResult": {
      "documentUuid": "9f2c1d84-3b7e-4a15-9c2d-6e8f1a4b7c30",
      "extractedFields": {
        "accountHolderName": "JANE DOE",
        "financialInstitutionName": "Bank of Example",
        "statementDate": "2026-06-30",
        "statementPeriodStart": "2026-06-01",
        "statementPeriodEnd": "2026-06-30"
      },
      "providerName": "bedrock",
      "verificationCheckResults": [
        {
          "ruleName": "data_completeness",
          "fields": [],
          "status": "PASS",
          "message": "esl.error.attachment_verification_check.data_completeness_pass"
        },
        {
          "ruleName": "date_validation",
          "fields": ["statementDate"],
          "status": "PASS",
          "message": "esl.error.attachment_verification_check.date_recent"
        }
      ],
      "extractionStatus": "COMPLETED",
      "reasonCode": null,
      "failureMessage": null,
      "preflight": {
        "checks": [
          {
            "check": "SOURCE",
            "status": "PASS",
            "messageKey": "esl.error.preflight_check.source_verified",
            "params": {}
          },
          {
            "check": "EDITS_AFTER_CREATION",
            "status": "PASS",
            "messageKey": "esl.error.preflight_check.no_edits_after_creation",
            "params": {}
          },
          {
            "check": "FILE_DATES",
            "status": "PASS",
            "messageKey": "esl.error.preflight_check.file_dates_consistent",
            "params": {}
          },
          {
            "check": "PERIOD_DATE",
            "status": "PASS",
            "messageKey": "esl.error.preflight_check.period_date_within",
            "params": {}
          }
        ],
        "verifiability": { "inputType": "VERIFIABLE_PDF" },
        "tier": "CLEAR"
      },
      "failed": false
    },
    "extractionStatus": "COMPLETED",
    "reasonCode": null,
    "typeMatch": true
  }
]

Exemple — le fichier n'a pas pu être classifié

[
  {
    "attachmentUuid": "attachment-1",
    "fileName": "photo",
    "fileId": "8843",
    "extension": "jpg",
    "classificationResult": {
      "documentUuid": "1a4b7c30-9f2c-4a15-8e6d-3b7e5c2d9f10",
      "documentType": null,
      "confidenceScore": 0.0,
      "confidenceLevel": null,
      "providerName": null,
      "failed": true,
      "errorCode": "esl.error.attachment_verification.image_too_blurry",
      "failureMessage": "Document is difficult to read"
    },
    "extractionResult": null,
    "extractionStatus": "NOT_PERFORMED",
    "reasonCode": "CLASSIFICATION_QUALITY_WARNING",
    "typeMatch": false
  }
]

Types de documents et champs d'extraction

Les types de documents suivants sont pris en charge. La colonne champs d'extraction liste toutes les clés pouvant apparaître extractedFields pour ce type. Les clés marquées (date) sont retournées sous forme ISO YYYY-MM-DD ; toutes les autres valeurs sont renvoyées telles qu'imprimées sur le document.

Deux champs sont contraints à un ensemble fixe de valeurs :

• utilityType — l'un des electric, gas, water, internet, mobile, other

• payFrequency — un des weekly, bi-weekly, monthly, undefined

taxYear est une chaîne simple, pas une date. Elle est retournée telle qu'imprimée sur le document.

Notez que la classification peut indiquer un document comme un type non reconnu, auquel documentType cas . "UNKNOWN"UNKNOWN n'est pas valide attachmentType et ne peut pas être demandé.

Traitement des champs extraits

extractedFields est clairsemée. Elle ne contient que les clés réellement trouvées et lisibles. Un champ absent du document, illisible, ou que l'extracteur a refusé de deviner est totalement omis de la carte — il n'est pas retourné comme null ou sous forme de chaîne vide.

Cela s'applique à toutes les clés, y compris celles requises par les vérifications. Votre code doit gérer toute clé manquante, et ne doit pas supposer que chaque clé listée pour un type de document sera présente dans chaque réponse.

Toutes les valeurs sont des chaînes de caractères.

• Les dates sont normalisées à ISO YYYY-MM-DD. Cette normalisation est effectuée par l'extracteur et contrainte par son schéma de sortie, mais elle n'est pas revalidée par la suite. Considérez une date ISO bien formée comme le cas attendu, et traitez une valeur qui ne parse pas plutôt que de supposer qu'elle le fera.

• Les montants monétaires sont retournés exactement tels qu'imprimés — par exemple "65000.00", "$75,000 per year", ou "120,000 00". Ils ne sont pas normalisés en chiffres. Analysez-les vous-même, de manière défensive.

• Tout le reste est rendu tel qu'imprimé sur le document.

Les données extraites sont produites par le service de validation et diffusées via ce point de terminaison. Elles ne sont pas modifiables via l'API, et il n'y a pas de point de terminaison pour corriger ou remplacer une valeur extraite.

Résultats des vérifications

extractionResult.verificationCheckResults est un tableau de résultats de vérification, présent uniquement à l'issue de l'extraction. Chaque élément :

Il y a quatre vérifications. Lequel d'entre eux s'exécute, et contre quels champs, est déterminé entièrement par le type de document.

Toutes les clés de message sont préfixées esl.error.attachment_verification_check.

Une date manquante ou incalculable produit WARNINGtoujours , jamais FAIL. Seule une date lue avec succès et jugée hors de portée produit FAIL. Ne considérez WARNING pas comme une défaillance douce du document — dans la plupart des cas, cela signifie que la vérification n'a pas pu être effectuée.

Configuration par type :

Notez que data_completeness certains champs que l'extracteur considère comme optionnels — payDate sur une fiche de paie et totalIncome sur une déclaration fiscale en sont des exemples. Un data_completeness défaut de nommer ces champs signifie qu'ils n'ont pas été trouvés sur le document, pas qu'il y a eu un problème.

« Aucun résultat » indique

Un résultat vide n'est jamais une erreur. 204 Cela signifie qu'aucune validation n'a été validée sur cette transaction, qui est l'état normal pour une transaction n'utilisant pas cette fonctionnalité.

Conciliez ce tableau avec les fichiers que vous savez avoir été téléchargés. Chaque fichier téléchargé est listé dans attachmentRequirements[].files[] le rôle. Un fichier dans cette liste mais absent de ce tableau n'a jamais été validé — le service était inaccessible lors de son téléchargement, ou la validation n'était pas configurée pour ses besoins à ce moment-là. Considérez cela comme un état explicitement non validé et montrez-le ainsi : relire ce point de terminaison ne le modifiera pas, et la seule façon de valider le fichier est que le signataire le remplace. Ne le confondez pas avec un fichier présent avec extractionStatus: NOT_PERFORMED un null reasonCode et — résolvez-le avec l'arbre de décision sous reasonCode.

Marquez comme révisé via l'API

PUT    /aws/rest/services/packages/{packageId}/attachment/{attachmentId}/file/{fileId}/reviewed
DELETE /aws/rest/services/packages/{packageId}/attachment/{attachmentId}/file/{fileId}/reviewed

PUTmarque le fichier comme examiné ;DELETE annule-le. Aucun ne prend de corps de requête. Les deux reviennent 200 avec la mise à jour AttachmentFile, et nécessitent tous deux des privilèges d'édition de transaction. A fileId qui n'appartient pas aux retours 404 error.validation.AttachmentFileNotFounddonnés attachmentId .

Le nom du champ API est reviewed, et la fonctionnalité est Marquez comme Examiné ; la piste d'audit l'enregistre comme Marqué comme Vérifié. Pour ce que l'action signifie et ne fait pas — toujours disponible, ne relance jamais ni ne réactive les résultats, ne notifie jamais le signataire — voir Marquer comme Examiné dans le sujet Expéditeur UI.

Cinq champs sur AttachmentFile portent l'état. Ils sont également renvoyés partout AttachmentRequirement.files[] où un rôle ou un package est lu, vous pouvez donc voir l'état de révision sans appeler le point de terminaison des vérifications :

• Marquage définit reviewed, reviewedBy et reviewedAt, et efface unreviewedBy et unreviewedAt.

• Défaire des ensembles reviewed de false et records unreviewedBy et unreviewedAt, tout en préservant l'original reviewedBy et reviewedAt comme l'histoire.

• Annuler un fichier qui n'a jamais été marqué, ou qui n'est déjà pas marqué, est une opération interdite qui renvoie l'état actuel.

• Remplacer ou supprimer un fichier supprime son état de relecture.

Trace d'audit

Marquer un fichier comme révisé et le retirer produit les entrées Mark as Verified d'audit et Undo Verification — les noms des traces d'audit pour ces actions — aux côtés des données existantes Upload File Attachment et Download File Attachment, toutes récupérables depuis GET /aws/rest/services/packages/{packageId}/audit. Aucun résultat de classification, valeur extraite, résultat de vérification ou constatation d'intégrité ne produit une entrée d'audit — si vous avez besoin d'un enregistrement durable de ce que la validation a rapportée à un moment donné, capturez-la vous-même depuis le point de terminaison de vérification.