Skip to main content
POST
/
api
/
v1
/
consulta-cpe
/
boleta
/
{id}
Query Boleta Status
curl --request POST \
  --url https://api.example.com/api/v1/consulta-cpe/boleta/{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 sales receipt (boleta) from SUNAT’s electronic invoice system. This endpoint retrieves the validation status, acceptance state, and additional information about the boleta 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/boleta/{id}

​
Path Parameters

​
id
integer
required
The internal ID of the boleta to query. This is the primary key from the boletas 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 boleta information and query results
​
data.comprobante
object
Basic information about the queried boleta
​
data.comprobante.id
integer
Boleta internal ID
​
data.comprobante.tipo_documento
string
Document type code (03 for boletas)
​
data.comprobante.serie
string
Boleta series (e.g., B001)
​
data.comprobante.correlativo
string
Boleta correlative number
​
data.comprobante.fecha_emision
string
Issue date in Y-m-d format
​
data.comprobante.monto
number
Total boleta 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/boleta/456 \
  -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": 456,
      "tipo_documento": "03",
      "serie": "B001",
      "correlativo": "00001234",
      "fecha_emision": "2026-03-05",
      "monto": 250.50
    },
    "consulta": {
      "estadocpe": "1",
      "estado_ruc": "ACTIVO",
      "condicion_domicilio": "HABIDO",
      "ubigeo": "150131",
      "descripcion_estado": "Aceptado",
      "consulta_fecha": "2026-03-05 15:45:10"
    }
  }
}

​
Annulled Document Response (200)

{
  "success": true,
  "message": "Consulta realizada correctamente",
  "data": {
    "comprobante": {
      "id": 457,
      "tipo_documento": "03",
      "serie": "B001",
      "correlativo": "00001235",
      "fecha_emision": "2026-03-04",
      "monto": 180.00
    },
    "consulta": {
      "estadocpe": "2",
      "estado_ruc": "ACTIVO",
      "condicion_domicilio": "HABIDO",
      "ubigeo": "150131",
      "descripcion_estado": "Anulado",
      "consulta_fecha": "2026-03-05 15:46:22"
    }
  }
}

​
Error Response (404)

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

​
SUNAT Query Error (422)

{
  "success": false,
  "message": "El comprobante no existe en los registros de SUNAT",
  "data": {
    "comprobante": {
      "id": 456,
      "tipo_documento": "03",
      "serie": "B001",
      "correlativo": "00001234",
      "fecha_emision": "2026-03-05",
      "monto": 250.50
    },
    "consulta": null
  }
}

​
Server Error (500)

{
  "success": false,
  "message": "Error al consultar boleta",
  "error": "SOAP connection failed: timeout"
}

​
Status Codes

​
200
OK
Query completed successfully, boleta status retrieved from SUNAT
​
404
Not Found
Boleta 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 boleta 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 same ConsultaCpeService as invoices, but operates on the Boleta model. The service is defined in app/Services/ConsultaCpeService.php:36.

​
Implementation Details

The query process follows these steps:
  1. Retrieve the boleta with company information from the database
  2. Attempt OAuth2 authentication with SUNAT API using cached or new token
  3. Create a CpeFilter object with boleta 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 boleta record with query results
  8. Return formatted response with document and query information

​
Difference from Invoice Query

While functionally identical to the invoice query endpoint, this endpoint:
  • Operates on the boletas table instead of invoices
  • Uses document type code 03 instead of 01
  • Typically uses series starting with ‘B’ (e.g., B001, B002) instead of ‘F’
Boletas are commonly used for sales to final consumers without RUC, while invoices (facturas) are used for business-to-business transactions.

​
Rate Limiting

To avoid rate limiting from SUNAT:
  • Single queries are performed immediately
  • For multiple queries, consider using the bulk query endpoint instead
  • The service includes automatic delays (0.5 seconds) between consecutive queries in bulk operations
SUNAT’s services may have rate limits. If you need to query multiple boletas, use the bulk query endpoint (/api/v1/consulta-cpe/masivo) which implements proper throttling.

Build docs developers (and LLMs) love

Get started for freeTalk to us