| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Intro
This API validates an electricity bill issued by CFE from the account holder's name and the service number printed on it.
In the answer you will get the CFDI that backs the bill —issuer, receiver, amounts and line items— together with the data printed on the bill itself: the customer's address, the tariff, the meter readings and the consumption history.
It is meant to confirm that a bill handed to you as proof of address is real and belongs to the person who handed it in, without having to read the document by hand.
Important Points
Mandatory Fields
All the fields in the body are mandatory and kiban cloud performs validations on the information sent to detect special characters or incorrect formats.
| field | type | required | length | Description |
|---|---|---|---|---|
| name | Alphabetic | Yes | min 2 | Name of the account holder, as it appears on the bill. |
| serviceNumber | Numeric | Yes | N/A | Service number (número de servicio) printed on the bill. Digits only. |
No credentials required
This service runs on credentials kiban provides, so you do not need to contract CFE or send a vault field: the API key of your account is enough.
Dates
cfdi.fecha is delivered as a date without time, in yyyy-mm-dd format, even though the CFDI carries a timestamp.
Test the service (test cases)
We have included a query parameter in Sandbox to enable you to query the test cases that we created for running tests. To get a response, fill the testCaseId parameter with any of the following cases:
| Num | Id | Name | Description |
|---|---|---|---|
| 1 | 6939a1b2c3d4e5f600000b01 | Respuesta exitosa | Indicates one successful response with the CFDI and the bill data |
| 2 | 6939a1b2c3d4e5f600000b02 | Datos invalidos | Indicates a 400 response when the provider rejects the data sent |
Test your own test caseIn case you want to test your own test case created in link, you can send in the testCaseId parameter the identifier of the test case you want to use.
For more information visit our knowledge center to know more about test cases
Successful response
Inside the response object you will get the next fields.
| subfield | Description |
|---|---|
| status | Status returned by the provider. |
| messageCode | Result code of the validation. |
| validationCode | Code the provider assigns to the validation performed. |
| cfdi | The CFDI that backs the bill. |
| datos | The data printed on the bill. |
cfdi
| subfield | Description |
|---|---|
| fecha | Issue date of the CFDI, in yyyy-mm-dd format. |
| folio | Folio of the CFDI. |
| serie | Series of the CFDI. |
| version | CFDI version, for example 4.0. |
| tipoDeComprobante | Type of receipt, for example I for income. |
| formaPago | Payment form code. |
| metodoPago | Payment method code, for example PUE. |
| moneda | Currency of the amounts. |
| lugarExpedicion | Postal code where the CFDI was issued. |
| subTotal | Amount before taxes. |
| total | Total amount of the bill. |
| emisor | Issuer: nombre, rfc and regimenfiscal. |
| receptor | Receiver: nombre, rfc, usoCFDI, regimenFiscalReceptor and domicilioFiscalReceptor. |
| conceptos | Line items of the bill, as the CFDI carries them. |
datos
| subfield | Description |
|---|---|
| rpu | Registro Permanente de Usuario of the service. |
| ajustePorRedondeo | Rounding adjustment applied to the amount. |
| ocr | Data read from the bill's OCR line: periodo, digito and tipo. |
| informacionFactura | Billing information: lineaDeReferencia, uso, montoAPagarEnLetras, cargosCreditos, dias, consumoDiario, precioDiario and codigoDeBarras. |
| cliente | Customer as printed on the bill: nombre, calle, calle2, colonia, codigoPostal, ciudad, estado, tarifa, consumo, lecturaAnterior and lecturaActual. |
| historialConsumos | Consumption history, with periodo, consumo and importe per period. |
{
"id": "6939a1b2c3d4e5f600000c11",
"createdAt": "2026-05-10T18:24:02.118Z",
"finishedAt": "2026-05-10T18:24:04.902Z",
"duration": 2784,
"status": "SUCCESS",
"request": {
"name": "JUAN PEREZ HERNANDEZ",
"serviceNumber": "773204509871"
},
"response": {
"status": "OK",
"messageCode": 0,
"validationCode": "vcf2789217358129.382917",
"cfdi": {
"fecha": "2025-05-10",
"folio": "000409872345",
"serie": "RB",
"version": "4.0",
"tipoDeComprobante": "I",
"formaPago": "03",
"metodoPago": "PUE",
"moneda": "MXN",
"lugarExpedicion": "11560",
"subTotal": "270.50",
"total": "305.00",
"emisor": {
"nombre": "AGUAS DEL NORTE SA DE CV",
"rfc": "ACE891203TT9",
"regimenfiscal": "601"
},
"receptor": {
"nombre": "JUAN PEREZ HERNANDEZ",
"rfc": "PAHJ850612F12",
"usoCFDI": "G03",
"regimenFiscalReceptor": "612",
"domicilioFiscalReceptor": "04330"
},
"conceptos": [
{
"cantidad": "1",
"claveProdServ": "43191510",
"claveUnidad": "KWH",
"descripcion": "Energia",
"importe": "215.50",
"valorUnitario": "215.50"
}
]
},
"datos": {
"rpu": "773204509871",
"ajustePorRedondeo": "0.02",
"ocr": {
"periodo": "202505",
"digito": "3",
"tipo": "02"
},
"informacionFactura": {
"lineaDeReferencia": "02 773204509871 250610 000000305 3",
"uso": "Comercial",
"montoAPagarEnLetras": "TRESCIENTOS CINCO PESOS M.N.",
"cargosCreditos": "305.00",
"dias": "30",
"consumoDiario": "2.10",
"precioDiario": "7.02",
"codigoDeBarras": "027732045098712506100000003053"
},
"cliente": {
"nombre": "JUAN PEREZ HERNANDEZ",
"calle": "AV INSURGENTES SUR 1458",
"calle2": "INT 3",
"colonia": "DEL VALLE CENTRO",
"codigoPostal": "03100",
"ciudad": "CIUDAD DE MÉXICO",
"estado": "CDMX",
"tarifa": "02",
"consumo": "130",
"lecturaAnterior": "5210",
"lecturaActual": "5340"
},
"historialConsumos": [
{
"periodo": "10 MAR 25 al 10 MAY 25",
"consumo": 130,
"importe": 305
}
]
}
},
"cost": 0
}Listing the possible not success responses
Required fields
You will get a 400 bad request error when any of the required fields are not provided.
[
{
"message": "name is required",
"field": "(root)"
},
{
"message": "serviceNumber is required",
"field": "(root)"
}
]Invalid Format
Some of the fields contain illegal characters or formatting or empty value, the service will return a 400 bad request.
[
{
"message": "String length must be greater than or equal to 2",
"field": "name"
},
{
"message": "Does not match pattern '^[0-9]+$'",
"field": "serviceNumber"
}
]
Use v2 to get the error detailThe bodies above are the ones returned by
v2. Onv1these validation errors arrive as a bare 400 with no body, so you will not know which field was rejected.
Data rejected by the provider (CFE)
The name and the service number do not match a bill, or the provider could not validate them. You will get a 400 with the execution, where status is INPUT_ERROR and errorMessage carries the reason.
{
"id": "6939a1b2c3d4e5f600000c12",
"createdAt": "2026-05-10T18:26:11.004Z",
"finishedAt": "2026-05-10T18:26:12.771Z",
"duration": 1767,
"status": "INPUT_ERROR",
"errorMessage": "Datos inválidos",
"request": {
"name": "JUAN PEREZ HERNANDEZ",
"serviceNumber": "000000000000"
}
}Unauthorized
It means that the provided API is incorrect and that you are not authorized to access it. You will not receive a body, only a 401 HTTP code.