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.
Qué resuelve
Sección titulada «Qué resuelve»- 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é necesitas antes
Sección titulada «Qué necesitas antes»| Qué | Detalle |
|---|---|
| Llave de la empresa | Rol FULL-API. En el modo de prueba, la de keys/redcumbre-prueba.json. No necesitas un emisor. |
| El RUT en el registro de contribuyentes | crearCliente 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 prueba | El 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
idde un cliente sale de la respuesta decrearCliente. 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: falseenemitirDte). SuorigenCreacionte dice de dónde vino:MANUALes 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.
-
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.jsonResultado esperado:
201con el cliente completo ysandbox: true. Guarda elid: es lo único con lo que después lo consultas.nombreFantasiaynotasInternasson 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 responde409(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} -
Lee el cliente.
Ventana de terminal redcumbre api obtenerCliente --param id=<id>Resultado esperado:
200con los mismos campos.404si el id no existe en tu empresa (o es de producción y usas una llave de prueba). -
Edita lo que es tuyo.
actualizarClientecambia 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.jsonResultado esperado:
200con 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. -
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.jsonredcumbre api agregarTelefonoDteCliente --param clienteId=<id> --cuerpo @telefono.jsonResultado esperado:
201con el cliente y el contacto agregado enemailsDteotelefonosDte. 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>) yquitarTelefonoDteCliente(telefonoDteId), que responden200. Los contactos que mandes al emitir (receptor.email,emailsAdicionales,receptor.telefono) también quedan en esta agenda; ver Documentos tributarios electrónicos. -
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.jsonredcumbre api desbloquearCliente --param id=<id>Resultado esperado:
201conbloqueado: true, elmotivoBloqueoy la fecha. Bloquear a un cliente ya bloqueado, o desbloquear a uno que no lo está, responde400. Los clientes de ejemplo precargados del modo de prueba no se bloquean. -
Proveedores. Son las mismas operaciones sobre otra agenda, con tres diferencias:
crearProveedoryactualizarProveedorsólo manejanrutynotasInternas(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.jsonredcumbre api listarProveedores --param search=prueba --param limit=20redcumbre api obtenerProveedorPorRut --param rut=11111111-1Resultado esperado:
201con el proveedor; el listado traedata,total,limityoffset. Filtros del listado:search(RUT o razón social),bloqueado,origenCreacion,sortBy(createdAt,razonSocial,rut) ysortOrder;limithasta 300.obtenerProveedorPorRutresponde200con el proveedor, o200connullsi 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 esproveedorId).{"motivoBloqueo": "Incumplimiento de contrato"}
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- Quedó dado de alta:
201con elid,origenCreacion: "MANUAL"ybloqueado: false. Léelo de vuelta conobtenerClienteuobtenerProveedory comprueba que larazonSociales la del registro. - El bloqueo rige:
bloqueado: trueen la lectura. Una emisión a ese cliente o proveedor se rechaza hasta que lo desbloquees. - Un contacto quedó registrado: aparece en
emailsDteotelefonosDtecon suidy 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.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
404 al crear | El RUT no está en el registro de contribuyentes | Consúltalo con consultarRutEnSii y vuelve a crear. En el modo de prueba, usa uno de los diez RUT de prueba |
409 al crear | Ya es cliente (o proveedor) de tu empresa | Es lo esperado con los RUT precargados del modo de prueba. Usa otro RUT del catálogo |
404 al leer, editar o bloquear | El id no existe en tu empresa, o es del otro modo | Verifica el id que devolvió el alta |
400 al bloquear o desbloquear | Ya estaba en ese estado | Lee primero el bloqueado actual |
400 al agregar un teléfono | No es un móvil chileno | Usa el formato 569XXXXXXXX |
409 al agregar un contacto | Ya estaba registrado | Nada que hacer: ya está en la agenda |
400 con MODO_PRUEBA_TOPE_DIARIO | Superaste 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 prueba | El cliente o proveedor es un dato de ejemplo precargado | Crea el tuyo con otro RUT de prueba |
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»- 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 apique 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.