CFE validation service

Address service

Address service allows to validate a CFE document and get the structured data of residence and owner of the service contract. Also, the service consults directly in CFE to verify.

Web service description

Validate CFE document and address

This method performs the validation of the CFE document and obtains the information of the contract by OCR (Optical Character Recognition), verifies before the CFE if the contract number presented in the CFE address document.

~/api/address/cfe

Parameters

Tag	Type	Required	Description
imageFile	file	yes	CFE image type .jpg, .jpeg, .png or .pdf. 4MB maximum size.
crossBr	bool	no	Indicates if the cross-validation between OCR data, barcode data, and official source data is to be performed (default: false). See Cross Validation section for details.

Headers

Tag	Type	Required	Description
apikey	string	yes	Customer key.

FormData

{
  "imageFile": "file"
}

CURL

curl -X POST "~/api/address/cfe?crossBr=false" \
  -H "accept: application/json" \
  -H "apikey: {YOUR_API_KEY}" \
  -H "Content-Type: multipart/form-data" \
  -F "imageFile=@path_to_your_file"

Response:

Name	Type	Description
Correct:
valid	boolean	"Success"
data
name	string	Name of the CFE service contract owner.
addressline1	string	Street and number, Street reference, Suburb and postal code, City and state.
addressline2	string	empty value
addressline3	string	empty value
addressline4	string	empty value
totalPayment	string	Total amount invoiced.
period	string	Billed period.
serviceNumber	string	Service contract number.
paymentDeadline	string	Payment deadline.
geocodeUrl	string	URL of the geographical location of the address.
lat	number	Latitude.
lng	number	Longitude.
rmu	string	RMU (Registro Móvil de Usuarios) of the service.
cutoffdate	string	Day of cut of the service (lowercase property).
rate	string	Rate of the service.
rmu_bc	string	RMU value from barcode.
barcode	string	Barcode value.
cfeData
contractingName	string	Name of the service contrator.
address	string	Address of the CFE service.
contractingServiceNumber	string	Contract number of the CFE service.
rmu	string	RMU (Registro Móvil de Usuarios) of the service.
contractingTotalPayment	string	Total payment for the last month.
rate	string	Rate of the service.
meterNumber	string	Meter number of the CFE service.
multiplier	string	Multiplier of the CFE service.
paymentLimit	string	Last day for payment of the CFE service.
cutoffDate	string	Day of cut of the service.
period	string	Billed period.
rmu_bc	string	RMU value from barcode.
barcode	string	Barcode value.
barcodeValidation
isValidCrossData	boolean	Indicates if the cross-data validation is correct.
issues	array	List of issues found during barcode validation.
field	string	Field name with issue.
message	string	Description of the issue.
ocrValue	string	Value from OCR.
barcodeValue	string	Value from barcode.
cfeValue	string	Value from source.
summary	string	Summary of barcode validation.
Error
code	string	Error code.
message	string	"Error message".
warnings
code	string	Warning code.
message	string	Warning message.
fullMessage	string	Full warning message.

JSON

{
  "valid": true,
  "data": {
    "name": "string",
    "addressline1": "string",
    "addressline2": "string",
    "addressline3": "string",
    "addressline4": "string",
    "totalPayment": "string",
    "period": "string",
    "serviceNumber": "string",
    "paymentDeadline": "string",
    "geocodeUrl": "string",
    "lat": 0,
    "lng": 0,
    "rmu": "string",
    "cutoffdate": "string",
    "rate": "string",
    "rmu_bc": "string",
    "barcode": "string"
  },
  "cfeData": {
    "contractingName": "string",
    "address": "string",
    "contractingServiceNumber": "string",
    "rmu": "string",
    "contractingTotalPayment": "string",
    "rate": "string",
    "meterNumber": "string",
    "multiplier": "string",
    "paymentLimit": "string",
    "cutoffDate": "string",
    "period": "string",
    "rmu_bc": "string",
    "barcode": "string"
  },
  "barcodeValidation": {
    "isValidCrossData": true,
    "issues": [
      {
        "field": "string",
        "message": "string",
        "ocrValue": "string",
        "barcodeValue": "string",
        "cfeValue": "string"
      }
    ],
    "summary": "string"
  },
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "fullMessage": "string"
    }
  ]
}

Error

{
  "error": "Error code",
  "message": "Error message",
  "statuscode": 400
}

Verification CFE by data

This method obtains the information related with a contract in the CFE throw the service number, the name of the contrating person and the bill in string base64

~/api/address/cfe/byData

Parameters

Tag	Type	Required	Description
serviceNumber	string	yes	Contract number.
name	string	yes	Name of the contracting person.

Headers

Tag	Type	Required	Description
apikey	string	yes	Customer key.

FormData

{
  "serviceNumber": "string",
  "name": "string"
}

Response:

Success

Name	Type	Description
valid	bool	info validated
data	object
geolocation	object
geocodeurl	string	geocodeurl location
lat	string	lat location
lng	string	lng location
file	string	base64 file
cfeData	object
contractingName	string	contractingName found in the CFE source
address	string	address found in the CFE source
contractingServiceNumber	string	contractingServiceNumber found in the CFE source
rmu	string	rmu found in the CFE source
contractingTotalPayment	string	contractingTotalPayment found in the CFE source
rate	string	rate found in the CFE source
meterNumber	string	meterNumber found in the CFE source
multiplier	string	multiplier found in the CFE source
paymentLimit	string	paymentLimit found in the CFE source
cutoffDate	string	cutoffDate found in the CFE source
warnings	array	list of warnings
code	string	warning code
message	string	warning message

JSON

{
  "valid": true,
  "data": {
    "geolocation": {
      "geocodeurl": "string",
      "lat": "string",
      "lng": "string"
    }
  },
  "file": "string",
  "cfeData": {
    "contractingName": "string",
    "address": "string",
    "contractingServiceNumber": "string",
    "rmu": "string",
    "contractingTotalPayment": "string",
    "rate": "string",
    "meterNumber": "string",
    "multiplier": "string",
    "paymentLimit": "string",
    "cutoffDate": "string"
  },
  "warnings": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Error

Name	Type	Description
code	string	Error code
message	string	Error message
statuscode	int	HTTP status code

{
  "code": "Error code",
  "message": "Error message",
  "statuscode": 400
}

Create verification request for CFE

This method performs the validation of the CFE document in an async way returning a verificationId that allows to consult the results later.

~/api/address/cfe/AsyncVerify

Parameters

Tag	Type	Required	Description
imageFile	file	yes	CFE image type .jpg, .jpeg, .png or .pdf.

Headers

Tag	Type	Required	Description
apikey	string	yes	Customer key.

FormData

{
  "imageFile": "file"
}

Response:

Name	Type	Description
verificationId	string	Id of the verification.

JSON

{
  "verificationId": "uuid" // Id of the transaction
}

Error

Name	Type	Description
code	string	Error code
message	string	Error message
statuscode	int	HTTP status code

JSON

{
  "code": "Error code",
  "message": "Error message",
  "statuscode": 400
}

Get verification request status

This method allows to get the status of verification of the requested data.

~/api/address/cfe/VerificationStatus

Parameters

Query

Tag	Type	Required	Description
verificationId	string	Yes	Id of the verification to track.

Headers

Tag	Type	Required	Description
apikey	string	yes	Customer key.

Response:

Success

Name	Type	Description
verificationId	string	Id of the verification.
verificationStatus	int	Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
verification
valid	boolean	If is valid or not
data
name	string	Name of the CFE service contract owner.
addressline1	string	Street and number, Street reference, Suburb and postal code, City and state.
addressline2	string	empty value
addressline3	string	empty value
addressline4	string	empty value
totalPayment	string	Total amount invoiced.
period	string	Billed period.
serviceNumber	String	Service contract number.
paymentDeadline	string	Payment deadline.
geocodeUrl	string	URL of the geographical location of the address.
lat	float	Latitude.
lng	float	Length.
rmu	string	RMU (Registro Móvil de Usuarios) of the service.
cutoffdate	string	Day of cut of the service.
rate	string	Rate of the service.
rmu_bc	string	RMU (Registro Móvil de Usuarios) from barcode.
barcode	string	Barcode data.
cfeData
contractingName	string	Name of the service contrator.
address	string	Address of the CFE service.
contractingServiceNumber	string	Contract number of the CFE service.
rmu	string	RMU (Registro Móvil de Usuarios) of the service.
contractingTotalPayment	string	Total payment for the last month.
rate	string	Rate of the service.
meterNumber	string	Meter number of the CFE service.
multiplier	string	Multiplier of the CFE service.
paymentLimit	string	Last day for payment of the CFE service.
cutoffDate	string	Day of cut of the service.
period	string	Billed period.
rmu_bc	string	RMU (Registro Móvil de Usuarios) from barcode.
barcode	string	Barcode data.
barcodeValidation
isValidCrossData	boolean	Indicates if the cross-validation between OCR data and barcode data was successful.
issues	array	List of inconsistencies found during cross-validation.
field	string	Name of the field with the inconsistency.
message	string	Description of the inconsistency.
ocrValue	string	Value obtained from OCR.
barcodeValue	string	Value obtained from the barcode.
cfeValue	string	Value obtained from the internal 'source' process.
summary	string	A summary of the validation result.
warnings
code	string	Error code.
message	string	"Error message".
statuscode	int	HTTP status code.

JSON

{
  "verificationId": "string",
  "verificationStatus": 0,
  "verification": {
    "valid": true,
    "data": {
      "name": "string",
      "addressline1": "string",
      "addressline2": "string",
      "addressline3": "string",
      "addressline4": "string",
      "totalPayment": "string",
      "period": "string",
      "serviceNumber": "string",
      "paymentDeadline": "string",
      "geocodeUrl": "string",
      "lat": 0,
      "lng": 0,
      "rmu": "string",
      "cutoffdate": "string",
      "rate": "string",
      "rmu_bc": "string",
      "barcode": "string"
    },
    "cfeData": {
      "contractingName": "string",
      "address": "string",
      "contractingServiceNumber": "string",
      "rmu": "string",
      "contractingTotalPayment": "string",
      "rate": "string",
      "meterNumber": "string",
      "multiplier": "string",
      "paymentLimit": "string",
      "cutoffDate": "string",
      "period": "string",
      "rmu_bc": "string",
      "barcode": "string"
    },
    "barcodeValidation": {
      "isValidCrossData": true,
      "issues": [
        {
          "field": "string",
          "message": "string",
          "ocrValue": "string",
          "barcodeValue": "string",
          "cfeValue": "string"
        }
      ],
      "summary": "string"
    },
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "fullMessage": "string"
      }
    ]
  }
}

Error

Name	Type	Description
code	string	Error code
message	string	Error message
statuscode	int	HTTP status code

{
  "code": "Error code",
  "message": "Error message",
  "statuscode": 400
}

Cross Validation (crossBr)

When the crossBr parameter is set to false, the service performs an integrity check comparing multiple data sources extracted from the document against the official CFE information.

If crossBr=false is passed as input, the fields in the OCR result will compared through the field in the CFE official result. As appear in the table below.

OCR data	CFE data
name	contractingName
serviceNumber	contractingServiceNumber
addressline	address
paymentDeadline	paymentLimit
outoffdate	outoffDate
period	period

When the crossBr parameter is set to true, the service performs an integrity check comparing multiple data sources extracted from the document against the official CFE information.

OCR data	CFE data
name	contractingName
serviceNumber	contractingServiceNumber
addressline	address
paymentDeadline	paymentLimit
outoffdate	outoffDate
period	period
rmu	rmu
totalPayment	contractingTotalPayment

Impact on Response

If a discrepancy is found during cross-validation:
1. The global valid flag in the response will be set to false.
2. The barcodeValidation object will contain isValidCrossData: false.
3. The issues array will list the specific fields and descriptions of the inconsistencies found.

When the data is correct, the field isValidCrossData will be true.

The summary indicates that cross was successful in a short message.

JSON Example

{
"barcodeValidation": {
    "isValidCrossData": true,
    "issues": [
      {
        "field": "string",
        "message": "string",
        "ocrValue": "string",
        "barcodeValue": "string",
        "cfeValue": "string"
      }
    ],
    "summary": "Data cross-validation completed successfully"
  }
}

When the field isValidCrossData is false, this case may have two reasons.

Reason 1. The barcode wasn’t found and then the cross-referencing of information was not executed.

JSON Example

{
"barcodeValidation": {
    "isValidCrossData": false,
    "issues": [
      {
        "field": "string",
        "message": "string",
        "ocrValue": "string",
        "barcodeValue": "string",
        "cfeValue": "string"
      }
    ],
    "summary": "No valid barcode found for cross-validation"
  }
}

Reason 2. The cross validation was not successful in comparing some fields.

field: field don’t was cross successfully. message: Description of all fields that were not successfully compared/cross. ocrValue: value got by OCR barcodeValue: value got in the barcode
cfeValue: value got from CFE source
summary: Total number of validations found that do not match.

Table of messages that would be answered by the service between the different crosses.

Field	Message
paymentLimit	Payment limit does not match between barcode and OCR data
totalPayment	Total payment does not match between barcode and OCR data
serviceNumber	Service number does not match between barcode and OCR
rmu	RMU does not match between OCR, barcode and CFE data
rmu	RMU matches between document and barcode, but could not validate against the official source (CFE)
rmu	RMU does not match between barcode and source. Could not validate against the missing source
rmu	RMU not found in the document nor in the official source

Example

When isValidCrossData: false

JSON Example

{
"barcodeValidation": {
    "isValidCrossData": false,
    "issues": [
      {
        "field": "paymentLimit",
        "message": "Payment limit does not match between barcode and OCR data",
        "ocrValue": "02 FEB 24",
        "barcodeValue": "02/02/2025",
        "cfeValue": null
      },
      { 
        "field": "totalPayment", 
        "message": "Total payment does not match between barcode and OCR data", 
        "ocrValue": "2142", 
        "barcodeValue": "21425", 
        "cfeValue": null 
      },
       { 
        "field": "serviceNumber", 
        "message": "Service number does not match between barcode and OCR data", 
        "ocrValue": "533860800703", 
        "barcodeValue": "079121006524", 
        "cfeValue": null 
       }
       { 
        "field": "rmu", 
        "message": "RMU does not match between OCR, barcode and CFE data", 
        "ocrValue": "38240220117XAXX850224010", 
        "barcodeValue": "38240220117MAPS850224010", 
        "cfeValue": "38240220117MAPS850224010" 
       }, 
       { 
        "field": "rmu", 
        "message": "RMU matches between document and barcode, but could not validate against the official source (CFE)", 
        "ocrValue": "06000780801XAXX010101001", 
        "barcodeValue": "06000780801XAXX010101001", 
        "cfeValue": "" 
       }, 
       { 
        "field": "rmu", 
        "message": "RMU does not match between barcode and source. Could not validate against the missing source.", 
        "ocrValue": "", 
        "barcodeValue": "35DX15G030111001", 
        "cfeValue": "45602230425XAXX010101010" 
       }, 
       { 
        "field": "rmu", 
        "message": "RMU not found in the document nor in the official source", 
        "ocrValue": "", 
        "barcodeValue": "", 
        "cfeValue": "" 
       }, 
    ],
    "summary": "Found 7 validation issue(s) in barcode cross-validation"
  }
}

---

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request.

Code	Status	Description
200	OK	Success or Success with Warnings (e.g., expired document).
202	Accepted	Verification is being processed (Async flow).
203	Non-Authoritative Information	Partial information was returned (e.g., bill file not available).
204	No Content	No information was found based on the provided data.
400	Bad Request	The request was invalid or lacked required parameters.
413	Payload Too Large	The file exceeds the maximum allowed weight.
415	Unsupported Media Type	The file format is not supported.
422	Unprocessable Entity	The document could not be read or processed correctly.
500	Internal Server Error	An unexpected error occurred on the server.
503	Service Unavailable	External source or internal component is temporarily unavailable.
504	Gateway Timeout	The request to an external source timed out.

Service messages

Warning Code	Message	HTTP Code	Method
ADS002	Failed to get data	503	by file
ADS003	The file format is not correct	415	by file
ADS007	File size is larger than expected	413	by file
ADS008	There was a problem to get geolocation.	503	by file & by data
ADS009	The apiKey is not valid	401	by file & by data
ADS010	Server response failed	500	by file & by data
ADS011	Response time has exceeded	504	by file & by data
ADS012	Error load image	503	by file
ADS013	The document could not be read	422	by file
ADS018	The payment deadline does not match the latest receipt issued by CFE.	200	by file
ADS019	The serviceNumber field is required.	400	by data
ADS020	The serviceNumber field format is not correct	400	by data
ADS021	The name field is required.	400	by data
ADS022	The name field format is not correct.	400	by data
ADS023	There was a problem to validate the document.	503	by file
ADS025	The information couldn't be verified in the CFE source.	503	by file & by data
ADS026	The address could not be read.	422	by file
ADS027	Internal error processing and loading the file on OCR.	503	by file
ADS028	It is not an official document issued by CFE.	422	by file
ADS031	The file is not available for download from the source site.	203	by data
ADS032	The addresses do not match.	200	by file
ADS033	The cutoff date not match, it is not the current document issued.	200	by file
ADS034	The period not match, it is not the current document issued.	200	by file
ADS035	Invalid Service Number.	400	by data
ADS036	Service number does not match the contracting name.	200	by file & by data
ADS037	The CFE service is currently unavailable, please try again later.	503	by file & by data