#Repasos

La API pública permite crear un repaso con pocos datos y completarlo después. El alta solo exige projectId y title; Trowel asigna el código y crea el repaso en estado pending. El proyecto no se puede cambiar al actualizarlo.

#Scopes

• snag-points:read permite consultar repasos, historial, fotos, comentarios y catálogos.
• snag-points:write permite crear, actualizar, eliminar, cambiar el estado y gestionar fotos y comentarios.

all:read y all:write incluyen estos permisos.

#Crear un repaso

POST /api/public/v1/snag-points usa multipart/form-data. La parte data contiene JSON. Las fotos del repaso se envían como partes photos; pueden repetirse. Cada comentario inicial puede indicar imagePartKey, cuyo valor debe coincidir con una única parte de archivo.

{
  "projectId": "0d3fa80a-d8aa-4a95-84b7-8f6a157005ea",
  "title": "Humedad en el portal",
  "priority": "high",
  "comments": [
    {
      "key": "community-notice",
      "text": "Aviso recibido del administrador",
      "imagePartKey": "comment-community-notice"
    }
  ]
}

Un comentario admite una sola imagen opcional. El repaso admite varias fotos. Cada archivo puede ocupar hasta 10 MB, el conjunto de archivos hasta 50 MB y la petición hasta 20 archivos. Se admiten JPEG, PNG, WebP, HEIC y HEIF.

Envía Idempotency-Key al crear. Repetir la misma petición con la misma clave devuelve el repaso ya creado. Reutilizarla con otros datos devuelve 409.

#Sincronización

GET /api/public/v1/snag-points?modifiedAfter={fecha} devuelve los repasos creados o modificados después de la fecha. Añadir, editar o borrar un estado, una foto o un comentario actualiza también la fecha de modificación del repaso.

También se puede filtrar por la fecha del repaso con dateFrom y dateTo. Ninguno de los filtros temporales es obligatorio. Una consulta sin ellos puede descargar todo el histórico y queda registrada para detectar integraciones poco eficientes.

La respuesta del listado incluye los contadores de fotos, comentarios y estados. Las colecciones se leen en sus endpoints propios.

#Estados, fotos y comentarios

Los estados son pending, resolved, rejected y closed. Las prioridades son low, medium y high.

Una transición de estado puede incluir varias fotos. Esas fotos quedan asociadas a la entrada de historial creada por la transición. Las fotos añadidas posteriormente se asocian al estado vigente.

Los comentarios tienen endpoints de alta, edición y borrado. Cada comentario conserva texto y, como máximo, una imagen. Al editar se puede reemplazar o quitar la imagen.

#Catálogos

• GET /api/public/v1/snag-points/catalogues/categories
• GET /api/public/v1/snag-points/catalogues/responsible-companies
• GET /api/public/v1/projects/{projectId}/situations

Estos catálogos también usan limit, cursor y sort. situationDescription corresponde a la ubicación seleccionada del proyecto y no se edita desde el repaso.

La primera versión no incluye exportaciones, clonado, código manual ni referencias externas. Si una integración necesita relacionar sus incidencias con Trowel, debe guardar el id devuelto por la API.