Peritaje de daños

Responde: ¿cuánta superficie del lote se dañó tras este evento? Es el producto más caro de los tres y el único con tres pasos, porque tiene un problema que los otros no: después de un evento puede que todavía no haya imagen satelital utilizable.

Tres pasos, y por qué

sequenceDiagram
    participant C as Tu sistema
    participant A as API
    C->>A: POST /v1/damage/feasibility
    A-->>C: 200 · { status: ready | pending_post_imagery | cloud_blocked }
    Note over C: si no está ready, no gastes: reintentá más tarde
    C->>A: POST /v1/damage/assessments
    A-->>C: 202 · trabajo encolado
    C->>A: POST /v1/damage/reports { assessmentId }
    A-->>C: 202 · trabajo encolado

El primer paso no consume cuota y por eso no exige Idempotency-Key: sólo consulta el catálogo de escenas. Consultarlo antes de peritar te evita pagar por un cálculo que va a devolver "no se puede todavía".

1. ¿Se puede peritar ya?

curl -s -X POST "$BASE/v1/damage/feasibility" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "ring": [[-59.95,-35.05],[-59.94,-35.05],[-59.94,-35.06],[-59.95,-35.06],[-59.95,-35.05]],
    "peril": "granizo",
    "eventDate": "2026-02-15"
  }'

El peril va en español: granizo, inundacion o sequia. Otro valor responde unsupported_peril.

La sequía casi siempre da ready: se computa contra una climatología de varios años y no necesita una escena posterior puntual.

2. Computar el daño

De dónde sale aoi_ref

Es la referencia a un lote ya dibujado, no una geometría que viaje en el pedido. Es el único punto en que el peritaje se aparta de los otros dos productos, que reciben las coordenadas en la misma llamada.

Hay tres lotes de demostración, linderos entre sí, en los dos entornos:

Son linderos a propósito: un granizo no respeta alambrados, y peritar dos lotes vecinos por el mismo evento es el caso que vas a querer probar. Cada uno tiene su propia superficie, así que los dos peritajes dan resultados distintos y la deduplicación por contenido no los confunde.

Una referencia que no está en esa tabla —demo:lote-9, por ejemplo— termina en failed con aoi_not_found: no es un error del pedido, es que ese lote no existe.

Dar de alta tus lotes

curl -s -X POST "$BASE/v1/aois" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Campo El Ombú",
    "ring": [[-59.724109,-34.121614],[-59.722668,-34.121166],
             [-59.720789,-34.122512],[-59.722606,-34.123115]],
    "labels": ["campaña-2026", "soja"]
  }'

Devuelve el aoiRef con el que se perita:

{
  "aoiRef": "org:campo-el-ombu-a1b2c3",
  "version": 1,
  "hectares": 3.29,
  "ring": [[-59.724109,-34.121614], "…", [-59.724109,-34.121614]]
}

El anillo no hace falta cerrarlo: si el último punto no repite el primero, se cierra al guardarlo. Lo que sí importa es el orden — [lng, lat], la longitud primero, con la misma trampa de Google Maps que describe la guía de edificación.

Tres cosas del alta que conviene saber:

• La superficie la calculamos nosotros a partir del polígono, y es la que va a aparecer en el peritaje. No se acepta un valor del cliente: si la superficie declarada y la geometría no coincidieran, todo porcentaje de daño estaría mal.
• El lote se versiona. version arranca en 1 y sube con cada edición de la geometría. Un peritaje cita el lote y su versión, así que un dossier ya emitido sigue mostrando el lote que midió aunque después lo redibujes.
• Idempotency-Key es obligatoria. Un reintento por timeout, sin ella, crearía dos lotes con el mismo polígono y referencias distintas, y no sabrías cuál citar.

El alta no corre en el sandbox. Ese entorno no tiene base, así que un lote cargado ahí no existiría para el peritaje que lo cite. Responde 501 diciéndolo. Cargá tus lotes contra producción.

curl -s -X POST "$BASE/v1/damage/assessments" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "parameters": {
      "aoi_ref": "demo:lote-1",
      "aoiVersion": 1,
      "event_ref": "ev-granizo-2026-02-15",
      "peril": "granizo",
      "eventDate": "2026-02-15",
      "threshold": 0.18,
      "licenceTier": "unverified"
    }
  }'

Devuelve 202. El resultado trae las hectáreas dañadas, el porcentaje afectado y la procedencia: qué ventanas se compararon, cuántas escenas de cada lado y con qué corte de nubes.

aoiVersion entra en la identidad del cálculo: redibujar el lote es otro peritaje, y tiene que serlo — un peritaje sobre una geometría vieja afirmaría algo sobre una superficie que ya no es la del lote.

3. Emitir el dossier

curl -s -X POST "$BASE/v1/damage/reports" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"assessmentId":"job_footprint_…","locale":"es-AR"}'

El assessmentId es el id del trabajo del paso 2, ya en succeeded. El dossier cita ese peritaje: de ahí salen las ventanas comparadas y las escenas usadas, que es lo que el documento declara.

Qué trae el dossier

En este orden, porque es el que sigue un perito para sostener una conclusión:

1. Resumen — lote, evento, superficie afectada neta y severidad predominante.
2. Evento y método — índice, sensor, umbral, ventanas comparadas y escenas.
3. Mapa — el lote en naranja y el footprint de daño en rojo, vectorizado píxel a píxel sobre la imagen satelital.
4. Índices espectrales — el índice medio antes y después, con su variación. El signo importa: negativo es caída, que es lo que el daño produce.
5. Severidad por zona — cuánta superficie quedó en daño severo, moderado y leve. Un lote con 40 % afectado no se ajusta igual si es todo leve que si un tercio está perdido.
6. Diagnóstico diferencial — el desglose que explica la cifra.
7. Observables, marco legal y metodología, y procedencia con hash y firma.

El desglose crudo / control / neto

El resultado del paso 2 trae damageBreakdown, y el dossier lo imprime:

La corrección no es cosmética. En una helada, buena parte de la caída del índice es el cultivo secándose como todos los años, y el número que corresponde peritar es el excedente: informar el crudo puede exagerar el siniestro varias veces.

Cuando controlFound es false no hubo línea de base con la que comparar. Eso no es un control de cero: el neto queda igual al crudo y el documento lo dice explícitamente, para que se lea como una cota superior y no como una medición.

Lo que se rompe

La tabla completa de códigos está en Trabajos, entrega y errores.

Qué afirma, y qué no

• Compara escenas previas y posteriores al evento sobre el mismo lote. Lo que detecta es un cambio en la respuesta espectral, compatible con daño.
• Para granizo y helada aplica además un control interanual a fenología igualada: la misma ventana un año atrás sobre el mismo lote. Un píxel cuenta como dañado sólo si cayó este año y no cayó el anterior, de modo que la evolución normal del cultivo queda descontada en vez de sumarse al siniestro.
• El diagnóstico diferencial puede incluir una interpretación redactada automáticamente sobre las cifras del informe. Ese texto queda fuera del hash de contenido y el documento lo declara: la firma cubre las cifras, que son las que se pueden rehacer.
• La nubosidad degrada el resultado. El informe declara el corte usado y cuántas escenas quedaron de cada lado.
• La inundación se detecta hoy con índices ópticos: bajo nubes persistentes la sensibilidad cae. El radar (que ve a través de nubes) es una mejora pendiente y está declarada como limitación en el documento.
• La resolución es de 10 m: daños en parches menores a eso no se resuelven individualmente.

Es evidencia técnica reproducible sobre superficie afectada. No reemplaza una inspección en campo ni fija un monto indemnizatorio.