Saltar al contenido
TDCOM Datos de contribuyentes Entrar Crear cuenta

Documentación de la API

Consulta los datos de un contribuyente por su RUT. Es una API HTTP que responde JSON: sirve desde cualquier lenguaje.

Dirección base
https://rut.tdcom.cl
Formato
JSON, UTF-8
Tope por minuto
120 consultas

Primeros pasos

  1. Consigue tu llave. Crea tu cuenta y sácala en tu panel. Empieza con dc_ y se muestra una sola vez: guárdala en un lugar seguro.
  2. Haz tu primera consulta. Reemplaza dc_tu_llave por tu llave y ejecuta:
    curl -s "https://rut.tdcom.cl/v1/contribuyentes/78348672-5" \
      -H "Authorization: Bearer dc_tu_llave"
    
  3. Lee la respuesta. Los datos principales están arriba (razon_social, correo_dte, direccion); las listas para elegir, en sucursales y giros; y los valores para Odoo, en odoo. Ver una respuesta completa.

Usa la llave solo desde tu servidor. En una página web o una app quedaría a la vista de cualquiera: haz la consulta desde tu backend y entrega el resultado a tu página.

Ejemplos por lenguaje

Cada ejemplo está completo: consulta el RUT 78348672-5, revisa si hubo error y muestra la razón social. Cópialo, pon tu llave y ejecútalo.

curl

curl -s "https://rut.tdcom.cl/v1/contribuyentes/78348672-5" \
  -H "Authorization: Bearer dc_tu_llave"

Para ejecutarlo: En la terminal.

Autenticación

Cada petición lleva tu llave en una cabecera. Sirve cualquiera de las dos formas:

Authorization: Bearer dc_tu_llave
X-API-Key: dc_tu_llave

Si la llave se filtra, pide que la revoquemos y te damos otra: puedes tener varias a la vez, por ejemplo una por sistema.

Rutas

RutaPara qué
GET /saludEstado del servicio
GET /v1/contribuyentes/{rut}Datos de un contribuyente
GET /v1/contribuyentes/{rut}/sucursalesBuscar entre las sucursales vigentes de un RUT
POST /v1/contribuyentes/loteConsultar varios RUT de una vez
GET /v1/cuentaPlan y consumo del mes

GET /salud

Estado del servicio

Responde: Salud.

GET /v1/contribuyentes/{rut}

Datos de un contribuyente

Razón social, tipo de persona, direcciones, giros y correo DTE de un RUT, más el bloque `odoo` listo para `res.partner`. Cuenta una consulta, esté o no el RUT en la base; un RUT inválido no se cobra.

El correo y la resolución DTE se verifican en línea con el SII la primera vez que se pide el RUT y después cada cierto tiempo (`dte.fuente` es `en_linea`). Si el SII no responde, se entrega lo del listado masivo.

ParámetroVa enTipoDescripción
rutrutatextoRUT con dígito verificador, con o sin puntos y guion.
sucursalesconsultaenteroCuántas sucursales vigentes incluir. Por defecto: 50.

Responde: Contribuyente. Errores: 401, 404, 422, 429.

GET /v1/contribuyentes/{rut}/sucursales

Buscar entre las sucursales vigentes de un RUT

Para empresas con muchas sucursales (hay RUT con cientos). Cuenta una consulta.

ParámetroVa enTipoDescripción
rutrutatextoRUT con dígito verificador, con o sin puntos y guion.
qconsultatexto o nullTexto en calle, número, comuna o ciudad.
limiteconsultaentero Por defecto: 50.
desdeconsultaentero Por defecto: 0.

Responde: Sucursales. Errores: 401, 422, 429.

POST /v1/contribuyentes/lote

Consultar varios RUT de una vez

Hasta 100 RUT por llamada, para actualizar contactos existentes. Se cobra una consulta por cada RUT válido y distinto; si no caben en la cuota, no se procesa ninguno. El lote no consulta al SII en línea: entrega lo guardado (incluido lo ya verificado en consultas individuales).

Cuerpo (JSON): PeticionLote. Responde: RespuestaLote. Errores: 401, 422, 429.

GET /v1/cuenta

Plan y consumo del mes

No cuenta como consulta.

Responde: EstadoCuenta. Errores: 401.

La respuesta

Esto responde GET /v1/contribuyentes/78348672-5. Para que se lea, aquí va con una sola sucursal y dos giros; la respuesta real los trae todos.

{
  "rut": "78348672-5",
  "rut_numero": 78348672,
  "dv": "5",
  "razon_social": "TECNOLOGÍA E INNOVACIÓN TDCOM SPA",
  "tipo_persona": "juridica",
  "subtipo": {
    "codigo": 223,
    "nombre": "SOCIEDAD POR ACCIONES",
    "tipo": "PERSONA JURIDICA COMERCIAL"
  },
  "fecha_inicio": "2026-02-03",
  "fecha_termino_giro": null,
  "vigente": true,
  "correo_dte": "dte@tdcom.cl",
  "resolucion_dte": {
    "numero": "80",
    "fecha": "2014-08-22"
  },
  "dte": {
    "fuente": "listado",
    "autorizado": true,
    "verificado_en": null,
    "documentos": []
  },
  "direccion": {
    "id": 3879628,
    "tipo": "DOMICILIO",
    "vigente": true,
    "direccion": "APOQUINDO 6410 OF 1004 PS 10",
    "calle": "APOQUINDO 6410 OF 1004 PS 10",
    "numero": null,
    "bloque": null,
    "departamento": null,
    "villa_poblacion": null,
    "ciudad": null,
    "comuna": "LAS CONDES",
    "region": "XIII REGION METROPOLITANA",
    "region_iso": "CL-RM",
    "region_numero": 13,
    "fecha": "2026-02-04"
  },
  "sucursales": [
    {
      "id": 3879628,
      "tipo": "DOMICILIO",
      "vigente": true,
      "direccion": "APOQUINDO 6410 OF 1004 PS 10",
      "calle": "APOQUINDO 6410 OF 1004 PS 10",
      "numero": null,
      "bloque": null,
      "departamento": null,
      "villa_poblacion": null,
      "ciudad": null,
      "comuna": "LAS CONDES",
      "region": "XIII REGION METROPOLITANA",
      "region_iso": "CL-RM",
      "region_numero": 13,
      "fecha": "2026-02-04"
    }
  ],
  "sucursales_total": 1,
  "giros": [
    {
      "codigo": "620200",
      "descripcion": "ACTIVIDADES DE CONSULTORIA DE INFORMATICA Y DE GESTION DE INSTALACIONES INFORMATICAS",
      "afecta_iva": true,
      "categoria_tributaria": 1,
      "fecha": "2026-02-03"
    }
  ],
  "actualizado_en": "2026-11-10T01:41:49.692005-03:00",
  "odoo": {
    "name": "TECNOLOGÍA E INNOVACIÓN TDCOM SPA",
    "vat": "78348672-5",
    "company_type": "company",
    "street": "APOQUINDO 6410 OF 1004 PS 10",
    "street2": null,
    "city": "LAS CONDES",
    "state_iso": "CL-RM",
    "state_numero": 13,
    "country_code": "CL",
    "l10n_cl_activity_description": "ACTIVIDADES DE CONSULTORIA DE INFORMATICA Y DE GESTION DE INSTALACIONES INFORMATICAS",
    "l10n_cl_dte_email": "dte@tdcom.cl",
    "l10n_cl_sii_taxpayer_type": "1"
  }
}
  • direccion es el domicilio vigente. sucursales son las direcciones vigentes para que el usuario elija, con el domicilio primero; cada una tiene un id estable.
  • sucursales_total dice cuántas hay. Si son más de las que pediste, usa la ruta de sucursales para buscar.
  • dte.fuente dice de dónde salen correo_dte y resolucion_dte: en_linea (verificado en el SII, con los documentos autorizados) o listado (el listado masivo del SII, que puede venir atrasado).
  • odoo repite lo necesario con los nombres de campo de un contacto de Odoo.
  • Lo que el SII no publica viene en null o en una lista vacía, nunca falta el campo.

Campos

Contribuyente

CampoTipoDescripción
ruttexto
rut_numeroentero
dvtexto
razon_socialtexto o null
tipo_personatextojuridica o natural.
subtipoSubtipo o null
fecha_iniciofecha (AAAA-MM-DD) o null
fecha_termino_girofecha (AAAA-MM-DD) o null
vigentesí/nofalse si tiene término de giro.
correo_dtetexto o nullCorreo de intercambio de documentos electrónicos.
resolucion_dteResolucionDte o null
dteDte
direccionDireccion o nullDomicilio vigente; si no hay direcciones vigentes, la más reciente.
sucursaleslista de DireccionDirecciones vigentes para elegir, con el domicilio primero.
sucursales_totalenteroTotal de direcciones vigentes; si supera las entregadas, usa /sucursales.
giroslista de GiroTodos los giros, el más reciente primero.
actualizado_enfecha y hora (ISO 8601)
odooDatosOdoo

Dte

CampoTipoDescripción
fuentetexto o nullDe dónde salen correo_dte y resolucion_dte: en_linea (verificado en el SII), listado (listado masivo, puede venir atrasado) o null si no hay datos.
autorizadosí/noSi es emisor autorizado de documentos electrónicos.
verificado_enfecha y hora (ISO 8601) o nullCuándo se verificó en línea con el SII.
documentoslista de DocumentoDteDocumentos autorizados (solo con fuente en_linea).

DocumentoDte

CampoTipoDescripción
codigoenteroCódigo del documento, p. ej. 33 (factura electrónica).
descripciontexto o null
autorizadofecha (AAAA-MM-DD) o null
desautorizadofecha (AAAA-MM-DD) o null

Direccion

CampoTipoDescripción
identeroIdentificador estable de la dirección: lo que el usuario elige.
tipotextoDOMICILIO o SUCURSAL.
vigentesí/no
direcciontextoCalle, número, bloque y departamento en una línea.
calletexto o null
numerotexto o null
bloquetexto o null
departamentotexto o null
villa_poblaciontexto o null
ciudadtexto o null
comunatexto o null
regiontexto o nullTexto del SII, p. ej. XIII REGION METROPOLITANA.
region_isotexto o nullCódigo ISO 3166-2:CL, p. ej. CL-RM.
region_numeroentero o nullNúmero de la región (1 a 16).
fechafecha (AAAA-MM-DD) o null

Giro

CampoTipoDescripción
codigotexto
descripciontexto o null
afecta_ivasí/no o null
categoria_tributariaentero o null
fechafecha (AAAA-MM-DD) o null

Subtipo

CampoTipoDescripción
codigoentero
nombretexto o null
tipotexto o null

ResolucionDte

CampoTipoDescripción
numerotexto o null
fechafecha (AAAA-MM-DD) o null

DatosOdoo

Valores listos para res.partner con la localización chilena (l10n_cl).

CampoTipoDescripción
nametexto o null
vattexto
company_typetextocompany o person.
streettexto o null
street2texto o null
citytexto o nullComuna.
state_isotexto o nullPara buscar res.country.state: ISO 3166-2:CL.
state_numeroentero o null
country_codetexto
l10n_cl_activity_descriptiontexto o nullGiro más reciente.
l10n_cl_dte_emailtexto o null
l10n_cl_sii_taxpayer_typetexto o nullSugerido: "1" afecto a IVA, "2" boletas de honorarios; null si no hay giros.

Sucursales

CampoTipoDescripción
totalentero
desdeentero
sucursaleslista de Direccion

PeticionLote

CampoTipoDescripción
rutslista de texto

RespuestaLote

CampoTipoDescripción
resultadoslista de ResultadoLote
consultas_cobradasentero

ResultadoLote

CampoTipoDescripción
ruttextoEl RUT tal como se pidió.
estadotextoencontrado, no_encontrado o rut_invalido.
contribuyenteContribuyente o null

EstadoCuenta

CampoTipoDescripción
clientetexto
plantexto
periodotextoMes en que partió el ciclo en curso.
periodo_desdefecha (AAAA-MM-DD)Primer día del ciclo de 30 días en curso.
se_renuevafecha (AAAA-MM-DD)Día en que la cuota vuelve a cero.
consultas_mesentero
usadasentero
restantesentero

Errores y cuotas

Todos los errores tienen la misma forma. Usa codigo en tu programa y muestra mensaje a la persona:

{"error": {"codigo": "rut_invalido", "mensaje": "El RUT no es válido (revisa el dígito verificador)."}}
EstadoCódigoQué pasó¿Se cobra?
401no_autorizadoFalta la llave o no es válida (revocada, o cliente suspendido).No
403ip_no_autorizadaLa llave de prueba ya se usó desde otra conexión. Libérala en tu cuenta o contrata un plan.No
404no_encontradoEl RUT es válido pero no está en la base.Sí
422rut_invalidoEl RUT no es válido: revisa el dígito verificador.No
422peticion_invalidaFalta un dato o viene con otro formato (p. ej. un lote vacío).No
429demasiadas_consultasPasaste el tope de consultas por minuto. Espera y reintenta.No
429cuota_agotadaSe acabaron las consultas del mes de tu plan.No
413peticion_demasiado_grandeEl cuerpo de la petición supera 1 MB.No

Cada respuesta de consulta trae tres cabeceras con tu cuota del mes:

X-Cuota-Limite: 10000
X-Cuota-Usadas: 1234
X-Cuota-Restantes: 8766
  • Se cobra una consulta por cada RUT válido consultado, esté o no en la base.
  • En un lote se cobra una por cada RUT válido y distinto. Si no caben en tu cuota, no se procesa ninguno.
  • Ver tu cuenta (GET /v1/cuenta) no se cobra.
  • La cuota se renueva cada 30 días, contados desde que partió tu plan. GET /v1/cuenta dice el día (se_renueva).
  • La llave del plan de prueba queda atada a la primera conexión (IP) que la usa. Desde otra responde 403; puedes liberarla en tu cuenta una vez al día.

Odoo

El bloque odoo de la respuesta trae los valores con los nombres de campo del contacto. Este método, dentro de un módulo propio, completa la ficha a partir del RUT:

# Dentro de un módulo propio de Odoo (18 a 20). Agrega un botón en la ficha del
# contacto que llame a action_completar_desde_sii. Guarda la URL y la llave en
# Ajustes > Técnico > Parámetros del sistema, no en el código.
import requests

from odoo import _, models
from odoo.exceptions import UserError


class ResPartner(models.Model):
    _inherit = "res.partner"

    def action_completar_desde_sii(self):
        self.ensure_one()
        parametros = self.env["ir.config_parameter"].sudo()
        url = parametros.get_param("contribuyentes.url")      # https://rut.tdcom.cl
        llave = parametros.get_param("contribuyentes.llave")  # dc_tu_llave
        if not self.vat:
            raise UserError(_("Escribe primero el RUT del contacto."))

        respuesta = requests.get(
            f"{url}/v1/contribuyentes/{self.vat}",
            headers={"Authorization": f"Bearer {llave}"},
            timeout=15,
        )
        datos = respuesta.json()
        if respuesta.status_code != 200:
            raise UserError(datos["error"]["mensaje"])

        odoo = datos["odoo"]
        region = self.env["res.country.state"].search(
            [("country_id.code", "=", "CL"), ("code", "=", odoo["state_iso"])], limit=1)
        # (revisa en tu versión de Odoo cómo vienen los códigos de región)
        self.write({
            "name": odoo["name"],
            "company_type": odoo["company_type"],
            "street": odoo["street"],
            "street2": odoo["street2"],
            "city": odoo["city"],
            "state_id": region.id,
            "country_id": self.env.ref("base.cl").id,
            "l10n_cl_activity_description": odoo["l10n_cl_activity_description"],
            "l10n_cl_dte_email": odoo["l10n_cl_dte_email"],
        })
        # datos["sucursales"] y datos["giros"] traen las listas completas, por si
        # quieres que el usuario elija otra dirección u otro giro.

Los nombres l10n_cl_* son los de la localización chilena. Confírmalos en tu versión de Odoo antes de usarlo en producción.

Asistentes de IA (MCP)

El servicio también se puede usar desde un asistente de IA con MCP (Model Context Protocol). Lo conectas una vez y después le pides en la conversación «busca los datos del RUT 78348672-5».

Dirección del servidor
https://rut.tdcom.cl/mcp
Transporte
HTTP (Streamable HTTP)
Acceso
Tu llave, en Authorization: Bearer

Usa la misma llave de la API y la misma cuota: cada RUT que consulta el asistente cuenta como una consulta. Las herramientas son solo de lectura.

HerramientaQué hace¿Se cobra?
consultar_contribuyenteLos datos de un RUT, con sus primeras sucursales y todos sus giros.1
buscar_sucursalesBusca entre las direcciones vigentes de un RUT por calle, comuna o ciudad.1
consultar_variosResumen de hasta 25 RUT en una llamada.1 por RUT válido y distinto
estado_de_cuentaTu plan y cuántas consultas te quedan este mes.No

Claude Code

En la terminal, una sola vez:

claude mcp add --transport http contribuyentes https://rut.tdcom.cl/mcp \
  --header "Authorization: Bearer dc_tu_llave"

Cursor

En el archivo .cursor/mcp.json de tu proyecto (o en el global):

{
  "mcpServers": {
    "contribuyentes": {
      "url": "https://rut.tdcom.cl/mcp",
      "headers": { "Authorization": "Bearer dc_tu_llave" }
    }
  }
}

VS Code

En el archivo .vscode/mcp.json:

{
  "servers": {
    "contribuyentes": {
      "type": "http",
      "url": "https://rut.tdcom.cl/mcp",
      "headers": { "Authorization": "Bearer dc_tu_llave" }
    }
  }
}

Claude Desktop y otros que solo aceptan servidores locales

Usa el puente mcp-remote (necesita Node). En el archivo de configuración del asistente:

{
  "mcpServers": {
    "contribuyentes": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://rut.tdcom.cl/mcp",
               "--header", "Authorization: Bearer dc_tu_llave"]
    }
  }
}

La llave queda guardada en la configuración de tu asistente. Si compartes ese archivo o el equipo, pide una llave aparte para el asistente: así puedes revocarla sin afectar a tu sistema.