RFC Certificates API

Internal API service designed to automate interactions with the SAT portal for certificate retrieval. The service programmatically performs queries against the SAT system, parses the response data, and returns certificate information in a structured JSON format. It also supports the secure download of the associated .cer file. The API is intended for integration with internal systems, enabling automated validation, synchronization, and certificate management workflows.

Use cases

  1. Automated Certificate Validation Systems can automatically query the API to validate the status and metadata of a certificate directly from the SAT portal, reducing manual verification efforts and ensuring up-to-date information.
  2. Certificate Synchronization Internal platforms can periodically retrieve and synchronize certificate data (including the .cer file) to maintain a consistent and centralized repository across services.
  3. Onboarding and Compliance Checks During user or vendor onboarding, the API can be used to fetch and verify certificate information as part of compliance and regulatory validation workflows.
  4. Batch Processing of Certificates The API enables bulk or scheduled processing of multiple certificate queries, supporting high-volume operations such as audits or large-scale validations.
  5. Integration with ERP or Accounting Systems Enterprise systems (e.g., ERP, billing, or invoicing platforms) can integrate with the API to automatically retrieve certificate data required for fiscal operations and electronic invoicing processes.
  6. Document and Record Management The downloaded .cer files can be automatically stored, indexed, and linked to internal records for traceability and document management purposes.

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

Parameters

Tag Type Required Description Value
v string yes Version of the API 1

Endpoint

Method Endpoint Description
POST /api/rfc/getCertificates Retrieves all certificate information for the RFC.

Request

Body Parameters

field Type Required Description Regex Example
rfc string yes RFC value to be verified ^[A-Z&Ñ]{3,4}[0-9]{6}[A-Z0-9]{3}$ XAXX010101000

Request body

{ 
 "rfc": "XAXX010101000"  
}

Response fields

Field Type Description
rfc string Queried RFC
businessName string Name of the person or company.
hasCertificates boolean
certificates array List of certificates.
certificates.serialNumber string Serial number of the certificate
certificates.status string Status of the certificate (ACTIVE / REVOKED / EXPIRED / NOT_FOUND).
certificates.certificateType string Type of certificate (EFIRMA / SEAL).
certificates.validFrom string:date Start of Validity
certificates.validTo string:date End of validity
certificates.file string:base64 Related document

Examples Bad Request

400 Bad Request

Response:

{ 
 "code": "RFCSC100", 
 "message": "Error in RFC format" 
}

500 Internal Server Error

Response:

{ 
 "code": "RFCSC200", 
 "message": "Internal server error" 
}

503 Service temporarily unavailable

Response:

{ 
 "code": "RFCSC300", 
 "message": "Service temporarily unavailable" 
}

Service errors

Error Code Public Description HTTP Status Category Typical Cause
RFCSC100 Endpoint not found. 404 Client Requested service does not exist.
RFCS010 Invalid API key. 401 Client The ApiKey is not valid.
RFCS004 The RFC field is required. 400 Client RFC field is null or empty string.
RFCS015 The structure is not correct. 400 Client RFC format is incorrect. Example of generic RFC: XAXX010101000
RFCSC200 Internal server error 500 Technical Not controled error.
RFCSC201 Official source is temporarily unavailable 503 Technical The verification source did not respond.
RFCSC202 Error initiating request to source site 504 Technical Thres is an error with the captcha. Try again.
RFCSC300 Official source is temporarily unavailable 503 Dependency The verification source is not available.
RFCSC301 Official source is temporarily unavailable 429 Dependency The verification source is blocked.
RFCSC302 Gateway Timeout 504 Dependency The SAT request timed out while processing.

Input and Output Contracts

Successful request

Request:

POST /api/rfc/getCertificates?v=1  
    Header: apikey: [API_KEY] 
    Body:  

     { 
      "rfc": "XAXX010101000" 
     }

Successful Response without certificates

Response:

 { 
 "rfc": "XAXX010101000", 
 "businessName": "JUAN PEREZ LOPEZ", 
 "hasCertificates": false, 
 "certificates": [] 
}

Successful Response with certificates

Response:

{ 
   "rfc": "XAXX010101000", 
   "businessName": "JUAN LOPEZ PEREZ", 
   "hasCertificates": true, 
   "certificates": [{ 
      "serialNumber": "00001000000118427636", 
      "status": "ACTIVE", 
      "certificateType": "SEAL", 
      "validFrom": "2025-01-01 00:00:00", 
      "validTo": "2029-01-01 00:00:00", 
      "file": "string:base64" 
   }] 

}

Successful Response that includes multiple certificates

Includes multiple objects in the certificates array, each with independent serialNumber, status, certificateType, validFrom, validTo, and cerFileUrl fields.

Response:

{ 
   "rfc": "XAXX010101000", 
   "businessName": "JUAN LOPEZ PEREZ", 
   "hasCertificates": true, 
   "certificates": [ 
     { 
      "serialNumber": "00001000000118434566", 
      "status": "EXPIRED", 
      "certificateType": "EFIRMA", 
      "validFrom": "2025-01-01 00:00:00", 
      "validTo": "2029-01-01 00:00:00", 
      "file": "string:base64" 
     }, 
{ 
      "serialNumber": "000010000001195865636", 
      "status": "ACTIVE", 
      "certificateType": "SEAL", 
      "validFrom": "2025-01-01 00:00:00", 
      "validTo": "2029-01-01 00:00:00", 
      "file": "string:base64" 
      }, 
     { 
      "serialNumber": "0000100000011844356", 
      "status": "ACTIVE", 
      "certificateType": "SEAL", 
      "validFrom": "2025-01-01 00:00:00", 
      "validTo": "2029-01-01 00:00:00", 
      "file": "string:base64" 
      } 
   ] 
}

400 Bad Request

Request:

POST /api/rfc/getCertificates?v=1 
    Header: apikey: [API_KEY] 
    Body:  
     { 
      "rfc": "" 
     }

Response: 

{ 
   "code": "RFCSC100", 
   "message": "The RFC field is required." 
}

500 Server error

Response:

{ 
   "code": "RFCSC200", 
   "message": "Internal server 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.