Saltar al contenido principal
Una solicitud de reporte crea un reporte de medición de techo desde una dirección de propiedad en EE. UU. Una herramienta de agenda la llama cuando se reserva una inspección. El reporte tarda unos 15 minutos, por eso la API es asíncrona.

​
Flujo

  1. Crear solicitud de reporte con la dirección y un Idempotency-Key. La respuesta es 202 con status: "preparing".
  2. Consulta Obtener solicitud de reporte, o suscribe un endpoint de webhook del workspace a los eventos de la solicitud.
  3. Cuando status sea ready, lee measurements, descarga report_pdf y descarga el modelo 3D de la casa desde render_3d.download_url. Consulta Modelo 3D.
El plan del workspace debe incluir Reportes. La creación necesita el scope reports.write. Las lecturas necesitan reports.read. Cualquier key del workspace con reports.read puede leer una solicitud, así que rotar una key conserva las solicitudes de la key anterior.

​
Reglas de creación

  • address es obligatorio y debe parecer una dirección de propiedad en EE. UU.
  • lat y lng son opcionales, pero deben ir juntos. Sin ellos, RoofKit ubica la dirección, o el place_id de Google Places cuando lo envías.
  • Una dirección que RoofKit no puede ubicar devuelve 400 VALIDATION_ERROR. Envía lat y lng con la dirección.
  • external_report_id es tu id, por ejemplo el id de la inspección. Una solicitud activa con el mismo id responde la creación con 200 y reused: true. Una solicitud fallida no cuenta.
  • roof_material es shingle, tile o metal. Sin él, el equipo del workspace elige el acabado después en RoofKit.
  • El mismo Idempotency-Key y el mismo payload repiten la primera respuesta con Idempotency-Replayed: true. Una repetición no inicia nada.
Un workspace también puede crear solicitudes desde JobNimbus, sin llamada del socio. Esa solicitud tiene source: "jobnimbus" y toma el id del trabajo de JobNimbus como external_report_id. Si envías el mismo id de trabajo, recibes esa misma solicitud, así una reserva nunca compra dos reportes.

​
Estado

Valores de attention_reason:
  • needs_outline: la IA no pudo trazar el techo. Un miembro del equipo dibuja el contorno en RoofKit y la ejecución continúa.
  • preparation_failed: una etapa se detuvo. Un miembro del equipo la reintenta en RoofKit.
  • insufficient_credits: la ejecución queda en pausa hasta que el workspace compre créditos y la reintente.
Cada entregable puede fallar por separado. La solicitud queda entonces ready con report_pdf_failure_code o render_3d.failure_code. Para generar otra vez un modelo 3D que falló o no existe, crea la solicitud de nuevo con el mismo external_report_id. La respuesta es 200 con reused: true, y la solicitud vuelve a rendering. Sus medidas y su PDF no cambian. Puedes hacerlo tres veces por solicitud.

​
Notificaciones

El dueño del workspace elige los eventos en Configuración para tu endpoint. data.details trae request_id y external_report_id. report_request.ready también trae source, revision_id y pdf_export_id. report_request.needs_attention trae reason.

​
Créditos

  • La creación verifica primero el precio del reporte. Un workspace que no puede pagar recibe 402 INSUFFICIENT_CREDITS y no se crea borrador.
  • La ejecución cobra el contorno con IA y el reporte, igual que el flujo por dirección de la app.
  • El PDF cobra una exportación por revisión. El modelo 3D no tiene costo.

​
Medidas

Las medidas son las cifras que la app imprime y cotiza para la revisión entregada. Las keys son snake_case estables con la unidad en el nombre. Las áreas están en pies cuadrados. Las longitudes están en pies. version cambia solo cuando se renombra o se elimina una key. Un valor en squares es su área dividida entre 100, con dos decimales. Cada valor redondea por separado, así que sloped_squares más flat_squares puede diferir de roof_squares en 0.01.

​
Plano y pendiente pronunciada

  • Una cara es plana cuando el equipo la marca como techo plano, o cuando su pendiente es menor que 2/12. La pendiente redondea primero a un número entero, así una cara a 1.6/12 se lee como 2/12 y tiene pendiente.
  • Una cara sin pendiente no es plana.
  • La pendiente pronunciada empieza en 8/12, donde una cuadrilla no puede caminar el techo.
  • La banda steep de area_by_pitch_band_sqft empieza en 10/12. Es la banda de mano de obra de la lista de precios.

​
Nombres de las líneas del techo

Las keys de lengths_ft son los nombres estables de las líneas del techo. Cada key siempre está presente. Una key vale 0 cuando el techo no tiene esa línea.
  • eaves_flat más eaves_sloped es eaves. Las dos keys de transición de pendiente suman slope_transitions.
  • drip_edge, starter, ridge_cap y ridge_vent siguen las reglas de la lista de precios.
  • Una línea de referencia solo marca el techo. No lleva remate, así que ninguna key la cuenta.

​
Tokens de medición de JobNimbus

Estos tokens de medición de JobNimbus corresponden a una key de medida. Los tokens de cargos, desecho, retiro y permisos dependen de reglas fuera del techo, como el material del techo actual o la distancia desde el contratista. Calcúlalos de tu lado.

​
Modelo 3D

El modelo 3D es un archivo GLB (glTF binario) de la casa: las paredes, el techo con el acabado del reporte, los remates, las canaletas y las aberturas. No tiene césped, cielo ni árboles. Está en metros, así que la realidad aumentada muestra la casa a su tamaño real. Descarga el modelo 3D de la solicitud de reporte con tu API key. Redirige (307) al archivo. La URL de almacenamiento no vence, así que trátala como un secreto y llama a la ruta otra vez cuando necesites el archivo. RoofKit no sirve ningún enlace público al modelo. Aloja el archivo de tu lado y muéstralo con el <model-viewer> de Google. El visitante arrastra para girar la casa y pellizca o usa la rueda para acercar.
  • max-camera-orbit mantiene la cámara por encima del suelo, como en el editor de RoofKit.
  • touch-action="pan-y" deja que un deslizamiento vertical desplace tu página en el teléfono. Un deslizamiento horizontal gira la casa.
  • La casa de prueba dio un archivo de unos 4,4 MB.
  • Una solicitud creada antes del 29 de octubre de 2026 tiene una imagen, no un modelo. Muestra render_3d.status: "failed" con failure_code: "model_missing". Créala otra vez con el mismo external_report_id para generar el modelo.