Buscar comprobante (consulta pública)
POST /api/consultas/search
Autenticación: ninguna.
Busca un comprobante emitido por una empresa de la plataforma con los datos impresos en él (como la consulta pública de comprobantes para clientes finales) y devuelve los enlaces de descarga del XML y PDF.
Endpoint público: no requiere token (auth: No Auth). Solo necesita que la URL sea la del dominio de tu empresa. Tiene límite de peticiones por minuto. Límite: 30 peticiones por minuto (429 al excederlo). La empresa emisora se identifica con ruc_emisor o tenant_slug.
Formato de respuesta: heredado {success, message?, data?} sin paginación. Ante reglas de negocio puede responder HTTP 200 con success: false: revisa siempre success. Respuesta {success, message, data}; data es una lista de coincidencias o null.
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
ruc_emisor |
string | Sí* | RUC (11 dígitos) de la empresa emisora. *Obligatorio si no envías tenant_slug. |
tenant_slug |
string | No* | Dominio de la empresa emisora (empresa.dominio), alternativa a ruc_emisor. |
series |
string | Sí | Serie (máx. 10). |
number |
string | Sí | Número (máx. 20). |
customer_number |
string | Sí | Documento del cliente (máx. 15). |
total |
numeric | Sí | Importe total (≥ 0). |
date_of_issue |
date | Sí | Fecha de emisión YYYY-MM-DD. |
Reglas: las URLs de descarga son relativas al protocolo (empiezan con //): antepón https:.
Errores: HTTP 200 con {success: false, message, data: null}: No se encontró una empresa activa con los datos ingresados., La empresa emisora se encuentra temporalmente inactiva., El número de documento del cliente no fue encontrado., No se encontró un comprobante con los datos ingresados.; 422 {success: false, message: {campo: [...]}} si falta un campo; 429 por exceso de peticiones.
Cuerpo
Content-Type: application/json
{
"ruc_emisor": "20123456789",
"tenant_slug": null,
"series": "F001",
"number": "1520",
"customer_number": "20501973522",
"total": 118.0,
"date_of_issue": "2026-11-07"
}
Respuestas
200 — Encontrado
{
"success": true,
"message": "Comprobante encontrado",
"data": [
{
"customer": "20501973522",
"number": "F001-1520",
"total": "118.00",
"download_xml": "//empresa.dominio/downloads/document/xml/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
"download_pdf": "//empresa.dominio/downloads/document/pdf/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77"
}
]
}
200 — Sin resultados
{
"success": false,
"message": "No se encontró un comprobante con los datos ingresados.",
"data": null
}
422 — Validación
{
"success": false,
"message": {
"ruc_emisor": [
"El campo ruc emisor es obligatorio cuando tenant slug no está presente."
]
}
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.