Ir al contenido

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.

  • 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éDetalle
Llave de la empresaRol FULL-API. En el modo de prueba, la de keys/redcumbre-prueba.json. No necesitas un emisor.
aguaSSR habilitadoLa empresa tiene que tener aguaSSR en su plan. Sin él, el servidor responde 403.
Una forma de llamarUn 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 200 trae 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.

Todo campo que no esté en esta lista hace que la ficha se rechace nombrándolo: no se descarta en silencio.

CampoObligatorioDetalle
codigoSíCódigo del servicio, hasta 40 caracteres.
cliente.rutSíRUT con su dígito verificador. Un RUT genérico no se acepta.
cliente.nombreSegún el casoHasta 200 caracteres. Es obligatorio si el RUT aún no es cliente y no tiene nombre registrado.
cliente.tipoNopersona o institucion.
cliente.telefonoNoNúmero chileno válido.
cliente.correoNoCorreo del cliente.
membresia.numeroNoNúmero de socio, entero desde 1. Sin número, la ficha no toca la membresía.
membresia.socioDesdeNoFecha AAAA-MM-DD. Sin ella, la de hoy.
servicio.estadoNoactivo, 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.direccionSíHasta 300 caracteres.
servicio.localidadNoHasta 120 caracteres.
servicio.comunaNoCódigo de la comuna según el catálogo de comunas de la plataforma.
servicio.referenciaNoTexto libre para ubicar el servicio.
servicio.titularDesdeNoFecha AAAA-MM-DD desde la que el cliente es el titular.
servicio.diametroArranqueNoDiámetro del arranque, del catálogo de diámetros.
servicio.sectorNoHasta 80 caracteres. Es la ruta de lectura del servicio.
servicio.diaLecturaNoDí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.ordenNoPosición dentro de la ruta, entero desde 1.
medidor.serieNoPuede venir vacía.
medidor.digitosNo4, 5 o 6.
medidor.diametroNoDel catálogo de diámetros.
medidor.marca, medidor.modelo, medidor.anioNoDatos del medidor.
medidor.instaladoDesdeNoFecha 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 diaLectura define el ciclo (del 29 al 31 queda en el ciclo del 28, conservando el día original) y el sector la 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.

  1. 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: 200 con 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 valorVigente y de sinDiaDeLectura dependen de lo que tenga sembrado la empresa. Lo que importa es la forma: resultado es aplicada, rechazada o en_conflicto.

  2. Lee el resultado de cada ficha. Recorre resultados y actúa según resultado:

    • aplicada: no hay nada más que hacer. Si trae sinDiaDeLectura: true, el servicio quedó «Sin ciclo» porque la ficha no traía diaLectura.
    • rechazada: nada de esa ficha se guardó. Corrige lo que dice motivos y reenvía sólo esa ficha.
    • en_conflicto: la ficha se aplicó salvo los datos de conflictos. No los reenvíes: esperan la decisión de la cooperativa en «Cambios del integrador».
  3. 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 orden y, a igual orden, por código.

  4. 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ódigoQué 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_conflicto y la última vuelve rechazada con AGUA_SERVICIO_ARCHIVADO. Los servicios de ensayo se siembran solos y no cuentan en el tope diario.

  • El lote se procesó: 200 con un envioId y tantos resultados como fichas enviaste.
  • Una ficha quedó guardada: su resultado es aplicada o en_conflicto. Reenviarla no cambia nada y vuelve aplicada.
  • 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.

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 vesSignificaQué haces
AGUA_FICHA_FORMA_INVALIDALa ficha no es un objetoEnvía cada ficha como un objeto
AGUA_FICHA_CAMPO_DESCONOCIDOTrae un campo que no está en la fichaQuita o corrige el campo que nombra el mensaje
AGUA_FICHA_CAMPO_INVALIDOUn campo no tiene un valor válidoCorrige el campo que nombra el mensaje
AGUA_FICHA_CODIGO_REQUERIDOFalta el código del servicioAgrega codigo
AGUA_FICHA_CODIGO_REPETIDO_EN_LOTEEl código viene repetido en el loteSólo se procesa la primera; reenvía la otra en otro lote si era otro servicio
AGUA_FICHA_DIRECCION_REQUERIDAFalta la dirección del servicioAgrega servicio.direccion
AGUA_FICHA_RUT_INVALIDOEl RUT del cliente no es válidoRevisa el RUT y su dígito verificador
AGUA_FICHA_RUT_GENERICOEl RUT es genérico y no identifica a una personaUsa el RUT real del cliente
AGUA_FICHA_TELEFONO_INVALIDOEl teléfono no es un número chileno válidoCorrígelo o quítalo
AGUA_FICHA_NOMBRE_REQUERIDOEl RUT no es cliente y no tiene un nombre registradoAgrega cliente.nombre
AGUA_FICHA_SOCIO_NUMERO_DISTINTOEl cliente ya es socio con otro númeroUsa su número vigente o quita membresia.numero
AGUA_FICHA_SOCIO_NUMERO_TOMADOEse número de socio lo tiene otro clienteUsa otro número
AGUA_FICHA_SOCIO_RETIRADOEl cliente se retiró como socio y la ficha trae otro númeroPide a la cooperativa que lo reincorpore en la web
AGUA_FICHA_SOCIO_DOS_NUMEROS_EN_LOTEEl mismo cliente trae dos números de socio en el loteDeja un solo número por cliente
AGUA_FICHA_TITULAR_DESDE_ANTERIOREl titular nuevo empieza antes que el actualCorrige servicio.titularDesde
AGUA_SERVICIO_ARCHIVADOEl servicio está archivadoPide a la cooperativa que lo desarchive en la web
AGUA_FICHA_MEDIDOR_DE_BAJAEl medidor está de baja y no se puede instalarUsa otra serie
AGUA_FICHA_MEDIDOR_EN_OTRO_SERVICIOEl medidor está instalado en otro servicioRevisa la serie o el código del otro servicio que dice el mensaje
400 por la formaEl lote está vacío, trae más de 250 fichas o fichas no es una listaEnvía de 1 a 250 fichas
400 con MODO_PRUEBA_TOPE_DIARIOEl 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
403La empresa no tiene aguaSSR, o la llave no correspondeVerifica el plan de la empresa y la llave
  • Lo que cargas en producción es el padrón real de la cooperativa. Cada comando de redcumbre api que 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.