Skip to main content
POST
/
api
/
v1
/
consulta-cpe
/
factura
/
{id}
Query Invoice Status
curl --request POST \
  --url https://api.example.com/api/v1/consulta-cpe/factura/{id}
{
  "200": {},
  "404": {},
  "422": {},
  "500": {},
  "success": true,
  "message": "<string>",
  "data": {
    "data.comprobante": {
      "data.comprobante.id": 123,
      "data.comprobante.tipo_documento": "<string>",
      "data.comprobante.serie": "<string>",
      "data.comprobante.correlativo": "<string>",
      "data.comprobante.fecha_emision": "<string>",
      "data.comprobante.monto": 123
    },
    "data.consulta": {
      "data.consulta.estadocpe": "<string>",
      "data.consulta.estado_ruc": "<string>",
      "data.consulta.condicion_domicilio": "<string>",
      "data.consulta.ubigeo": "<string>",
      "data.consulta.descripcion_estado": "<string>",
      "data.consulta.consulta_fecha": "<string>"
    }
  }
}
Query the status of a specific invoice (factura) from SUNAT’s electronic invoice system. This endpoint retrieves the validation status, acceptance state, and additional information about the invoice from SUNAT’s records.

​
Authentication

This endpoint requires authentication using Laravel Sanctum. Include the bearer token in the Authorization header: 
Authorization: Bearer {your-api-token}

​
Endpoint

POST /api/v1/consulta-cpe/factura/{id}

​
Path Parameters

​
id
integer
required
The internal ID of the invoice to query. This is the primary key from the invoices table.

​
Query Methods

The service automatically attempts two methods in order:
  1. OAuth2 API (Primary): Uses SUNAT’s modern API with OAuth2 authentication
  2. SOAP SOL (Fallback): Uses traditional SOAP web services with SOL credentials if OAuth2 fails
The system automatically caches OAuth2 tokens for 45 minutes to optimize performance and reduce authentication requests.

​
Response

​
success
boolean
required
Indicates if the query was successful
​
message
string
required
Human-readable message describing the result
​
data
object
required
Contains the invoice information and query results
​
data.comprobante
object
Basic information about the queried invoice
​
data.comprobante.id
integer
Invoice internal ID
​
data.comprobante.tipo_documento
string
Document type code (01 for invoices)
​
data.comprobante.serie
string
Invoice series (e.g., F001)
​
data.comprobante.correlativo
string
Invoice correlative number
​
data.comprobante.fecha_emision
string
Issue date in Y-m-d format
​
data.comprobante.monto
number
Total invoice amount
​
data.consulta
object
SUNAT query results
​
data.consulta.estadocpe
string
CPE status code:
  • 1: Accepted (Aceptado)
  • 2: Annulled (Anulado)
  • 3: Authorized (Autorizado)
  • 0: Does not exist (No existe)
  • -1: Query error
​
data.consulta.estado_ruc
string
RUC status from SUNAT registry
​
data.consulta.condicion_domicilio
string
Tax domicile condition
​
data.consulta.ubigeo
string
Geographic location code (ubigeo)
​
data.consulta.descripcion_estado
string
Human-readable status description in Spanish
​
data.consulta.consulta_fecha
string
Timestamp when the query was performed (Y-m-d H:i:s)

​
Code Examples

curl -X POST https://api.yourdomain.com/api/v1/consulta-cpe/factura/123 \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

​
Response Examples

​
Success Response (200)

{
  "success": true,
  "message": "Consulta realizada correctamente",
  "data": {
    "comprobante": {
      "id": 123,
      "tipo_documento": "01",
      "serie": "F001",
      "correlativo": "00000456",
      "fecha_emision": "2026-03-05",
      "monto": 1180.00
    },
    "consulta": {
      "estadocpe": "1",
      "estado_ruc": "ACTIVO",
      "condicion_domicilio": "HABIDO",
      "ubigeo": "150101",
      "descripcion_estado": "Aceptado",
      "consulta_fecha": "2026-03-05 14:30:25"
    }
  }
}

​
Error Response (404)

{
  "success": false,
  "message": "No query results for model [App\\Models\\Invoice] 123",
  "error": "Model not found"
}

​
SUNAT Query Error (422)

{
  "success": false,
  "message": "El comprobante no existe en los registros de SUNAT",
  "data": {
    "comprobante": {
      "id": 123,
      "tipo_documento": "01",
      "serie": "F001",
      "correlativo": "00000456",
      "fecha_emision": "2026-03-05",
      "monto": 1180.00
    },
    "consulta": null
  }
}

​
Server Error (500)

{
  "success": false,
  "message": "Error al consultar factura",
  "error": "Connection timeout to SUNAT services"
}

​
Status Codes

​
200
OK
Query completed successfully, invoice status retrieved from SUNAT
​
404
Not Found
Invoice with the specified ID does not exist in the database
​
422
Unprocessable Entity
Query was performed but SUNAT returned an error (e.g., document not found in SUNAT records)
​
500
Internal Server Error
Server error occurred during query processing

​
Database Updates

When a successful query is performed, the invoice record is automatically updated with:
  • consulta_cpe_estado: The CPE status code from SUNAT
  • consulta_cpe_respuesta: JSON-encoded full response from SUNAT
  • consulta_cpe_fecha: Timestamp of the query
  • estado_sunat: Updated with the current SUNAT status
This endpoint uses the ConsultaCpeService which implements intelligent fallback between OAuth2 API and SOAP SOL methods. The service is defined in app/Services/ConsultaCpeService.php:36.

​
Implementation Details

The query process follows these steps:
  1. Retrieve the invoice with company information from the database
  2. Attempt OAuth2 authentication with SUNAT API using cached or new token
  3. Create a CpeFilter object with invoice details (RUC, document type, series, correlative, date, amount)
  4. Query SUNAT API for document status
  5. If OAuth2 fails, automatically fallback to SOAP SOL credentials method
  6. Process and interpret the response codes
  7. Update the invoice record with query results
  8. Return formatted response with document and query information
The OAuth2 token is automatically managed with a 45-minute cache lifetime and 5-minute expiration buffer to ensure seamless authentication.

Build docs developers (and LLMs) love

Get started for freeTalk to us