La API v1 de OwnData resuelve un RUC exacto con una sola llamada: GET https://app.controlaria.online/api/v1/ruc/{ruc} con el encabezado X-API-Key. El valor {ruc} acepta el par completo base-DV o la base registrada. El contrato se publica en formato OpenAPI 3.1 en /api/v1/openapi.json y es la fuente de verdad: si esta guía y el contrato difieren, manda el contrato.
Las respuestas no vienen de una conexión en vivo con la DNIT. OwnData consulta una publicación oficial de la DNIT que importó como snapshot, y cada respuesta exitosa conserva en meta.provenance la fuente, la fecha de publicación, el texto publicado, la fecha de importación y el hash del snapshot. Eso permite mostrar o guardar de dónde sale cada dato. OwnData es independiente de la DNIT: para trámites tributarios corresponde usar los servicios oficiales.
Un 200 trae data con ruc (base), fullRuc, dv, nameOfficial, equivalenceRaw y stateRaw, más requestId y meta con el entorno, el cupo (límite, usadas, restantes, día y segundos hasta el reinicio), la procedencia y la contabilidad de la consulta. nameOfficial, equivalenceRaw y stateRaw se devuelven tal como los publica la fuente, sin normalizar. Opcionalmente, nameMethods y subjectKind=individual agregan vistas del nombre, solo si quien llama confirma que se trata de una persona.
Los errores usan un sobre con error.code y error.message. Conviene ramificar por el código, que es estable, y no por el mensaje, que es informativo y está en inglés. Hay códigos para formato inválido (INVALID_RUC_FORMAT), dígito verificador incorrecto (INVALID_RUC_DV), clave ausente, inválida, revocada o vencida, registro no encontrado (REGISTERED_RUC_NOT_FOUND), cupo diario agotado (DAILY_QUOTA_REACHED, con Retry-After) y servicio o dataset no disponible (503).
La clave gratuita se crea desde la cuenta, en Cuenta, Claves personales, y se muestra una sola vez. Es solo para uso del lado servidor: nunca debe viajar en código de navegador o de una app móvil. El nivel gratuito comparte 100 consultas por día con la consulta web, y los planes comerciales no están habilitados. Un 200 nuevo o un 404 válido cuentan una consulta; los rechazos por formato, DV, autenticación o límite previo, y los fallos 503, no descuentan cupo.
Para empezar: creá una cuenta, generá la clave, probá con un RUC de tu propia base desde tu servidor y guardá fullRuc, nameOfficial y la fecha de publicación del snapshot junto al dato. Antes de pasar a producción, revisá el contrato completo y definí qué hace tu aplicación ante 404, 429 y 503.