Einvoice XML Validation

# Validate Mexico E-Invoice Run SAT validation on an already-created document. Executes three steps in order and records the outcome (audit log + validation-history row): 1. **Schema** — CFDI 4.0 structure + required attributes. 2. **SAT status** — queries SAT's `ConsultaCFDIService` for the invoice status (`Vigente` = valid). 3. **RFC** — the receiver RFC matches the configured company RFC. The document must have finished importing (creation `status = SUCCESS`) before it can be validated. ## Endpoint `POST /v2/einvoice/mexico/validate` ## Request Headers | Attribute | Type | Option | Description | | --- | --- | --- | --- | | `x-api-key` | String | Required | A unique string | | `Authorization` | String | Required | Bearer token | | `Content-Type` | String | Required | `application/json` | | `Accept` | String | Optional | `application/json` | ## Request Payload | Field | Type | Required | Description | | --- | --- | --- | --- | | `documentId` | String | ✅ | The Staple document id to validate | ``` { "documentId": "245234" } ``` ## Response (Success — VALID) ``` { "documentId": "245234", "uuid": "699628be-2f06-4bc9-adc2-860b51eecbca", "validation_result": "VALID", "validatedAt": "2026-07-09T08:29:06.785Z", "invalid_reason": null, "steps": { "schema": { "result": "PASS", "detail": null }, "satStatus": { "result": "PASS", "detail": null }, "rfc": { "result": "PASS", "detail": null } } } ``` ## Response (INVALID) ``` { "documentId": "245234", "uuid": "699628be-2f06-4bc9-adc2-860b51eecbca", "validation_result": "INVALID", "validatedAt": "2026-07-09T08:29:06.785Z", "invalid_reason": "Cancelled E-Invoice", "steps": { "schema": { "result": "PASS", "detail": null }, "satStatus": { "result": "FAIL", "detail": "Cancelled E-Invoice" } } } ``` ## Response Fields | Field | Type | Description | | --- | --- | --- | | `documentId` | String | The validated document id | | `uuid` | String | CFDI Folio Fiscal (UUID) from the XML | | `validation_result` | String | `VALID` or `INVALID` | | `validatedAt` | String | ISO timestamp of the validation run | | `invalid_reason` | String | null | | `steps` | Object | Per-step results — `schema`, `satStatus`, `rfc` | ### `steps.\*` Fields | Field | Type | Description | | --- | --- | --- | | `result` | String | `PASS` or `FAIL` | | `detail` | String | null | Only the steps that actually ran are present. Validation stops at the first failing step, so e.g. a schema failure returns `steps.schema` only; a SAT failure returns `schema` + `satStatus`. ## Notes - `documentId` is the main identifier for this endpoint. - Validation can only run once the document's creation `status = SUCCESS` (document is `RECEIVED`/`COMPLETED`). - Common `satStatus.detail` values: `Cancelled E-Invoice`, `E-Invoice Not Found`, `Unknown SAT Status:` , `SAT service unavailable: no response after 3 attempts`. - Every call is recorded as a validation-history row and an audit-trail entry (`validated_document`). ## Errors | Status | When | | --- | --- | | `400 Bad Request` | Missing `documentId`; document not found; caller not authorized; document not yet processed (creation status not success); XML missing; or CFDI has no UUID | | `401 / 403` | Missing/invalid `x-api-key` or `Authorization`, or no access to the document | | `502 / 503` | SAT (or upstream dependency) temporarily unavailable | * * * Want the **example request/response pairs** formatted for Postman (so you can drop them into saved Examples — e.g. one `VALID`, one `INVALID – Cancelled`, one `400 – not processed`), or shall I paste the **status endpoint** next?