--- title: "Refresh status" description: "Queries SAT directly for the current CFDI status. If required verification data is missing, it derives and persists it from the fiscal XML before reconciling local status and cancellation state." language: en canonical_url: "https://exac.mx/docs/en/api/documents/cfdi/refresh-cfdi-status" md_url: "https://exac.mx/docs/en/api/documents/cfdi/refresh-cfdi-status.md" --- # Refresh status Queries SAT directly for the current CFDI status. If required verification data is missing, it derives and persists it from the fiscal XML before reconciling local status and cancellation state. ## Request `POST /v1/cfdis/{documentRef}/status/refresh` - **Authorization:** Required permission: `invoices:manage`. - **Environments:** Production only - **Idempotency:** Required ## Canonical machine contract This fragment is generated from the canonical operation and Zod contracts used by the route. ```json { "method": "POST", "path": "/v1/cfdis/{documentRef}/status/refresh", "operation": { "operationId": "refreshCfdiStatus", "tags": [ "CFDI" ], "summary": "Refresh status", "description": "Queries SAT directly for the current CFDI status. If required verification data is missing, it derives and persists it from the fiscal XML before reconciling local status and cancellation state.", "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://adventurous-moose-616.convex.site", "description": "Current Exac production API deployment" } ], "parameters": [ { "name": "documentRef", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cfdi:.+$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Unique retry key for this exact operation. Reuse it only when retrying the same request." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Operation completed.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "webhook", "sat_query", "sat_bulk" ] }, "documentStatus": { "type": "string", "enum": [ "valid", "canceled", "not_found" ] }, "cancellability": { "type": "string", "enum": [ "unknown", "not_cancellable", "without_acceptance", "with_acceptance" ] }, "cancellation": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "unchanged" } }, "required": [ "state" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "none" } }, "required": [ "state" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "pending" }, "phase": { "type": "string", "enum": [ "requested", "verifying" ] } }, "required": [ "state", "phase" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "rejected" } }, "required": [ "state" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "expired" } }, "required": [ "state" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "completed" }, "resolution": { "type": "string", "enum": [ "accepted", "without_acceptance", "timeout", "unknown" ] } }, "required": [ "state", "resolution" ], "additionalProperties": false } ] }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "cancellationDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "source", "documentStatus", "cancellability", "cancellation", "observedAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "source": "sat_query", "documentStatus": "valid", "cancellability": "without_acceptance", "cancellation": { "state": "none" }, "observedAt": "2026-07-15T18:02:00.000Z" } } } } }, "400": { "description": "Invalid request.\n\n`validation_error`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid credential.\n\n`unauthenticated`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The credential does not include the `invoices:manage` permission.\n\n`forbidden`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found.\n\n`not_found`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Method not allowed.\n\n`method_not_allowed`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The operation conflicts with its current state or idempotency key.\n\nPossible codes: `conflict`, `idempotency_conflict`, `operation_in_progress`, `recovery_required`.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests.\n\n`rate_limited`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error.\n\n`internal`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service temporarily unavailable.\n\n`provider_unavailable`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-exac-environments": [ "production" ] }, "components": { "schemas": { "ApiError": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ProgrammaticError" } }, "required": [ "error" ], "additionalProperties": false }, "ProgrammaticError": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation_error", "unauthenticated", "forbidden", "not_found", "method_not_allowed", "conflict", "idempotency_conflict", "operation_in_progress", "recovery_required", "rate_limited", "provider_unavailable", "internal" ], "description": "Recommended action by code:\n\n- `validation_error` — Correct each details.issues entry using its path and stable issue code.\n- `unauthenticated` — Provide a valid API key or OAuth access token.\n- `forbidden` — Use a credential with the required permission.\n- `not_found` — Check the organization-scoped resource identifier.\n- `method_not_allowed` — Use the documented HTTP method.\n- `conflict` — Refresh the resource and resolve its current state.\n- `idempotency_conflict` — Use a new idempotency key for a changed request.\n- `operation_in_progress` — Wait for Retry-After, then repeat the exact request.\n- `recovery_required` — Do not retry automatically; reconcile the provider outcome.\n- `rate_limited` — Wait for Retry-After before retrying.\n- `provider_unavailable` — Retry only when the response marks the failure as retryable.\n- `internal` — Retry later and contact support if the error persists." }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "message", "status" ], "additionalProperties": false } } } } ``` [OpenAPI 3.1](/openapi.json) ## Equivalent MCP tools - [`refresh_cfdi_status`](/docs/en/mcp/tools/refresh_cfdi_status.md) Complete documentation: https://exac.mx/docs/en.md Agent documentation index: https://exac.mx/docs/en/llms.txt