> ## Documentation Index > Fetch the complete documentation index at: https://docs.roofkit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Solicitudes de reporte de techo > Pide un reporte de medición de techo desde una dirección y lee las medidas, el PDF y el modelo 3D de la casa. 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](https://docs.roofkit.ai/es/api-reference/reports/create-report-request.md) con la dirección y un `Idempotency-Key`. La respuesta es `202` con `status: "preparing"`. 2. Consulta [Obtener solicitud de reporte](https://docs.roofkit.ai/es/api-reference/reports/get-report-request.md), 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](#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 | Estado | Significado | | - | - | | `preparing` | La IA mide el techo. | | `needs_attention` | El reporte espera al equipo del workspace en RoofKit. `attention_reason` indica por qué. | | `rendering` | El reporte está registrado. RoofKit genera las medidas, el PDF y el modelo 3D. | | `ready` | Los entregables están disponibles. | | `failed` | Los entregables fallaron tres veces, o el equipo archivó el reporte antes de que estuviera listo. `failure_code` indica por qué. | 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 | Evento | Cuándo | | - | - | | `report_request.ready` | Una vez, cuando se generan los entregables. Otra vez cuando una creación genera de nuevo un modelo 3D que falló. | | `report_request.needs_attention` | Cada vez que el borrador empieza a esperar al equipo, y una vez cuando la solicitud falla. | 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. | Key | Contenido | | - | - | | `roof_material` | Acabado del techo del reporte: `shingle`, `tile`, `metal` o null antes de que el equipo elija uno. Es el techo nuevo, no el techo actual. | | `roof_area_sqft`, `roof_squares` | Área medida del techo, antes del desperdicio. Las caras planas cuentan. Las losas no. | | `sloped_area_sqft`, `sloped_squares` | Área de las caras que no son planas. | | `flat_area_sqft`, `flat_squares` | Área de las caras planas. | | `steep_slope_area_sqft`, `steep_slope_squares` | Área con pendiente de 8/12 o más. | | `predominant_pitch`, `predominant_pitch_rise` | Pendiente ponderada por área, como `6/12`. | | `facets` | Cantidad de caras del techo. | | `suggested_waste_pct` | Desperdicio que sugiere la forma del techo. | | `waste_table` | Área y squares a pedir con cada factor de desperdicio. Los squares redondean hacia arriba a un paquete, como en el PDF. | | `area_by_pitch` | Área y proporción de cada pendiente. | | `area_by_pitch_band_sqft` | `low` (6/12 o menos), `mid` (7/12 a 9/12) y `steep` (10/12 o más). Son las bandas de mano de obra. | | `unpitched_area_sqft` | Área de caras sin pendiente. Estas caras cuentan como `low`. | | `lengths_ft` | Longitudes de líneas en pies. Consulta [Nombres de las líneas del techo](#nombres-de-las-líneas-del-techo). | | `penetrations` | Cantidades de `skylights`, `chimneys`, `vents` y `pipe_boots`, o null. | | `walls` | `perimeter_ft` y `gable_area_sqft`, o null. | | `metal_panels` | `stock_ft`, `piece_count` e `is_complete` para un diseño de paneles metálicos, o null. | 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. | Key | Nombre en la app y el PDF | Líneas que suma | | - | - | - | | `eaves` | Aleros | Alero | | `eaves_flat` | Ninguno | Líneas de alero cuyas caras son todas planas | | `eaves_sloped` | Ninguno | Las demás líneas de alero, y las líneas de alero sin cara | | `rakes` | Bordes inclinados | Borde inclinado | | `ridges` | Cumbreras | Cumbrera | | `hips` | Limatesas | Limatesa | | `valleys` | Limahoyas | Limahoya | | `step_flashing` | Tapajuntas escalonado | Tapajuntas escalonado y muro lateral | | `wall_flashing` | Tapajuntas de muro | Tapajuntas de faldón y muro de cabecera | | `parapets` | Parapeto | Parapeto | | `slope_transitions` | Transición de pendiente | Transición de pendiente | | `slope_transitions_pitch_to_pitch` | Ninguno | Líneas de transición entre dos caras con pendiente | | `slope_transitions_flat_to_pitch` | Ninguno | Líneas de transición con una cara plana de un lado | | `drip_edge` | Gotero | Aleros más bordes inclinados | | `starter` | Ninguno | Aleros más bordes inclinados | | `ridge_cap` | Caballete | Cumbreras más limatesas | | `ridge_vent` | Ninguno | Cumbreras | * `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. | Token de JobNimbus | Key | | - | - | | Sloped Roof Squares (SQ) | `sloped_squares` | | Flat Roof Squares (SQ) | `flat_squares` | | Flat Roof Eaves (LF) | `lengths_ft.eaves_flat` | | Total Eaves (Non Flat) (LF) | `lengths_ft.eaves_sloped` | | Total Ridges (LF) | `lengths_ft.ridges` | | Total Hips (LF) | `lengths_ft.hips` | | Total Valleys (LF) | `lengths_ft.valleys` | | Total Rakes (LF) | `lengths_ft.rakes` | | Total Sidewall (LF) | `lengths_ft.step_flashing` | | Total Headwall (LF) | `lengths_ft.wall_flashing` | | Pitch-to-Pitch Slope Transition (LF) | `lengths_ft.slope_transitions_pitch_to_pitch` | | Flat-to-Pitch Slope Transition (LF) | `lengths_ft.slope_transitions_flat_to_pitch` | | Ridge Vent (LF) | `lengths_ft.ridge_vent` | | Steep Squares (SQ) | `steep_slope_squares`, desde 8/12. Para otro límite, suma las filas de `area_by_pitch`. | 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](https://docs.roofkit.ai/es/api-reference/reports/download-report-request-3d-model.md) 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 `` de Google. El visitante arrastra para girar la casa y pellizca o usa la rueda para acercar. ```html theme={null} ``` * `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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.