API de OwnData

Usa la sesión del navegador y el mismo origen; no lleva X-API-Key. Free100 cobra resultados completos y 404 válidos nuevos. Con la caché habilitada, el mismo RUC, cuenta y día Paraguay no vuelve a descontar, incluso entre web y API: alreadyConsulted=true y charged=false. cacheEnabled=false indica que aún funciona sin deduplicación; su activación requiere una migración autorizada. DV inválido y errores propios no cobran.

await fetch("/api/account/ruc", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ ruc: "80121686-9" }),
});

{
  "data": {
    "ruc": "80121686",
    "fullRuc": "80121686-9",
    "dv": "9",
    "nameOfficial": "EMPRESA DE EJEMPLO S.A.",
    "equivalenceRaw": "",
    "stateRaw": "ACTIVO",
    "sourcePartition": 0
  },
  "provenance": {
    "source": "dnit_official_snapshot",
    "sourcePage": "https://www.dnit.gov.py/en/web/portal-institucional/listado-de-ruc-con-sus-equivalencias",
    "publicationDate": "2026-10-01",
    "publishedText": "Publicación oficial de ejemplo",
    "importedAt": "2026-10-02T00:00:00Z",
    "snapshotHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "fullRuc": "80121686-9",
  "alreadyConsulted": false,
  "charged": true,
  "cacheEnabled": true,
  "allowance": {
    "visitorUsed": 1,
    "visitorLimit": 100,
    "remaining": 99,
    "day": "2026-10-03",
    "resetTimeZone": "America/Asuncion",
    "resetAtLocal": "00:00",
    "blocked": false
  }
}

{
  "fullRuc": "80121686-9",
  "canonicalPath": "/ruc/80121686-9",
  "data": {
    "fullRuc": "80121686-9",
    "nameOfficial": "EMPRESA DE EJEMPLO S.A.",
    "stateRaw": "ACTIVO"
  },
  "allowance": {
    "blocked": false,
    "visitorUsed": 1,
    "visitorLimit": 10,
    "remaining": 9,
    "dailyUsed": 1,
    "dailyLimit": 10,
    "monthlyUsed": 1,
    "monthlyLimit": 20,
    "day": "2026-10-03",
    "month": "2026-10",
    "resetTimeZone": "America/Asuncion",
    "resetAtLocal": "00:00",
    "accounting": "Reserved demo lookups, including not-found and unavailable data. Independent demo allowance."
  }
}

Con GET en las rutas web de cuenta y demo consultás el cupo sin consumirlo. Desde tu servidor, usá GET /api/v1/ruc/{ruc} con X-API-Key y una clave personal free: esta ruta consulta el RUC y puede consumir cupo; no requiere activar la API comercial paga. La consulta web depende de la sesión del navegador.

El endpoint acepta un RUC completo o su base registrada y responde con datos publicados, cuota y procedencia. La autorización legal de redistribución es la dependencia de lanzamiento: hasta entonces no se habilita ni se emiten claves.

curl --request GET \
  --url https://app.controlaria.online/api/v1/ruc/80121686-9 \
  --header 'X-API-Key: od_test_TU_CLAVE' \
  --header 'Accept: application/json'

{
  "data": {
    "ruc": "80121686",
    "fullRuc": "80121686-9",
    "dv": "9",
    "nameOfficial": "EMPRESA DE EJEMPLO S.A.",
    "equivalenceRaw": "",
    "stateRaw": "ACTIVO"
  },
  "requestId": "req_1f0c2a9d4b7e4c8f9a0b1d2e",
  "meta": {
    "environment": "test",
    "quota": { "limit": 300, "used": 1, "remaining": 299, "day": "2026-10-03", "resetAfter": 54000 },
    "accounting": { "alreadyConsulted": false, "charged": true },
    "provenance": {
      "source": "dnit_official_snapshot",
      "sourcePage": "https://www.dnit.gov.py/en/web/portal-institucional/listado-de-ruc-con-sus-equivalencias",
      "publicationDate": "2026-10-01",
      "publishedText": "Publicación oficial de ejemplo",
      "importedAt": "2026-10-02T00:00:00Z",
      "snapshotHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  }
}

• Cobra una vez cada intento válido: encontrado, sin registro o base no disponible.
• No reintenta automáticamente. La demo mantiene su cobro por intento; una reconsulta personal en caché no descuenta de nuevo.
• No uses claves comerciales desde el navegador; son de servidor.

La clave va en el encabezado X-API-Key desde tu servidor. Las claves personales free son independientes por aplicación y comparten el cupo de tu cuenta. Tienen alcance ruc:read, vencimiento obligatorio, rotación con solapamiento y revocación inmediata. Solo se guarda el hash: el texto plano se muestra una única vez al crearla o rotarla. Las claves comerciales pertenecen a una empresa y entorno; su uso sigue deshabilitado.

Hay dos niveles: la clave free de la cuenta se emite y se revela una vez desde la propia cuenta, sin verificación de correo; las claves comerciales las gestiona un propietario o administrador de la empresa activa.

La gestión por empresa (crear, rotar, revocar, definir cupo) requiere una sesión verificada con rol propietario o administrador en la empresa activa.

El documento OpenAPI 3.1 describe las rutas, las respuestas, los encabezados de cuota y los códigos estables. Cambiar un campo o un código publicado es una decisión de versión, no un refactor.

curl --request GET \
  --url https://app.controlaria.online/api/v1/openapi.json \
  --header 'Accept: application/json'

{
  "openapi": "3.1.0",
  "info": { "title": "OwnData Commercial RUC API", "version": "1.2.0" },
  "paths": {
    "/api/v1/ruc/{ruc}": {
      "get": { "operationId": "getRucV1", "security": [{ "ApiKey": [] }] }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    }
  },
  "x-owndata-legal-gate": { "status": "disabled-by-default" }
}

Versión publicada: 1.2.0. El interruptor de habilitación y el límite legal están documentados dentro del propio contrato.

La API free comparte 100 consultas diarias por cuenta entre claves, web y lotes personales. La API comercial, aún deshabilitada, define 300, 1.000 o un cupo a medida por empresa. El día se reinicia a medianoche en America/Asuncion. Solo un resultado completo o 404 válido nuevo cobra una unidad; DV inválido y errores propios o del dataset no cobran. Con cacheEnabled=true, las reconsultas personales del mismo RUC y día no cobran, incluso con el cupo agotado; cacheEnabled=false no deduplica. meta.accounting informa charged y alreadyConsulted.

La consulta web no se cobra con estas cuotas: Free100 usa 100 por día y la demo tiene su propio límite compartido.

La clave free de la cuenta tampoco usa estas cuotas: comparte el cupo Free100 de 100 consultas por día. Sus respuestas incluyen RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset, y un 429 con Retry-After cuando se agota.

El código es el contrato; el mensaje es informativo. Los rechazos de autenticación, formato, alcance, plan y cuota no se cobran. Un 404 válido puede ser un resultado nuevo o una reconsulta en caché: revisá meta.accounting.charged. Un 429 DAILY_QUOTA_REACHED incluye Retry-After en segundos; esperá el reinicio y no reintentes automáticamente. Los ejemplos hacen una sola solicitud y no prueban una integración externa productiva.

{
  "error": {
    "code": "REGISTERED_RUC_NOT_FOUND",
    "message": "No record exists for that RUC in the active dataset."
  },
  "meta": {
    "environment": "test",
    "quota": { "limit": 300, "used": 2, "remaining": 298, "day": "2026-10-03", "resetAfter": 53999 },
    "accounting": { "alreadyConsulted": false, "charged": true }
  }
}

Errores de la consulta web

La respuesta conserva la publicación oficial que la originó. La hora de respuesta no es la fecha de publicación: usá provenance para saber qué copia respondió.

source

dnit_official_snapshot

Origen oficial de la base importada.

sourcePage

https://www.dnit.gov.py/…

Página oficial de la publicación usada.

publicationDate

2026-10-01

Fecha de publicación DNIT (YYYY-MM-DD).

publishedText

Publicación oficial

Etiqueta oficial conservada textualmente.

importedAt

2026-10-02T00:00:00Z

Momento de importación de la copia OwnData.

snapshotHash

0123…def

Hash de la base importada; permite verificar la misma copia.

No se promete intervalo de actualización, cobertura, resultado de posicionamiento ni SLA. Esas afirmaciones requieren autorización escrita y comportamiento medido.

1. 1

   Separá las credenciales: la web usa sesión; tu servidor usa X-API-Key con una clave personal free. Las claves comerciales por empresa siguen deshabilitadas.

2. 2

   Validá el RUC completo con su dígito verificador antes de enviarlo.

3. 3

   Esperá el cupo: respetá Retry-After y no reintentes automáticamente. Solo los resultados completos y 404 válidos nuevos cobran; la caché personal evita un segundo descuento.

4. 4

   Guardá la procedencia junto al dato: fuente, fecha de publicación, texto publicado y hash de la base.

5. 5

   No derives identidad ni nombres normalizados: en v1 solo existen los campos publicados.