aguaSSR
Esta ficha explica cómo cargar y mantener al día el padrón de una cooperativa de agua potable rural: sus clientes, los socios, los servicios (una conexión con su dirección, su estado y su ruta de lectura) y el medidor de cada servicio. Se hace enviando fichas, de a lotes, y cada ficha vuelve con su propio resultado.
Una ficha describe un servicio con todo lo que lo rodea: quién es el cliente, si es socio, cómo es el servicio y qué medidor tiene. Enviar la misma ficha dos veces no duplica nada: la segunda vez no cambia lo que ya estaba y vuelve aplicada.
Qué resuelve
Sección titulada «Qué resuelve»- Cargar el padrón completo de la cooperativa la primera vez, en lotes.
- Enviar después los servicios nuevos y los cambios del padrón.
- Saber, ficha por ficha, si quedó aplicada, si se rechazó (y por qué) o si se aplicó con datos que la oficina de la cooperativa cambió a mano y que esperan su decisión.
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. |
| aguaSSR habilitado | La empresa tiene que tener aguaSSR en su plan. Sin él, el servidor responde 403. |
| Una forma de llamar | Un POST a /{slug}/agua/ingreso/v1/fichas, con la llave en el encabezado de autorización. El contrato completo lo muestra redcumbre api describir cargarFichasAgua. |
Lo que debes saber antes de empezar:
- Un lote lleva de 1 a 250 fichas. Cinco mil servicios caben en veinte lotes. Un lote vacío o de más de 250 fichas se rechaza entero con
400. - La respuesta es inmediata. No hay que esperar un proceso: el mismo
200trae un resultado por ficha, en el orden en que las enviaste. - Una ficha que falla no deshace las anteriores. Cada ficha se aplica por separado.
- El código del servicio manda. Es lo que identifica a una ficha: si ya existe un servicio con ese código, la ficha lo actualiza; si no, lo crea. Dos fichas del mismo lote con el mismo código: sólo se procesa la primera.
- Lo que la oficina cambió a mano se respeta. Si la oficina cambió en la web la dirección, la referencia, el estado, la ruta de lectura o el medidor de un servicio, y tu ficha trae otro valor, no lo pisa: el valor queda en «Cambios del integrador» para que una persona elija cuál usar.
- El cliente no se modifica. Si el RUT ya es cliente de la cooperativa, la ficha se suma a ese cliente y su nombre, tipo, teléfono y correo de la ficha se ignoran.
La ficha, campo por campo
Sección titulada «La ficha, campo por campo»Todo campo que no esté en esta lista hace que la ficha se rechace nombrándolo: no se descarta en silencio.
| Campo | Obligatorio | Detalle |
|---|---|---|
codigo | Sí | Código del servicio, hasta 40 caracteres. |
cliente.rut | Sí | RUT con su dígito verificador. Un RUT genérico no se acepta. |
cliente.nombre | Según el caso | Hasta 200 caracteres. Es obligatorio si el RUT aún no es cliente y no tiene nombre registrado. |
cliente.tipo | No | persona o institucion. |
cliente.telefono | No | Número chileno válido. |
cliente.correo | No | Correo del cliente. |
membresia.numero | No | Número de socio, entero desde 1. Sin número, la ficha no toca la membresía. |
membresia.socioDesde | No | Fecha AAAA-MM-DD. Sin ella, la de hoy. |
servicio.estado | No | activo, suspendido, sin_conexion o baja. Sin estado, el servicio queda sin estado: no se le pone uno por defecto, no se lee y se muestra «—». |
servicio.direccion | Sí | Hasta 300 caracteres. |
servicio.localidad | No | Hasta 120 caracteres. |
servicio.comuna | No | Código de la comuna según el catálogo de comunas de la plataforma. |
servicio.referencia | No | Texto libre para ubicar el servicio. |
servicio.titularDesde | No | Fecha AAAA-MM-DD desde la que el cliente es el titular. |
servicio.diametroArranque | No | Diámetro del arranque, del catálogo de diámetros. |
servicio.sector | No | Hasta 80 caracteres. Es la ruta de lectura del servicio. |
servicio.diaLectura | No | Día del mes de la lectura, de 1 a 31. Sin él, el servicio queda «Sin ciclo» y la respuesta lo avisa con sinDiaDeLectura. |
servicio.orden | No | Posición dentro de la ruta, entero desde 1. |
medidor.serie | No | Puede venir vacía. |
medidor.digitos | No | 4, 5 o 6. |
medidor.diametro | No | Del catálogo de diámetros. |
medidor.marca, medidor.modelo, medidor.anio | No | Datos del medidor. |
medidor.instaladoDesde | No | Fecha AAAA-MM-DD. Sin ella, la de hoy. |
Reglas que conviene conocer:
- Socios. Una ficha crea la membresía de un cliente que aún no es socio, pero no cambia la de uno que ya lo es: si el número es distinto del vigente, se rechaza. Un número de socio que ya tuvo otro cliente (aunque se haya retirado) cuenta como usado.
- Titular. Si la ficha trae un titular distinto del actual, la titularidad anterior se cierra y se abre la nueva, siempre que no empiece antes que la actual.
- Ruta. El
diaLecturadefine el ciclo (del 29 al 31 queda en el ciclo del 28, conservando el día original) y elsectorla ruta dentro de él. Si la ruta no existe, se crea. - Medidor. Se identifica por servicio y serie. Un medidor que llega por la integración queda instalado sin índice de montaje: la oficina lo ve como «Sin índice de montaje (llegó por la integración)».
- Servicio archivado. Una ficha con el código de un servicio archivado se rechaza: hay que desarchivarlo en la web.
- Estado
baja. Es un estado como cualquier otro, no un archivado.
Los ejemplos usan el modo de prueba. Los datos que cargues ahí se suprimen solos a los 30 días y redcumbre restaurar --confirmar <slug> los borra en el acto.
-
Envía un lote de prueba. Tres fichas: un servicio nuevo con medidor, uno con el RUT mal escrito y el servicio de ensayo
ENSAYO-DIRECCION, que trae la dirección cambiada en la web:{"fichas": [{"codigo": "S-0001","cliente": { "rut": "12345678-5", "nombre": "Cliente de Prueba Uno", "tipo": "persona" },"membresia": { "numero": 101, "socioDesde": "2024-03-01" },"servicio": { "estado": "activo", "direccion": "Camino Vecinal 120", "localidad": "Sector Central", "sector": "Central", "diaLectura": 10, "orden": 1 },"medidor": { "serie": "MED-0001", "digitos": 5, "diametro": "1/2", "marca": "Marca Ejemplo", "modelo": "Modelo Ejemplo", "instaladoDesde": "2024-03-01" }},{"codigo": "S-0002","cliente": { "rut": "12345678-9", "nombre": "Cliente de Prueba Dos" },"servicio": { "estado": "activo", "direccion": "Camino Vecinal 340" }},{"codigo": "ENSAYO-DIRECCION","cliente": { "rut": "88888888-8" },"servicio": { "estado": "activo", "direccion": "Dirección que envía la integración" }}]}Resultado esperado:
200con un resultado por ficha, en el mismo orden.{"envioId": "cm5abc123def456","resultados": [{ "indice": 0, "codigo": "S-0001", "resultado": "aplicada", "motivos": [], "conflictos": [], "sinDiaDeLectura": false },{"indice": 1,"codigo": "S-0002","resultado": "rechazada","motivos": [{ "codigo": "AGUA_FICHA_RUT_INVALIDO", "mensaje": "El RUT del cliente no es válido." }],"conflictos": [],"sinDiaDeLectura": false},{"indice": 2,"codigo": "ENSAYO-DIRECCION","resultado": "en_conflicto","motivos": [],"conflictos": [{ "dato": "DIRECCION", "valorVigente": { "direccion": "Dirección corregida en la web" }, "valorEnviado": { "direccion": "Dirección que envía la integración" } }],"sinDiaDeLectura": true}],"sandbox": true,"cobro": { "modo": "prueba", "mensaje": "En modo de prueba no se cobra." }}Los valores exactos de
valorVigentey desinDiaDeLecturadependen de lo que tenga sembrado la empresa. Lo que importa es la forma:resultadoesaplicada,rechazadaoen_conflicto. -
Lee el resultado de cada ficha. Recorre
resultadosy actúa segúnresultado:aplicada: no hay nada más que hacer. Si traesinDiaDeLectura: true, el servicio quedó «Sin ciclo» porque la ficha no traíadiaLectura.rechazada: nada de esa ficha se guardó. Corrige lo que dicemotivosy reenvía sólo esa ficha.en_conflicto: la ficha se aplicó salvo los datos deconflictos. No los reenvíes: esperan la decisión de la cooperativa en «Cambios del integrador».
-
Carga el padrón completo. Divide los servicios en lotes de hasta 250 fichas y envíalos uno tras otro. Una carga inicial ordenada deja los servicios de cada ruta ordenados por
ordeny, a igual orden, por código. -
Prueba los casos de conflicto. En el modo de prueba, la empresa trae cuatro servicios de ensayo para provocar cada caso sin tocar datos reales:
Código Qué tiene ENSAYO-DIRECCIONLa dirección cambiada en la web. ENSAYO-RUTAEn el ciclo del día 10 y en una ruta, movido en la web. ENSAYO-MEDIDORCon medidor y su marca corregida en la web. ENSAYO-ARCHIVADOArchivado. Envía una ficha con cada código y otro valor en el dato correspondiente: las tres primeras vuelven
en_conflictoy la última vuelverechazadaconAGUA_SERVICIO_ARCHIVADO. Los servicios de ensayo se siembran solos y no cuentan en el tope diario.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- El lote se procesó:
200con unenvioIdy tantosresultadoscomo fichas enviaste. - Una ficha quedó guardada: su
resultadoesaplicadaoen_conflicto. Reenviarla no cambia nada y vuelveaplicada. - Todo lo enviado está a la vista de la cooperativa: el envío aparece en Configuración › Integración de la web, con su modo (prueba o producción) y sus contadores. Los datos en conflicto aparecen en el cliente, pestaña «Cambios del integrador».
- Estás en el modo de prueba: los datos no existen para la llave de producción, y al revés.
Qué puede fallar
Sección titulada «Qué puede fallar»Cada ficha rechazada trae motivos con un codigo y un mensaje. El mensaje nombra lo que falló sin repetir el dato personal que viniste a cargar.
| Si ves | Significa | Qué haces |
|---|---|---|
AGUA_FICHA_FORMA_INVALIDA | La ficha no es un objeto | Envía cada ficha como un objeto |
AGUA_FICHA_CAMPO_DESCONOCIDO | Trae un campo que no está en la ficha | Quita o corrige el campo que nombra el mensaje |
AGUA_FICHA_CAMPO_INVALIDO | Un campo no tiene un valor válido | Corrige el campo que nombra el mensaje |
AGUA_FICHA_CODIGO_REQUERIDO | Falta el código del servicio | Agrega codigo |
AGUA_FICHA_CODIGO_REPETIDO_EN_LOTE | El código viene repetido en el lote | Sólo se procesa la primera; reenvía la otra en otro lote si era otro servicio |
AGUA_FICHA_DIRECCION_REQUERIDA | Falta la dirección del servicio | Agrega servicio.direccion |
AGUA_FICHA_RUT_INVALIDO | El RUT del cliente no es válido | Revisa el RUT y su dígito verificador |
AGUA_FICHA_RUT_GENERICO | El RUT es genérico y no identifica a una persona | Usa el RUT real del cliente |
AGUA_FICHA_TELEFONO_INVALIDO | El teléfono no es un número chileno válido | Corrígelo o quítalo |
AGUA_FICHA_NOMBRE_REQUERIDO | El RUT no es cliente y no tiene un nombre registrado | Agrega cliente.nombre |
AGUA_FICHA_SOCIO_NUMERO_DISTINTO | El cliente ya es socio con otro número | Usa su número vigente o quita membresia.numero |
AGUA_FICHA_SOCIO_NUMERO_TOMADO | Ese número de socio lo tiene otro cliente | Usa otro número |
AGUA_FICHA_SOCIO_RETIRADO | El cliente se retiró como socio y la ficha trae otro número | Pide a la cooperativa que lo reincorpore en la web |
AGUA_FICHA_SOCIO_DOS_NUMEROS_EN_LOTE | El mismo cliente trae dos números de socio en el lote | Deja un solo número por cliente |
AGUA_FICHA_TITULAR_DESDE_ANTERIOR | El titular nuevo empieza antes que el actual | Corrige servicio.titularDesde |
AGUA_SERVICIO_ARCHIVADO | El servicio está archivado | Pide a la cooperativa que lo desarchive en la web |
AGUA_FICHA_MEDIDOR_DE_BAJA | El medidor está de baja y no se puede instalar | Usa otra serie |
AGUA_FICHA_MEDIDOR_EN_OTRO_SERVICIO | El medidor está instalado en otro servicio | Revisa la serie o el código del otro servicio que dice el mensaje |
400 por la forma | El lote está vacío, trae más de 250 fichas o fichas no es una lista | Envía de 1 a 250 fichas |
400 con MODO_PRUEBA_TOPE_DIARIO | El lote no cabe en el tope diario del modo de prueba (5.000 fichas por día, contando también las rechazadas) | Se rechaza el lote entero. Espera a las 00:00 de Chile y reenvíalo. redcumbre estado muestra lo que queda |
403 | La empresa no tiene aguaSSR, o la llave no corresponde | Verifica el plan de la empresa y la llave |
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»- Lo que cargas en producción es el padrón real de la cooperativa. Cada comando de
redcumbre apique escribe en producción lleva--produccion --confirmar <slug>. El paso es el común a todos los servicios: ver Modo de prueba y producción. - Cada servicio nuevo suma al cobro del plan. En producción, un servicio que nace se cuenta como servicio vigente; en prueba no se cobra nada.
- El padrón de prueba no pasa a producción. Tienes que cargarlo de nuevo con la llave de producción. Los servicios de ensayo existen sólo en el modo de prueba.
- No hay tope diario en producción. El de 5.000 fichas por día es del modo de prueba.
- Para el paso a paso con ejemplos y lo que ve la cooperativa en su web, ver la guía aguaSSR.