io.github.g-digital-by-Garrigues/ead-enterprise-suite

Activates a signature request, transitioning from DRAFT to ACTIVE and sending signing invitations to all signatories. Do NOT call this immediately after uploading files. Activation preconditions: request is DRAFT; at least one SIGNATORY exists; every document has been uploaded to its presigned URL; backend processing has had time to complete for every uploaded document (use processed/READY_TO_SIGN from signature_request_get when exposed; otherwise wait after the successful PUT); and PDF documents have signature coordinates set for every required signatory. INTERPOSITION may send a simple signing link, including WhatsApp when available/configured; ADVANCED uses phonePrefix/phoneNumber for OTP and currently does not support WhatsApp delivery. IRREVERSIBLE: cannot add documents or participants after activation. ASYNC: after activation, poll signature_request_get until status is ACTIVE, then use signature_document_signatory_list with documentId to monitor each signatory, or signature_document_list for the request's documents and their aggregate signatoryStatusStats; call signature_certificate_get only after the document is SIGNED.

Assigns one or more validators to a specific signatory in a signature request. The validator must approve before the signatory can sign. Requires: signature_participant_create (validator) → validatorId in validatorIds array, signature_participant_create (signatory) → signatoryId, signature_request_create → requestId, case_file_create → caseFileId.

Creates a new case file — the top-level container for all related operations (evidence, notifications, signatures, dossiers). Call this first before any other operation. Generate a UUID v4 for `id`. Returns caseFileId needed for all subsequent calls.

Deletes a case file and everything filed inside it — evidence groups, dossiers, notifications and their certificates. Irreversible, with no confirmation step and no recycle bin. Requires: caseFileId. Returns no body (HTTP 204); confirm with case_file_list. Do not call it to 'clean up' unless the user asked for that case file to be destroyed.

Retrieves details of a specific case file. Requires: caseFileId. Use to verify a case file exists before creating evidence groups, dossiers, or signature requests.

Lists all case files in your EAD Enterprise Suite account. Pass userId (from session_login or session_info) to scope results to your account. Returns paginated list with IDs, names, and status.

Certifies a dossier, generating a tamper-evident PDF and locking all linked evidence. Requires: dossier_create → dossierId, dossier_evidence_link (evidence linked), case_file_create → caseFileId. ASYNC: transitions DRAFT → CERTIFYING → CERTIFIED. Poll dossier_list until dossierId status === CERTIFIED.

Creates a dossier to aggregate certified evidence groups into a single tamper-evident PDF. Requires: case_file_create → caseFileId. Evidence groups must be in CLOSED status before linking. Generate a UUID v4 string for `id`. Returns dossierId. After creation, link evidence with dossier_evidence_link, then certify with dossier_certify.

Deletes a dossier. Available in DRAFT status (to discard before certification) or in CERTIFIED status (to permanently remove the certified dossier). Irreversible. Requires: caseFileId and dossierId.

Returns the download URL for the certified dossier PDF. Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId.

Removes an evidence item from a dossier. Only available while dossier is in DRAFT status. Requires: caseFileId, dossierId, evidenceId.

Retrieves details of a specific evidence item linked to a dossier. Requires: caseFileId, dossierId, evidenceId.

Links evidence items from a sealed group to a dossier. Requires: dossier_create → dossierId, evidence_seal (CLOSED), case_file_create → caseFileId. Pass the ids array of evidence UUIDs. Can be called multiple times for evidence from different case files.

Lists the evidence items linked to ONE evidence group of a dossier. Requires: caseFileId, dossierId AND dossierEvidenceGroupId — all three are mandatory. For every evidence item in the dossier regardless of group, use dossier_evidence_list_by_dossier instead. Supports filter, order and page.

Lists every evidence item linked to a dossier, across all of its evidence groups. Requires: caseFileId and dossierId. This is the dossier-wide view; dossier_evidence_list is the narrower per-group one and additionally needs a dossierEvidenceGroupId. Supports filter, order and page. Returns { data, meta.totalElements }.

Lists evidence items available to be linked to a dossier (CLOSED groups not yet linked). Requires: caseFileId and dossierId.

Retrieves full details of a specific dossier including status, linked evidence, and download URLs. Requires: caseFileId and dossierId.

Creates AND certifies a dossier from a single sealed evidence group in one call (express path). Requires: evidence_seal (CLOSED), case_file_create → caseFileId, evidence_group_create → evidenceGroupId. Generate a UUID v4 string for `id`. Returns dossierId with CERTIFYING status → poll until CERTIFIED.

Lists all dossiers in a case file. Requires: caseFileId. Returns paginated list with IDs, names, status, and creation dates. Use to monitor certification progress — poll until status: CERTIFIED.

Lists every dossier belonging to a user, across all of their case files. Requires: userId (from session_login or session_info). Use this when you do not know which case file a dossier is in; use dossier_list when you already have a caseFileId. Supports filter, order and page. Returns { data, meta.totalElements }.

Returns the download URL for the full dossier package (PDF + evidence files). Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId.

Returns an HTML preview URL of a dossier before certification. Requires: caseFileId and dossierId.

Lists available dossier templates. No prerequisites. Returns template IDs and their translations per language. Use the returned id as dossierTemplateId in dossier_create.

Updates the metadata of an existing dossier. Requires: dossier_create → dossierId, caseFileId. Only available while dossier is in DRAFT status.

Updates the visibility (public/private) of a certified dossier. Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId.

Registers a NEW evidence record inside an evidence group. Requires: evidence_group_create → evidenceGroupId, case_file_create → caseFileId. Generate a UUID v4 for `id`. Compute the SHA-256 hex hash of the file BEFORE calling. Normal INTERNAL flow: call evidence_create with custodyType INTERNAL and NO fileUrl; the API returns uploadFileUrl, a presigned S3 URL. You MUST PUT the exact file bytes to uploadFileUrl, then verify with evidence_get/evidence_list, and ONLY THEN call evidence_seal. Do not seal an evidence group until every INTERNAL evidence file has been uploaded. Convenience flow: if you pass `fileUrl` (public HTTPS, no redirects, under 1 GiB), this tool downloads that URL and PUTs the bytes to uploadFileUrl for you. EXTERNAL flow: use custodyType EXTERNAL only when you intentionally register hash-only evidence; still generate a fresh UUID for each evidence. If an INTERNAL evidence creation/upload failed and you want to retry as EXTERNAL, create a NEW evidence id; do not reuse an id whose outcome is unknown. WARNING: the API sometimes returns {code:'EvidenceCreateError'} even when the evidence was successfully persisted — always verify with evidence_list before retrying.

Retrieves a specific evidence record. Requires: evidence_create → evidenceId, evidence_group_create → evidenceGroupId, case_file_create → caseFileId. Returns status (COMPLETED|IN_PROCESS|ERROR), hash, and tspTimestamp when certified.

Creates an evidence group inside a case file. Requires: case_file_create → caseFileId. Generate a UUID v4 for `id`. Set evidenceType to FILE, PHOTO, VIDEO, or WEB_PLUGIN. Returns evidenceGroupId. One group can contain multiple evidence records.

Lists all evidence groups in a case file with their current status (OPEN, CLOSING, CLOSED). Use to find an existing group or check which groups are ready for sealing. Requires: caseFileId.

Lists all evidence records in a specific evidence group. Requires: caseFileId and evidenceGroupId. Returns paginated list with IDs, titles, status, and timestamps.

Seal and certify an evidence group. Closes the group to new additions and triggers async timestamping. Returns immediately — the group transitions OPEN → CLOSING → CLOSED. Poll evidence_group_list until status is CLOSED before linking to a dossier.

Uploads a local file as evidence in one step: computes its SHA-256, registers the evidence record (custodyType INTERNAL = EAD stores the file), and uploads the bytes to S3 — no manual hashing or PUT needed. Internally this follows the required EAD sequence: create INTERNAL evidence → receive uploadFileUrl (presigned S3 URL) → PUT file bytes → return uploaded:true. Requires: case_file_create → caseFileId, evidence_group_create → evidenceGroupId. Provide EXACTLY ONE of `filePath` (absolute local path, stdio/local mode only) or `contentBase64` (base64-encoded file content, ~10 MB max). Use evidence_upload when the file is on the local machine; use evidence_create when you already have the SHA-256 hash, need to inspect/use uploadFileUrl manually, or have a public fileUrl. After this tool succeeds, verify with evidence_get/evidence_list and only then call evidence_seal. If this tool fails before returning an evidence id, check evidence_list before retrying; if retrying manually, use evidence_create with a fresh UUID. Local files must be under 1 GiB.

Retrieves the signed identity-verification contract for one completed verification. Requires: verificationId — the id you generated for id_verification_video_create, or an id from id_verification_list. NOTE: the OpenAPI specification declares a 200 response with NO body for this operation, so the exact payload is undeclared and has not been observed against a working deployment; inspect what comes back rather than assuming a particular field. PERMIT-GATED: returns 403 with code NoIdVerificationsPermit when profile_get reports permit.idVerifications === false. Signing the contract requires two live OTPs and is deliberately not exposed as a tool.

Lists the identity verifications belonging to a user, with the outcome of each. Requires: userId (from profile_get). Items are { id, email, name, firstSurname, secondSurname, status, identificationType, createdAt, createdBy, rejectedReason, rejectedContext }, so this is where you read whether a verification succeeded and, when it did not, why. Supports filter, order and page. This is the only way to observe an id_verification_video_create, which returns no body. PERMIT-GATED: returns 403 with code NoIdVerificationsPermit when profile_get reports permit.idVerifications === false.

Starts a REMOTE VIDEO identity verification for one person: the platform contacts them and runs the identification session. Requires: id (UUID v4 you generate), name, firstSurname, email, phonePrefix and phoneNumber. phonePrefix must include the leading + (for example '+34'). secondSurname is optional. Returns HTTP 201 with NO body, so keep the id you generated — it is the verificationId, and id_verification_list is the only way to read the outcome. PERMIT-GATED: call profile_get first and check permit.idVerifications; if it is false every call here returns 403 with code NoIdVerificationsPermit and no argument change will help, so report it rather than retrying. Presential (in-person) identity verification is deprecated upstream and deliberately not exposed.

Finalize a multipart evidence upload and register the evidence in the group. Returns immediately — the evidence transitions asynchronously to COMPLETED. Poll evidence_list until status is COMPLETED before sealing the group.

Reports how much of a large evidence upload the platform has actually received. Requires: caseFileId, evidenceGroupId and the evidence id. Returns fileName, totalSizeMB, chunkSizeMB and biggestUploadedOffset — compare biggestUploadedOffset against totalSizeMB to decide whether every part landed before calling large_evidence_upload_complete. Use it to resume or diagnose a stalled upload.

Performs the large_evidence_upload_initiate operation against the GoCertius API. Review the API documentation for full field details.

Returns { documentUrl } for the certificate PDF on its own, WITHOUT the attachments. Requires certificateId, receiverId, notificationRequestId and caseFileId. Wait until the certificate is CERTIFIED: generation is asynchronous and the first call can 404 or come back empty while it is still CERTIFYING, so poll a few times with a bounded retry rather than hammering it. If you want the attachments bundled in, use notification_certificate_package_url instead.

Creates or retrieves a PDF certificate for a specific notification receiver. Requires notification_request_send and notification_receiver_add. Generate a UUID v4 for `id` the first time and reuse that id when polling. This tool is idempotent: it first lists existing certificates for the receiver and, if `id` already exists, returns it instead of creating it again. If the certificate status is CERTIFIED, the response includes documentUrl when available. If it is CERTIFYING, poll this same tool with the same id.

Lists the delivery certificates already generated for one recipient, so you can reuse one instead of generating a duplicate. Requires receiverId, notificationRequestId and caseFileId. Returns per certificate: id, status (DRAFT, CERTIFYING, CERTIFIED), language, createdAt, certifiedAt, `partial` — whether it is an intermediate certificate issued before the recipient finished responding — and `embeddedDocuments`. Do not read `embeddedDocuments` as "the package contains the attachments": in a tested run it was false on a notification that had an attachment, and notification_certificate_package_url still returned a ZIP carrying that attachment. Once a certificate is CERTIFIED, download it with notification_certificate_document_url (the certificate alone) or notification_certificate_package_url (a ZIP that also carries the attachments).

Returns { packageUrl } for a ZIP containing the certificate AND the notification's attachments — the "with annexes" form. There is no separate preview flag anywhere in the API: the package carries the annexes, the document is the certificate alone. Requires certificateId, receiverId, notificationRequestId and caseFileId. Same preconditions as notification_certificate_document_url — wait for CERTIFIED, and expect the first call to fail while generation is still running.

Attaches a document to a notification. Two steps: this call registers the file and returns { url }, a presigned upload URL, and you then PUT the raw bytes to that URL with an x-amz-checksum-sha256 header. Generate a UUID v4 for `id`, and compute the file's SHA-256 hex hash BEFORE calling — it goes in `hash`. ORDER MATTERS AND GETTING IT WRONG FAILS THE SEND: add every document BEFORE adding recipients, and wait until each document reaches READY_TO_SEND (poll notification_document_list; roughly 8 seconds) before calling notification_request_send. Attaching after recipients, or sending while a document is still PENDING, returns 409/404 NOTIFICATION_NOT_FOUND. The maximum number of attachments is a per-subscription setting rather than a fixed API limit, so do not assume a number. Attachments can be bundled into the delivery certificate — see notification_certificate_package_url.

Removes an attachment from a notification. Requires documentId (from notification_document_list), notificationRequestId and caseFileId.

Returns { downloadUrl }, a temporary link to an attachment as it was sent. Requires documentId (from notification_document_list), notificationRequestId and caseFileId. Use it to retrieve a file you attached or to verify what a recipient received. The URL is presigned and expires — fetch it when you need it rather than storing it.

Lists the documents attached to a notification with their processing status, and it is what you poll after notification_document_add: a newly registered document starts at PENDING and reaches READY_TO_SEND in roughly 8 seconds. Calling notification_request_send while any document is still PENDING fails with 409/404 NOTIFICATION_NOT_FOUND. Poll with a bounded retry — every few seconds, a dozen attempts at most. Requires notificationRequestId and caseFileId. Paginated.

Adds a recipient to a notification request. Requires: notification_request_create → notificationRequestId, case_file_create → caseFileId. The `id` can be a UUID v4 or custom string. Returns receiverId — save it for notification_certificate_get. Delivery is by email always; set sendWaUrl for a WhatsApp link, sendSmsUrl for an RCS/SMS link (the channel negotiates: RCS where the handset supports it, SMS otherwise), and otpRequired to challenge the recipient with a one-time code. Any of those three needs phonePrefix (with the +) and phoneNumber. Add all receivers before calling notification_request_send — but if the notification has attachments, add those FIRST (see notification_document_add).

Adds several recipients in one call instead of one notification_receiver_add per person. Pass `receivers` as an array; each entry needs `id` (you generate it), firstName, lastName and email, and may carry phonePrefix (with the +) and phoneNumber. Note this bulk form does NOT accept the per-recipient otpRequired, sendWaUrl or sendSmsUrl flags that the single-recipient tool does — set the defaults on the request instead (otpByDefault, sendWaUrlByDefault, sendSmsUrlByDefault). The maximum number of recipients is a per-subscription setting, not a fixed API limit: it varies by tenant and platform, so do not assume a number — add them and read the error if the tenant's cap is exceeded. Add every recipient before calling notification_request_send, then check the result with notification_receiver_list, since a rejected address appears with status INVALID.

Removes a recipient from a notification. Requires receiverId, notificationRequestId and caseFileId. To remove every address the platform rejected in one call, use notification_receiver_invalid_purge rather than deleting them one by one.

Removes every recipient whose status is INVALID — addresses the platform rejected as malformed or duplicated — from a notification in a single call. Requires notificationRequestId and caseFileId. Recipients in any other status are left untouched. AN INVALID RECIPIENT BLOCKS THE SEND, so run this (or fix the addresses with notification_receiver_update) before notification_request_send, or the notification will not go out. Use notification_receiver_list first to see what will go.