Consulta de RUC — para el programador

Base

https://ws.a3.com.py/centroservicios

Encabezado X-API-Key. También se acepta ?token= en la URL (menos recomendable). CORS habilitado.

1. Buscar

GET https://ws.a3.com.py/centroservicios/api/ruc/v1/lookup

Enviá uno de estos parámetros:

• documento — coincidencia exacta (cédula / RUC sin DV)
• ruc — exacta, admite 1234567-3
• nombre — aproximación sobre razón social (mínimo 3 caracteres, máximo 20 resultados)

Documento o RUC encontrado:

{
  "documento": "1000000",
  "nombre_completo": "CAÑETE GONZALEZ, JUANA DEL CARMEN",
  "dv": "3",
  "ruc_completo": "1000000-3",
  "anterior": "CAGJ761720E",
  "estado": "ACTIVO"
}

Por nombre: un arreglo de esos objetos. Si no hay resultado: 404

{ "mensaje": "Persona o RUC no encontrado." }

2. Probar la API Key

GET https://ws.a3.com.py/centroservicios/api/ruc/v1/test

Códigos HTTP

• 200 — OK
• 400 — Falta documento/ruc/nombre, o el nombre es muy corto
• 401 — Sin API Key o inválida
• 403 — Sistema suspendido o IP no autorizada
• 404 — No está en el padrón
• 429 — Más de 20 consultas en el último minuto (Retry-After: 60)

Ejemplo JavaScript

const API = "https://ws.a3.com.py/centroservicios";
const KEY = "tu-api-key";

async function buscarRuc(documento) {
  const url = API + "/api/ruc/v1/lookup?documento=" + encodeURIComponent(documento);
  const res = await fetch(url, { headers: { "X-API-Key": KEY } });
  if (res.status === 404) return null;
  if (!res.ok) throw new Error("Error " + res.status);
  return res.json();
}