Ir al contenido

Clientes y proveedores

Esta ficha explica cómo administrar la agenda de clientes (a quienes les vendes) y de proveedores (a quienes les compras) de la empresa: darlos de alta, guardar sus notas internas y su nombre de fantasía, registrar a quién avisar cuando se les emite un documento, y bloquearlos para que no se les emita.

Un cliente o proveedor no es un contribuyente nuevo: es un RUT que ya existe en el registro de contribuyentes y que tu empresa asocia a su agenda. Los datos tributarios (razón social, giro, direcciones, actividades) los trae el registro; lo tuyo, privado de tu empresa, son las notas, el nombre de fantasía, los contactos de aviso y el bloqueo.

  • Dar de alta un cliente o proveedor por su RUT, con datos que ya vienen del SII.
  • Guardar un nombre de fantasía que se imprime en el PDF al emitirle un documento.
  • Registrar los correos y celulares a los que se avisa cuando se le emite un documento (la «agenda de destinatarios»).
  • Bloquear a un cliente o proveedor (con motivo) para que no se le emitan documentos, y desbloquearlo.
  • Buscar proveedores por RUT o por texto.

Lo que cuesta cada operación de estas dos agendas, y la emisión que las usa (Documentos tributarios electrónicos), depende de tu plan: redcumbre tarifas --produccion.

QuéDetalle
Llave de la empresaRol FULL-API. En el modo de prueba, la de keys/redcumbre-prueba.json. No necesitas un emisor.
El RUT en el registro de contribuyentescrearCliente y crearProveedor responden 404 si el RUT no está registrado. Para registrarlo, consúltalo antes con Consulta de RUT (consultarRutEnSii): esa consulta lo deja registrado con los datos del SII. En producción esa consulta va al SII; su precio: redcumbre tarifas consultarRutEnSii --produccion.
Qué RUT usar en el modo de pruebaEl registro sólo reconoce los diez RUT de prueba (ver Modo de prueba y producción). Seis ya vienen cargados como clientes (88888888-8, 66666666-6, 55555555-5, 22222222-2, 33333333-3, 12345678-5) y cuatro como proveedores (88888888-8, 22222222-2, 33333333-3, 12345678-5).

Hay tres cosas que conviene saber antes de empezar:

  • No existe una operación publicada para listar ni buscar clientes. El id de un cliente sale de la respuesta de crearCliente. Los proveedores sí se pueden listar (listarProveedores) y buscar por RUT (obtenerProveedorPorRut).
  • Los clientes y proveedores también nacen solos. Al emitir un documento, si el receptor no existe en tu agenda, la plataforma lo crea (a menos que mandes crearMaestroCliente: false en emitirDte). Su origenCreacion te dice de dónde vino: MANUAL es el que diste de alta tú.
  • Cliente y proveedor son agendas separadas. Un mismo RUT puede estar en las dos con ids distintos.

Los ejemplos usan el modo de prueba. Los datos que crees ahí se suprimen solos a los 30 días y redcumbre restaurar --confirmar <slug> los borra en el acto.

  1. Da de alta un cliente. Con 77777777-7, un RUT de prueba que aún no es cliente:

    {
    "rut": "77777777-7",
    "notasInternas": "Cliente de prueba, pago a 30 días",
    "nombreFantasia": "Empresa de Prueba"
    }
    Ventana de terminal
    redcumbre api crearCliente --cuerpo @cliente.json

    Resultado esperado: 201 con el cliente completo y sandbox: true. Guarda el id: es lo único con lo que después lo consultas. nombreFantasia y notasInternas son opcionales; el nombre de fantasía no viene del SII, es tuyo, y al emitirle un documento precarga el campo del mismo nombre. Con un RUT que ya es cliente responde 409 (CLIENTE_YA_EXISTE); con un RUT que el registro no conoce, 404.

    {
    "id": "clcliente0001",
    "createdAt": "2026-11-05T12:00:00.000Z",
    "updatedAt": "2026-11-05T12:00:00.000Z",
    "rut": "77777777-7",
    "razonSocial": "EMPRESA DE PRUEBA RCAPI SPA",
    "giro": "SERVICIOS DE PRUEBA",
    "giroDeLaFactura": "SERVICIOS DE PRUEBA",
    "actividadDelGiro": null,
    "tipoContribuyente": "PERSONA_JURIDICA",
    "direcciones": [],
    "actividadesEconomicas": [],
    "emailsDte": [],
    "telefonosDte": [],
    "emailIntercambio": null,
    "nroResolucionSii": null,
    "fechaResolucionSii": null,
    "documentosAutorizadosSii": null,
    "contribuyenteAutorizadoSii": null,
    "ultimaConsultaContribuyente": null,
    "bloqueado": false,
    "motivoBloqueo": null,
    "fechaBloqueo": null,
    "bloqueadoPorId": null,
    "notasInternas": "Cliente de prueba, pago a 30 días",
    "nombreFantasia": "Empresa de Prueba",
    "infoPagoHtml": null,
    "origenCreacion": "MANUAL",
    "ultimaSincronizacionSii": null,
    "condicionPagoDefectoId": null,
    "condicionPagoDefecto": null,
    "sandbox": true
    }
  2. Lee el cliente.

    Ventana de terminal
    redcumbre api obtenerCliente --param id=<id>

    Resultado esperado: 200 con los mismos campos. 404 si el id no existe en tu empresa (o es de producción y usas una llave de prueba).

  3. Edita lo que es tuyo. actualizarCliente cambia las notas internas, la condición de pago por defecto y el nombre de fantasía. Omitir una clave la deja intacta; null (o una cadena vacía, en el nombre de fantasía) la borra; un valor la reemplaza. Lo que ya emitiste conserva el nombre de fantasía que tenía:

    {
    "nombreFantasia": null,
    "notasInternas": "Pasó a pago al contado"
    }
    Ventana de terminal
    redcumbre api actualizarCliente --param id=<id> --cuerpo @cambios.json

    Resultado esperado: 200 con el cliente actualizado. No se pueden editar la razón social ni los datos tributarios: vienen del registro. Un cliente de ejemplo precargado en el modo de prueba se rechaza al editarlo.

  4. Registra a quién avisar. Cada correo o celular que agregues se usa para notificar los documentos que le emitas a ese cliente. El celular es un móvil chileno (569XXXXXXXX):

    {
    "email": "contabilidad@tuempresa.cl",
    "etiqueta": "Contabilidad"
    }
    {
    "telefono": "56912345678",
    "etiqueta": "Contabilidad"
    }
    Ventana de terminal
    redcumbre api agregarEmailDteCliente --param clienteId=<id> --cuerpo @email.json
    redcumbre api agregarTelefonoDteCliente --param clienteId=<id> --cuerpo @telefono.json

    Resultado esperado: 201 con el cliente y el contacto agregado en emailsDte o telefonosDte. Un teléfono que no es móvil, 400; uno ya registrado, 409. Para sacar un contacto: quitarEmailDteCliente (--param clienteId=<id> --param emailDteId=<id del contacto>) y quitarTelefonoDteCliente (telefonoDteId), que responden 200. Los contactos que mandes al emitir (receptor.email, emailsAdicionales, receptor.telefono) también quedan en esta agenda; ver Documentos tributarios electrónicos.

  5. Bloquea a un cliente. Un cliente bloqueado no recibe documentos: no se le pueden emitir boletas de honorarios ni documentos tributarios de venta. El motivo es obligatorio (mínimo 10 caracteres, máximo 500) y el bloqueo es reversible:

    {
    "motivoBloqueo": "Deuda pendiente mayor a 90 días"
    }
    Ventana de terminal
    redcumbre api bloquearCliente --param id=<id> --cuerpo @bloqueo.json
    redcumbre api desbloquearCliente --param id=<id>

    Resultado esperado: 201 con bloqueado: true, el motivoBloqueo y la fecha. Bloquear a un cliente ya bloqueado, o desbloquear a uno que no lo está, responde 400. Los clientes de ejemplo precargados del modo de prueba no se bloquean.

  6. Proveedores. Son las mismas operaciones sobre otra agenda, con tres diferencias: crearProveedor y actualizarProveedor sólo manejan rut y notasInternas (no hay nombre de fantasía), a un proveedor bloqueado no se le pueden emitir boletas de terceros ni documentos tributarios, y los proveedores se pueden listar y buscar:

    {
    "rut": "11111111-1",
    "notasInternas": "Proveedor de prueba, pago a 30 días"
    }
    Ventana de terminal
    redcumbre api crearProveedor --cuerpo @proveedor.json
    redcumbre api listarProveedores --param search=prueba --param limit=20
    redcumbre api obtenerProveedorPorRut --param rut=11111111-1

    Resultado esperado: 201 con el proveedor; el listado trae data, total, limit y offset. Filtros del listado: search (RUT o razón social), bloqueado, origenCreacion, sortBy (createdAt, razonSocial, rut) y sortOrder; limit hasta 300. obtenerProveedorPorRut responde 200 con el proveedor, o 200 con null si no existe (no es un error). Los demás: obtenerProveedor, actualizarProveedor, bloquearProveedor (motivoBloqueo), desbloquearProveedor, agregarEmailDteProveedor, agregarTelefonoDteProveedor, quitarEmailDteProveedor, quitarTelefonoDteProveedor, con las mismas reglas que en clientes (en proveedores el parámetro de ruta es proveedorId).

    {
    "motivoBloqueo": "Incumplimiento de contrato"
    }
  • Quedó dado de alta: 201 con el id, origenCreacion: "MANUAL" y bloqueado: false. Léelo de vuelta con obtenerCliente u obtenerProveedor y comprueba que la razonSocial es la del registro.
  • El bloqueo rige: bloqueado: true en la lectura. Una emisión a ese cliente o proveedor se rechaza hasta que lo desbloquees.
  • Un contacto quedó registrado: aparece en emailsDte o telefonosDte con su id y su etiqueta.
  • Estás en el modo de prueba: sandbox: true. Nada de lo que crees ahí aparece en la llave de producción, y al revés.
Si vesSignificaQué haces
404 al crearEl RUT no está en el registro de contribuyentesConsúltalo con consultarRutEnSii y vuelve a crear. En el modo de prueba, usa uno de los diez RUT de prueba
409 al crearYa es cliente (o proveedor) de tu empresaEs lo esperado con los RUT precargados del modo de prueba. Usa otro RUT del catálogo
404 al leer, editar o bloquearEl id no existe en tu empresa, o es del otro modoVerifica el id que devolvió el alta
400 al bloquear o desbloquearYa estaba en ese estadoLee primero el bloqueado actual
400 al agregar un teléfonoNo es un móvil chilenoUsa el formato 569XXXXXXXX
409 al agregar un contactoYa estaba registradoNada que hacer: ya está en la agenda
400 con MODO_PRUEBA_TOPE_DIARIOSuperaste el tope diario del modo de prueba para clientes o proveedores (200 por día)Espera a las 00:00 de Chile. redcumbre estado muestra lo que queda
Una edición o un bloqueo rechazado en el modo de pruebaEl cliente o proveedor es un dato de ejemplo precargadoCrea el tuyo con otro RUT de prueba
  • Las operaciones de estas agendas escriben los datos de producción de tu empresa. Un cliente bloqueado en producción deja de recibir documentos de verdad. Cada comando de redcumbre api que escribe en producción lleva --produccion --confirmar <slug>.
  • El registro es el del SII. Un RUT que el SII no conoce no se puede dar de alta. Para uno nuevo, hay que consultarlo antes con consultarRutEnSii, que en producción llama al SII; lo que cuesta depende de tu plan: redcumbre tarifas consultarRutEnSii --produccion.
  • Tus agendas de prueba no pasan a producción. Los clientes y proveedores del modo de prueba no existen para la llave de producción: tienes que darlos de alta de nuevo, con sus contactos.
  • Los precargados desaparecen. Los RUT de prueba (88888888-8, 22222222-2…) no existen como contribuyentes en el SII: no los uses en producción.
  • Ver Modo de prueba y producción para el cambio de llave.