Saltar al contenido
Facturador

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.