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 |
Example of request
Request
curl --request POST \
--url https://web-prod01.tuidentidad.com/api/cfdivalidation/validate \
--header 'apikey: TU_API_KEY_AQUI' \
--form 'file=@PANADERIA_ARTESANAL_BAKERS.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
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.",
"instance": "3240e823-06b9-45a4-9807-ee8524a5F43a",
"code": "CFDI401"
}
400 Bad Request
{
"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.",
"instance": "5820e823-56b9-82a4-9867-aa8524f8d43a",
"code": "CFDI003"
}
Service Messages
| Error Code | Public Description | HTTP code |
|---|---|---|
| CFDI001 | An unexpected internal error occurred. | 500 |
| CFDI002 | Provider service is unavailable. All retry attempts have been exhausted. | 503 |
| CFDI003 | The provided XML file is invalid or does not follow the expected format. | 400 |
| CFDI004 | Failed to extract UUID from XML. | 400 |
| CFDI005 | An XML file is required to process the request. | 400 |
| CFDI010 | The CFDI has an invalid digital seal. | 200 (warning) |
| CFDI011 | The RFC in the XML does not match the official record. | 200 (warning) |
| CFDI012 | The CFDI is marked as 'Cancelled' by the Tax Authority. | 200 (warning) |
| CFDI013 | CFDI record not found in the Tax Authority database. | 200 (warning) |
| CFDI014 | Failed to retrieve verification information from the provider. | 503 |
| CFDI015 | The total amount in the XML does not match the official record. | 200 (warning) |
| CFDI016 | The emission date in the XML does not match the official record. | 200 (warning) |
| CFDI017 | CFDI record was not located in SAT controls. | 200 (warning) |
| CFDI018 | The CFDI is invalid according to official records. | 200 (warning) |
| CFDI020 | Error deserializing the provider response at the gateway. | 502 |
| CFDI050 | The provider failed to respond within the timeout period. | 408 |
| CFDI401 | Unauthorized request. Company ID is missing or invalid. | 401 |
| CFDI999 | An error occurred with the external verification provider. | 200 (warning) |
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.