> For the complete documentation index, see [llms.txt](https://academy.trowelapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.trowelapp.com/desarrolladores/api-publica.md).

# API pública

Contrato común de la API pública V1 de Trowel.

La API pública permite conectar sistemas externos con Trowel mediante credenciales propias de cada integración. Las rutas compatibles empiezan por `/api/public/v1` y aparecen en el documento OpenAPI `public-v1`.

Los endpoints internos de Trowel, aunque aparezcan en el Swagger de desarrollo, no forman parte de este contrato.

## Antes de empezar

Necesitas estos datos:

* API key completa de una credencial activa.
* Scopes concedidos al cliente de API.

El administrador del tenant crea el cliente y sus credenciales desde **Administración → Claves de API**. La API key completa se muestra una sola vez al crear o rotar una credencial. Si se pierde, hay que crear otra credencial o rotar la existente.

## Flujo de una petición

1. Solicita un token con `POST /api/public/v1/token`.
2. Conserva el token en memoria y envíalo como `Authorization: Bearer <token>`.
3. Llama únicamente a operaciones incluidas en la referencia pública.
4. Cuando caduque el token, solicita otro con la misma credencial.

Los tokens no tienen refresh token. Una credencial revocada o un cliente desactivado dejan de funcionar de inmediato, aunque el JWT todavía no haya caducado.

## Compatibilidad

Dentro de V1 pueden añadirse campos opcionales y operaciones nuevas. Eliminar un campo, cambiar su tipo o modificar su significado requiere una nueva versión mayor.

La referencia OpenAPI se publica en `/swagger/public-v1/swagger.json` en cada entorno. La referencia interactiva está en el [portal de desarrolladores](https://developers.trowelapp.com/documentation). Academy explica los conceptos y los flujos de trabajo; el portal contiene los endpoints y modelos vigentes.

## Recursos

* [Autenticación y credenciales](/desarrolladores/api-publica/autenticacion-y-credenciales.md)
* [Scopes y autorización](/desarrolladores/api-publica/scopes-y-autorizacion.md)
* [Paginación y errores](/desarrolladores/api-publica/paginacion-y-errores.md)
* [Clientes](/desarrolladores/api-publica/clientes.md)
* [Productos, proveedores y precios](/desarrolladores/api-publica/productos-proveedores-y-precios.md)
* [Proyectos y series](/desarrolladores/api-publica/proyectos-y-series.md)
* [Repasos](/desarrolladores/api-publica/repasos.md)
* [Partes de trabajo](/desarrolladores/api-publica/partes-de-trabajo.md)
* [Trabajar con el portal de desarrolladores](/desarrolladores/api-publica/consola.md)