Cómo integrar la consulta de RUC en tu sistema de ventas o facturación

El problema: verificación manual de RUC

Si alguna vez trabajaste en un negocio que emite facturas, sabés lo tedioso que es el proceso de verificar un RUC. El escenario típico es así: un cliente llega a la caja, te dice su número de RUC, vos lo anotás a mano o lo buscás en el navegador, copiás los datos y los pegás en tu sistema. Todo esto mientras el cliente espera.

El problema no es solo la lentitud. Cada paso manual es una oportunidad para cometer errores. Un dígito mal copiado, un nombre incompleto, un RUC inactivo que nadie verificó. Y esos errores tienen consecuencias reales: una factura con un RUC inválido puede ser rechazada por la DNIT, lo que significa pérdida de tiempo, retrabajo y posibles sanciones.

En muchas empresas paraguayas, este proceso se repite decenas o cientos de veces al día. Los empleados alternan entre el sistema de facturación y el navegador, copiando y pegando datos manualmente. Es ineficiente, propenso a errores y completamente innecesario en 2026.

La solución: la API gratuita de TuRuc

TuRuc ofrece una API REST completamente gratuita que te permite consultar datos de contribuyentes de forma programática. No necesitás registrarte, no necesitás una API key, no necesitás pagar nada. Simplemente hacés una petición HTTP y recibís los datos en formato JSON.

La URL base de la API es:

https://turuc.com.py/api

Fue diseñada pensando en la facilidad de integración. Si tu sistema puede hacer una petición HTTP (y prácticamente todos pueden), podés integrar la consulta de RUC en minutos. No importa si tu sistema está hecho en Java, Python, PHP, JavaScript o cualquier otro lenguaje.

Endpoints disponibles

La API de TuRuc tiene dos endpoints principales que cubren los casos de uso más comunes:

GET /api/contribuyente/{ruc}

Este endpoint te permite buscar un contribuyente por su número de RUC exacto. Devuelve el registro completo del contribuyente si existe en la base de datos.

Caso de uso típico: cuando el usuario de tu sistema ya tiene el número de RUC (porque el cliente se lo dictó o lo leyó de una tarjeta), tu sistema puede llamar a este endpoint para autocompletar automáticamente el nombre, la razón social y verificar que el RUC esté activo antes de emitir la factura.

GET https://turuc.com.py/api/contribuyente/80012345-6

GET /api/contribuyente/search?q={query}

Este endpoint te permite buscar contribuyentes por nombre o por un fragmento del RUC. Devuelve una lista de contribuyentes que coinciden con la búsqueda.

Caso de uso típico: cuando el cliente no sabe su número de RUC pero sí su nombre o razón social, tu sistema puede usar este endpoint para buscarlo. Mostrás los resultados en un dropdown y el usuario selecciona el correcto.

GET https://turuc.com.py/api/contribuyente/search?q=EMPRESA%20EJEMPLO

¿Qué datos devuelve la API?

La API devuelve los datos en formato JSON. Cada registro de contribuyente incluye campos como el número de RUC, la razón social, el nombre de fantasía, el estado del contribuyente (activo, cancelado, suspendido), la categoría y otros datos de registro.

A continuación, un ejemplo conceptual de la respuesta:

{
  "ruc": "80012345-6",
  "razonSocial": "EMPRESA EJEMPLO SA",
  "nombreFantasia": "EJEMPLO",
  "estado": "ACTIVO",
  "categoria": "GRANDE"
}

Los campos más útiles para un sistema de facturación son:

• ruc: el número de RUC completo con dígito verificador.
• razonSocial: el nombre legal del contribuyente, tal como figura en el registro de la DNIT.
• nombreFantasia: el nombre comercial, si tiene uno registrado.
• estado: indica si el contribuyente está ACTIVO, CANCELADO o en otro estado. Fundamental para validar antes de facturar.
• categoria: la categoría del contribuyente según la DNIT.

¿Cómo integrar en tu sistema?

La integración es conceptualmente sencilla. Estos son los pasos generales que tu sistema debería seguir:

Para documentación técnica detallada, ejemplos de código en varios lenguajes y guías de integración paso a paso, visitá la documentación completa en docs.turuc.com.py.

Casos de uso

La API de TuRuc se adapta a múltiples escenarios. Estos son los más comunes entre los sistemas que ya la utilizan:

• Sistemas POS (punto de venta): validá el RUC del cliente en el momento del cobro, antes de imprimir la factura. Evitá facturas con datos incorrectos que después no podés usar para el IVA.
• Software de facturación: autocompletá los datos del contribuyente cuando el operador ingresa el RUC. Verificá que el estado sea ACTIVO antes de emitir el comprobante.
• E-commerce: cuando un cliente empresarial se registra en tu tienda online, validá su RUC en tiempo real. Asegurate de que los datos de facturación sean correctos desde el principio.
• Sistemas ERP: si manejás una base de datos de proveedores, podés hacer una validación masiva de todos los RUCs para asegurarte de que estén actualizados y activos.
• Contabilidad: antes del cierre mensual, verificá que todos los RUCs de proveedores y clientes en tus registros estén vigentes. Detectá contribuyentes cancelados o suspendidos antes de presentar tus declaraciones.

Preguntas frecuentes