RUC Paraguay API — Documentación interna

Servicio REST en PHP que consulta datos de un RUC paraguayo (principalmente razón social). Desplegado en https://api.avatar.com.py/ruc.

Fuentes de datos

La respuesta siempre incluye un campo fuente indicando de dónde salió el dato:

Valor de fuenteOrigenEstado
dnitServicio web oficial de DNIT (ex-SET), "Consulta RUC"Implementado, pendiente apiKey (a obtener vía Marangatú)
turuc.com.pyTercero no oficial (espeja datos de RUC), sin authActivo — se usa como fallback automático mientras no haya apiKey de DNIT

El fallback no tiene SLA ni términos de uso documentados. No usar para nada con implicancia legal o contable hasta migrar a la fuente oficial.

Autenticación

Todas las requests requieren el header:

Authorization: Bearer <TOKEN>

Token del servicio:

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Está definido en config/config.php (clave service_token) o vía variable de entorno RUC_SERVICE_TOKEN (tiene prioridad sobre el valor del archivo). Sin el header correcto, la API responde 401.

Endpoints

MétodoRutaDescripción
GET/ruc/{ruc}-{dv}Datos del contribuyente (RUC + dígito verificador pegados con guion).
GET/ruc/{ruc}?dv={dv}Igual, con el DV como query param separado.

Formato de respuesta

{
  "ok": true,
  "fuente": "dnit" | "turuc.com.py",
  "ruc": "80012345-6",
  "encontrado": true,
  "razonSocial": "NOMBRE DE LA EMPRESA",
  "estado": "ACTIVO",
  "detalle": { ... datos crudos específicos de la fuente ... }
}

Si el RUC no existe en la fuente consultada: "encontrado": false, "razonSocial": null. Si fallan ambas fuentes: HTTP 502 con {"ok": false, "error": "upstream", "errores": {"dnit": "...", "turuc.com.py": "..."}}. Si el RUC existe pero el DV no coincide: HTTP 400 con {"ok": false, "error": "dv_incorrecto", "fuente": "...", "ruc": "...", "dvProvisto": "...", "dvReal": "..."} — usá dvReal para reintentar con el DV correcto.

Ejemplos con curl

Consulta con RUC y DV pegados:

curl -s -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.avatar.com.py/ruc/80012345-6"

Consulta con DV separado:

curl -s -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.avatar.com.py/ruc/80012345?dv=6"

Infraestructura del deploy

ÍtemValor
URL base de RUChttps://api.avatar.com.py/ruc (HTTP redirige a HTTPS)
Directorio en el server/var/www/ruc-paraguay-api (dueño www-data)
DocumentRoot/var/www/ruc-paraguay-api/public
Vhost Apachecompartido con el resto del dominio (Alias /ruc en api-avatar.conf + api-avatar-le-ssl.conf) — ver /root/api-avatar-hub/CLAUDE.md
Directorio fuente/root/ruc-paraguay-api — editar acá y sincronizar al deploy

Actualizar el deploy

rsync -a --exclude '.git' --exclude '.claude' /root/ruc-paraguay-api/ /var/www/ruc-paraguay-api/
sudo chown -R www-data:www-data /var/www/ruc-paraguay-api
sudo chmod 600 /var/www/ruc-paraguay-api/config/config.php
sudo chmod 640 /var/www/ruc-paraguay-api/docs/ruc.html

Estado conocido / quirks