Consulta datos de una empresa por RUT

GET

/v1/consultar-rut/{rut}

• Producción
• Homologación / pruebas

Consulta el padrón de DGI por RUT y devuelve los datos básicos de la empresa.

Modos de respuesta

• ?pretty=true (default) — Devuelve un DTO normalizado y en español con los campos más usados: rut, denominacion, direccion, ciudad, departamento, nombreFantasia, telefono1, telefono2, email.
• ?pretty=false — Devuelve la respuesta cruda de DGI. Útil si necesitás campos avanzados que el pretty no expone (actividades, contactos múltiples, etc.).

Casos de uso

• Auto-completar formularios de alta de cliente cuando el operador ingresa un RUT.
• Validar contra padrón que el RUT exista antes de emitir una e-Factura.

Performance y cacheo

Cada consulta hace una llamada en vivo al servicio de padrón de DGI y no se cachea del lado del servidor. Si vas a validar muchos RUT (por ejemplo, para autocompletar), conviene cachear el resultado del lado de tu integración para no repetir consultas del mismo RUT.

Autorizaciones

• BearerAuth

Parámetros

Parámetros de path

rut

required

string

>= 1 characters

Parámetros de query

pretty

string

Allowed values: true false

Respuestas

200

Datos de la empresa según pretty

nullable

Ejemplos

Datos normalizados (pretty=true, default)

{
  "data": {
    "rut": "219999830019",
    "denominacion": "EMPRESA EJEMPLO S.A.",
    "direccion": "18 DE JULIO 1234",
    "ciudad": "MONTEVIDEO",
    "departamento": "MONTEVIDEO",
    "nombreFantasia": "Empresa Ejemplo",
    "telefono1": "29010000",
    "telefono2": "",
    "email": "contacto@empresa-ejemplo.com.uy"
  }
}

401

No autenticado. La API_KEY no fue enviada o no es válida.

Códigos posibles: API_AUTH_HEADER_MISSING, API_AUTH_HEADER_INVALID, API_ACCESS_INVALID.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Falta header Authorization

{
  "error": {
    "code": "API_AUTH_HEADER_MISSING",
    "message": "Se esperaba la cabecera Authorization con esquema Bearer"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Secret key inválida o revocada

{
  "error": {
    "code": "API_ACCESS_INVALID",
    "message": "Acceso no autorizado"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

403

Acceso prohibido. La credencial es válida pero el plan o el alcance de sucursal lo impiden.

Códigos posibles: API_FEATURE_DISABLED, API_ACCESS_BRANCH_MISMATCH.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

El plan no incluye API

{
  "error": {
    "code": "API_FEATURE_DISABLED",
    "message": "El plan de esta cuenta no tiene habilitado el acceso a la API"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Header x-branch-id distinto al fijo del ApiAccess

{
  "error": {
    "code": "API_ACCESS_BRANCH_MISMATCH",
    "message": "El ApiAccess está fijado a otra sucursal y no coincide con x-branch-id"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

429

Rate limit excedido. Esperá los segundos indicados en el header Retry-After.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Excediste el rate limit

{
  "error": {
    "code": "API_RATE_LIMITED",
    "message": "Se superó el límite de requests para esta API key"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Headers

Retry-After

integer

Ejemplo

42

Segundos hasta que se libera la ventana de rate limit

500

Error consultando DGI (timeout, downtime del servicio padrón, RUT inexistente)

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

DGI no respondió

{
  "error": {
    "code": "RUT_LOOKUP_FAILED",
    "message": "Error consultando datos de RUC"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}