Documentación API pública V1 — Trowel Developers

POST/api/public/v1/snag-points

snag-points:write

Parámetros

Idempotency-Keystringopcionalcabecera

Clave opcional para repetir la misma alta sin duplicarla.

Body de entrada

PublicSnagPointCreate

Crear repaso

Metadatos JSON de la parte data. El alta puede incluir varias fotos y comentarios con una imagen opcional cada uno.

PropiedadTipoDescripción

projectIdobligatoriouuidProyecto del repaso.

titleobligatoriostringTítulo del repaso.

descriptionstring | nullDescripción editable.

situationIduuid | nullUbicación del proyecto.

categoryIduuid | nullCategoría.

responsibleCompanyIduuid | nullEmpresa responsable.

prioritystring | nullPrioridad.

resolutionCostnumber | nullCoste de resolución.

commentsPublicInitialSnagPointComment[]Comentarios iniciales.

Ejemplo JSON

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

Respuesta

201Repaso creado.

PublicSnagPoint

Repaso

Ficha pública con contadores; las colecciones se consultan por separado.

PropiedadTipoDescripción

idobligatoriouuidIdentificador estable.

codeobligatoriointegerCódigo generado en el proyecto.

projectIdobligatoriouuidProyecto.

titleobligatoriostringTítulo.

descriptionstring | nullDescripción.

stateobligatoriostringEstado.

prioritystring | nullPrioridad.

photoCountobligatoriointegerNúmero de fotos.

commentCountobligatoriointegerNúmero de comentarios.

stateHistoryCountobligatoriointegerNúmero de estados.

createdAtobligatoriodate-timeCreación.

modifiedAtobligatoriodate-timeÚltimo cambio del repaso o de sus colecciones.

Ejemplo JSON

{
  "id": "cbefdbb8-acde-49f9-8cc5-390024315c2b",
  "code": 42,
  "projectId": "0d3fa80a-d8aa-4a95-84b7-8f6a157005ea",
  "projectCode": "OBR-2026-0042",
  "projectName": "Reforma Gran Vía",
  "title": "Humedad en el portal",
  "description": "Aparece después de llover",
  "state": "pending",
  "priority": "high",
  "photoCount": 2,
  "commentCount": 1,
  "stateHistoryCount": 1,
  "createdAt": "2026-10-10T12:00:00",
  "modifiedAt": "2026-10-10T12:00:00"
}

Ejemplo de respuesta

{
  "id": "cbefdbb8-acde-49f9-8cc5-390024315c2b",
  "code": 42,
  "projectId": "0d3fa80a-d8aa-4a95-84b7-8f6a157005ea",
  "projectCode": "OBR-2026-0042",
  "projectName": "Reforma Gran Vía",
  "title": "Humedad en el portal",
  "description": "Aparece después de llover",
  "state": "pending",
  "priority": "high",
  "photoCount": 2,
  "commentCount": 1,
  "stateHistoryCount": 1,
  "createdAt": "2026-10-10T12:00:00",
  "modifiedAt": "2026-10-10T12:00:00"
}

Errores

400Solicitud incorrectaapplication/json

401Autenticación inválida o no proporcionadaapplication/json

403Permisos insuficientesapplication/json

404Recurso no encontradoapplication/json

409Conflicto con el estado actualapplication/json

410Recurso ya no disponibleapplication/json

422Error de validaciónapplication/json

429Límite de solicitudes excedidoapplication/json

Ver modelo de error

PublicApiError

Error de API

Formato estable de los errores públicos.

PropiedadTipoDescripción

statusobligatoriointegerCódigo HTTP.

codeobligatoriostringCódigo estable para tratamiento automático.

messageobligatoriostringMensaje legible.

correlationIdobligatoriostringIdentificador para soporte y trazabilidad.

currentConcurrencyTokenstring | nullToken actual cuando existe un conflicto.

validationErrorsobject<string,string[]>Errores agrupados por campo.

Ejemplo JSON

{
  "status": 422,
  "code": "validation_error",
  "message": "The request is invalid.",
  "correlationId": "01J9EXAMPLE",
  "validationErrors": {
    "unitCode": [
      "The unit does not exist."
    ]
  }
}