CFDI validation API
CFDI API is an automated and standardized mechanism for validating the status of electronic tax receipts (CFDI) against the SAT (Servicio de Adminitración Tributaria). This solution enables real-time verification by querying official SAT services to confirm the authenticity, validity, and current status of each document. It helps identify canceled, invalid, or non-existent CFDIs, ensuring regulatory compliance, reducing fraud risk, and improving the efficiency of tax and financial processes.
Use cases
- Invoice Verification Before Payment: Ensure that a supplier’s CFDI is valid, not canceled, and matches the expected company information before processing payments.
- Accounts Payable Compliance: Automatically validate incoming invoices to meet regulatory requirements and prevent accounting errors.
- Fraud Detection: Detect invalid, duplicated, or nonexistent CFDIs to reduce the risk of fraudulent transactions.
- Real-Time Workflow Integration: Validate CFDIs automatically during business processes, such as supplier onboarding or invoice submission, for immediate feedback.
- Audit and Regulatory Reporting: Provide verifiable proof that all CFDIs have been checked and comply with SAT regulations for internal or external audits.
- Automated Reconciliation: Cross-check issued and received CFDIs against SAT records to ensure consistency in accounting systems and reports.
Base URL
https://web-prod01.tuidentidad.com
Authentication
Each company is assigned a unique, non-transferable API key that must be included to authenticate requests.
Headers
| Tag | Type | Required | Description |
|---|---|---|---|
| ApiKey | string | yes | Customer key. |
Example: ApiKey: YOUR_API_KEY
Endpoint
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/CfdiValidation/validate | Validate a CFDI document. |
Request
Body Parameters
| field | Type | Required | Validations | Description | Example |
|---|---|---|---|---|---|
| File | IFromFile (Binary) | yes | Extensión .xml o Content-Type text/xml / application/xml. non null |
XML file to be validated | cfdi.xml |
Successful Response
{
"verificationId": "550e8400-e29b-41d4-a716-446655440000",
"uuid": "28729F92-28D0-4441-9692-9D11D9A57525",
"success": true,
"data": {
"rfcEmisor": "PAB190328KM7",
"rfcReceptor": "TID1703311Y9",
"fechaExpedicion": "2023-10-27T09:44:02",
"fechaCertificacion": "2023-10-27T09:59:06",
"pacCertifico": null,
"total": 180.00,
"estado": "Vigente",
"estatusCancelacion": "",
"validacionXml": true,
"selloCfdiValido": true,
"selloTimbreFiscalValido": true
},
"warnings": [
"code": "CFDI000",
"message": "description",
"statuscode": 500
]
}
Response fields
| Field | Type | Description |
|---|---|---|
| verificationId | GUID | Unique identifier for this validation within the TuIdentidad system |
| uuid | string | UUID of the CFDI extracted of XML file. |
| success | boolean | true indicates that there are no critical warnings and the CFDI has not been canceled |
| data.rfcEmisor | string | Issuer RFC (validation against XML and SAT records) |
| data.rfcReceptor | string | Receptor RFC (validation against XML and SAT records) |
| data.fechaExpedicion | datetime | CFDI issue date |
| data.fechaCertificacion | datetime | CFDI certification date |
| data.total | decimal | Normalized total amount (without $ or commas) |
| data.estado | string | Status: Valid \ Cancelled \ Not Found |
| data.estatusCancelacion | string | Cancellation status (blank if not applicable) |
| data.validacionXml | boolean | true if the XML was validated successfully by the SAT |
| data.selloCfdiValido | boolean | CFDI digital seal is valid |
| data.selloTimbreFiscalValido | boolean | Fiscal stamp seal is valid |
| warnings | array | List of warnings |
| warnings.code | string | Error code |
| warning.message | string | Description of the error |
| warnings.statuscode | integer | Status code |
Examples Bad Request
400 500 Bad Request - Server error
{
"type": "https://docs.tuidentidad.com/cfdi-verification/#service-messages",
"title": "Bad Request",
"status": 400,
"detail": "The provided XML file is invalid or does not follow the expected format.",
"code": "CFDI003"
}
401 Unauthorized — Invalid API key
{
"type": "https://docs.tuidentidad.com/cfdi-verification/#service-messages",
"title": "Unauthorized",
"status": 401,
"detail": "Unauthorized request. Company ID is missing or invalid.",
"code": "CFDI401"
}
503 Service Unavailable
{
"type": "https://docs.tuidentidad.com/cfdi-verification/#service-messages",
"title": "Service Unavailable",
"status": 503,
"detail": "Provider service is unavailable. All retry attempts have been exhausted.",
"code": "CFDI002"
}
HTTP Status Codes
| Error Code | Public Description | HTTP Status | Category | Typical Cause |
|---|---|---|---|---|
| CFDI001 | An unexpected internal error occurred. | 500 | Technical | Unhandled exception in the service |
| CFDI002 | Provider service is unavailable. All retry attempts have been exhausted. | 503 | Dependency | The CanicaSync provider did not respond after 3 retries |
| CFDI003 | The provided XML file is invalid or does not follow the expected format. | 400 | Client | Malformed XML or not a valid CFDI |
| CFDI004 | Failed to extract UUID from XML. | 400 | Client | XML does not contain the TimbreFiscalDigital node or UUID attribute |
| CFDI005 | An XML file is required to process the request. | 400 | Client | No file sent or the file is empty |
| CFDI010 | The CFDI has an invalid digital seal. | 200 (warning) | Dependency | SAT reports an invalid digital seal |
| CFDI011 | The RFC in the XML does not match the official record. | 200 (warning) | Dependency | Discrepancy in Issuer/Receiver RFC between XML and SAT |
| CFDI012 | The CFDI is marked as 'Cancelled' by the Tax Authority. | 200 (warning) | Dependency | The CFDI was canceled with SAT |
| CFDI013 | CFDI record not found in the Tax Authority database. | 200 (warning) | Dependency | The UUID does not exist in SAT records |
| CFDI014 | Failed to retrieve verification information from the provider. | 503 | Dependency | Provider response could not be deserialized or was null |
| CFDI015 | The total amount in the XML does not match the official record. | 200 (warning) | Dependency | Amount in XML differs from SAT (tolerance ±$0.05) |
| CFDI016 | The emission date in the XML does not match the official record. | 200 (warning) | Dependency | Emission date in XML differs from the one reported by SAT |
| CFDI017 | CFDI record was not located in SAT controls. | 200 (warning) | Dependency | Provider message: "CFDI not located in SAT controls" |
| CFDI018 | The CFDI is invalid according to official records. | 200 (warning) | Dependency | Provider message: "CFDI invalid" |
| CFDI020 | Error deserializing the provider response at the gateway. | 502 | Technical | Web endpoint could not deserialize microservice response |
| CFDI050 | The provider failed to respond within the timeout period. | 408 | Dependency | Connection timeout to provider |
| CFDI401 | Unauthorized request. Company ID is missing or invalid. | 401 | Client | Header apikey / companyid missing or invalid |
| CFDI999 | An error occurred with the external verification provider. | 200 (warning) | Dependency | Generic / unclassified provider error |
Error categories
Client: Error in the API consumer request (invalid data, incorrect format, or credentials). Dependency: Failure in external services or providers (INE, RENAPO, SAT, CFE, etc.). Technical: Failure in TuIdentidad's internal infr astructure or code.
Support
If you encounter issues integrating the API, contact the Tu Identidad support team.