terminal Referencia técnica v2

Captura obligatoria en arribo y finalización

Cómo una compañía exige fotografías o datos al prestador antes de que pueda marcar el arribo o la finalización de un servicio. Define las reglas por caso, dentro del propio caso.

updateActualizado: 30 de septiembre de 2026groupDirigido a: Equipos de sistemas e integradoresdeployed_codeAplica a: AsistManager · aplicación de prestadores

Descripción #

La captura obligatoria permite que la compañía condicione dos momentos del servicio: el arribo y la finalización. Antes de que el prestador pueda marcarlos, la aplicación le exige las fotografías y los datos que la compañía definió para ese caso.

Las reglas viajan dentro del caso, en el campo requirements de task. Eso significa que se definen por servicio y no por flota ni por configuración global: dos casos enviados a la misma flota pueden exigir cosas distintas.

Las fotografías y los datos se transmiten a medida que el prestador los completa, no al final. Si interrumpe el trabajo y vuelve más tarde, lo ya cargado se conserva.

info
Las reglas las aplica la aplicación del prestador
El cumplimiento lo verifica la aplicación en el dispositivo, que es donde ocurre la captura. AsistManager transporta, almacena y preserva estas reglas sin interpretarlas, lo que permite incorporar exigencias nuevas sin modificar el servidor. Consecuencia para quien integra: el cambio de estado de un caso no constituye por sí mismo la prueba de la evidencia. La evidencia es lo que llega al callback.

Cuándo se usa #

Cuando la evidencia del trabajo forma parte del servicio y no de la auditoría posterior: estado inicial antes de intervenir, trabajo terminado, conformidad del cliente, lectura de un medidor.

Los servicios de hogar son el caso característico, porque el prestador entra a un domicilio y la compañía necesita constancia de en qué condiciones lo encontró y en cuáles lo dejó.

info
Requiere el formato JSON
El campo requirements solo puede enviarse en el formato JSON del alta de caso o de la consulta. El formato heredado separado por tabulaciones reconstruye el caso a partir de una lista fija de campos y descarta cualquier otro, de modo que estas reglas se perderían sin aviso.

Dónde vive requirements #

data_object JSON
json 
{
  "identifier": "20260812101952844",
  "alias": "prestador",
  "worker": "",
  "delay": "0",
  "task": {
    "TipoServicioInicial": "Hogar/Plomeria",
    "Desperfecto": "Perdida de agua en cocina",
    "Vehiculo": "",
    "Patente": "",
    "Color": "",
    …  el resto de los campos de task,

    "requirements": {
      "version": 1,
      "on_arrive": {
        "mode": "block",
        "photos": [
          {"id": "portico", "label": "Foto del pórtico / frente", "min": 1,
           "hint": "Confirmá que estás en el domicilio"},
          {"id": "estado_inicial", "label": "Fotos del estado inicial (antes de empezar)", "min": 2,
           "hint": "Cómo estaba antes de trabajar"}
        ],
        "fields": []
      },
      "on_finish": {
        "mode": "block",
        "reminder": "Sumá las fotos del trabajo terminado antes de finalizar",
        "photos": [
          {"id": "trabajo_terminado", "label": "Fotos del trabajo terminado", "min": 2,
           "hint": "Mostrá lo realizado"}
        ],
        "fields": []
      }
    }
  }
}

Es un servicio de hogar: los campos de vehículo van vacíos y TipoServicioInicial lleva el prefijo Hogar/. El objeto task está definido en el documento de consultas; acá se abrevia para que se vea dónde encaja requirements.

Campos de requirements #

Campo Tipo Obligatorio Valores posibles Descripción
version entero Obligatorio 1 Versión del esquema. Se incluye para permitir cambios futuros sin ambigüedad.
on_arrive objeto Opcional — Reglas que condicionan el arribo. Puede omitirse si solo se exige algo al finalizar.
on_finish objeto Opcional — Reglas que condicionan la finalización. Puede omitirse si solo se exige algo al arribar.
mode string Obligatorio block · warn · remind Determina la exigencia. Ver la tabla siguiente.
reminder string Opcional — Texto que se muestra sobre el panel de requisitos.
photos array Opcional — Categorías de fotografía exigidas.
fields array Opcional — Datos a completar. Puede enviarse vacío.

Los tres modos #

ModoQué haceCuándo conviene
blockImpide el arribo o la finalización hasta que se cumpla todo lo exigido. No puede omitirse.Cuando la evidencia es condición del servicio.
warnPermite continuar sin completar, advirtiendo al prestador. La omisión queda registrada como un dato más del caso.Cuando la evidencia se prefiere pero no puede frenar la operación.
remindSolo informa. No condiciona nada.Cuando se quiere instalar una práctica antes de exigirla.

Combinar los modos entre arribo y finalización #

Los dos momentos son independientes: cada uno lleva su propio modo, y uno puede omitirse por completo. Eso permite graduar la exigencia según lo que esté en juego en cada etapa del servicio.

Combinaciones habituales #

ArriboFinalizaciónQué consigueEjemplo de uso
blockblockEvidencia obligatoria en las dos etapas. Es la configuración más estricta.Servicio en domicilio donde se documenta el estado antes y después.
blockwarnSe exige constatar la llegada; al cerrar se pide evidencia pero no se frena.Cuando lo crítico es probar la presencia en el lugar.
warnblockSe pide evidencia al llegar sin frenar, y se exige al cerrar.Cuando el trabajo terminado es lo que se factura.
remindblockAl llegar solo se recuerda; al cerrar se exige.Etapa de transición hacia una exigencia plena.
(omitido)blockNo se condiciona el arribo. Solo se exige al finalizar.Servicios breves sin etapa intermedia relevante.
block(omitido)Se condiciona el arribo y la finalización queda libre.Cuando la constancia de llegada es el requisito contractual.
remindremindNo condiciona nada. Solo informa qué se espera.Instalar la práctica antes de exigirla.
info
Qué informa cada modo al cerrar el servicio
Con block, la existencia de la evidencia está garantizada por el flujo. Con warn, si el prestador decide continuar sin completar, la omisión queda registrada como un dato más del caso, de modo que la compañía puede distinguir lo que falta por decisión de lo que falta por error. Con remind no se registra nada.

Campos de cada categoría de fotografía #

Campo Tipo Obligatorio Valores posibles Descripción
id string Obligatorio — Identificador de la categoría. Es la clave con la que después se recuperan las fotografías, de modo que conviene que sea estable y descriptivo.
label string Obligatorio — Título que ve el prestador.
min entero Opcional 1 o más Cantidad mínima exigida. Si se omite, se considera 1.
hint string Opcional — Aclaración secundaria bajo el título.

Ejemplo con datos a completar #

data_object JSON
json 
"on_finish": {
  "mode": "block",
  "photos": [
    {"id": "trabajo_terminado", "label": "Trabajo terminado", "min": 2}
  ],
  "fields": [
    {"id": "km", "label": "Kilometraje", "type": "number", "min": 0, "max": 999999},
    {"id": "estado", "label": "Estado general", "type": "select",
     "options": ["Resuelto", "Parcial", "No resuelto"]},
    {"id": "obs", "label": "Observación", "type": "text", "maxlength": 300, "required": false},
    {"id": "conforme", "label": "Conformidad", "type": "check",
     "checklabel": "El cliente prestó conformidad"}
  ]
}

Campos de cada dato a completar #

Campo Tipo Obligatorio Valores posibles Descripción
id string Obligatorio — Identificador del dato, usado para recuperarlo.
label string Obligatorio — Etiqueta visible.
type string Obligatorio text · number · select · check Tipo de dato. Determina el control que se presenta y la validación.
required booleano Opcional — Los datos son obligatorios por omisión. Para que uno sea opcional debe enviarse este campo en falso de forma explícita.
min · max entero Opcional — Límites del valor. Solo para el tipo number.
minlength · maxlength entero Opcional — Límites de longitud. Solo para el tipo text.
options array Condicional Obligatorio para el tipo select — Valores admitidos. Un valor fuera de la lista se rechaza.
checklabel string Opcional — Texto junto a la casilla. Solo para el tipo check.

Cómo llegan las capturas a la compañía #

Cada fotografía y cada dato se envían al callback de la compañía a medida que el prestador los completa, sin esperar al cierre del servicio. El nombre que la regla le puso a la categoría viaja en el campo index del adjunto: es ahí donde la compañía lee a qué regla corresponde cada captura. El resto del cuerpo del mensaje se describe en Adjuntos binarios.

Valores del campo index #

Valor de indexQué esEjemplo
arrive-<id>-<n>Fotografía de arribo. El identificador es el de la categoría, tal como se la nombró en la regla; el número es correlativo dentro de ella y arranca en 0.arrive-portico-0 · arrive-portico-1
finish-<id>-<n>Fotografía de finalización.finish-trabajo_terminado-0 · finish-trabajo_terminado-1
arrive-field-<id> · finish-field-<id>Dato completado. Sin número correlativo.finish-field-estado
warning
Dos precauciones al leer los adjuntos
La numeración correlativa puede tener huecos: si el prestador elimina una fotografía, el número no se reutiliza, de modo que puede existir el 1 sin que exista el 0. Y una misma clave puede repetirse cuando un dato se corrige: en ese caso corresponde tomar el registro más reciente por fecha y no asumir que la clave es única.

Consideraciones de campo #

Las fotografías se toman a 640 por 480 píxeles con compresión intermedia, lo que da un archivo típico de 22 kilobytes y de 77 en el peor caso medido. Un arribo con tres fotografías y una finalización con dos representan unos 110 kilobytes por servicio.

El envío se realiza en el momento de la captura y sin confirmación de recepción. En condiciones de señal deficiente, el prestador puede completar los requisitos y avanzar sin que las capturas hayan llegado. Por eso una compañía no debe deducir la existencia de la evidencia a partir del cambio de estado: debe verificarla contra las capturas efectivamente recibidas en su callback.

Código Qué se ve Causa Cómo se resuelve
Sin efecto El caso llega sin las reglas Se envió en el formato heredado separado por tabulaciones, que descarta los campos no canónicos. Enviar el caso en formato JSON.
Estado sin evidencia Un caso figura arribado y no tiene fotografías La verificación es de la aplicación. El servidor no condiciona el cambio de estado, y además la captura pudo no transmitirse por falta de señal. Verificar las capturas efectivamente recibidas en el callback, y no deducirlas del estado del caso.
Dato duplicado La misma clave aparece más de una vez El prestador corrigió un dato ya cargado. Tomar el registro más reciente por fecha.

Compatibilidad #

Componente Desde Estado Nota
Reglas dentro del caso Versión 1 vigente El caso viaja con sus reglas y se conservan sin alteraciones.
Modos block, warn y remind Versión 1 vigente Los tres se pueden combinar entre arribo y finalización.
Campos de tipo text, number, select y check Versión 1 vigente Con sus validaciones propias.
Formato heredado separado por tabulaciones Histórico Deprecado No admite este campo. Debe usarse el formato JSON.
← Volver a la documentación de AsistManager Última actualización: 30 de septiembre de 2026