Autenticación

Todas las peticiones a /v1 se autentican con una API Key en la cabecera x-api-key:

curl "$API_URL/v1/avaluos/AVL-2026-000123" \
  -H "x-api-key: sai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

La llave es un secreto de servidor

Úsala sólo desde tu backend. No la pongas en una app móvil, en JavaScript que corre en el navegador ni en un repositorio: quien la tenga puede actuar en nombre de tu integración.

Cómo conseguir una llave

Las emite el equipo de Tasvalúo. Al pedirla indica:

El entorno: test para desarrollar y probar, live para operar con datos reales.
Los scopes que tu integración necesita (ver abajo). Pide sólo los necesarios: se pueden ampliar después sin cambiar la llave.

El secreto se muestra una sola vez

Guárdala en tu gestor de secretos en cuanto la recibas. El sistema no conserva el valor en claro: si se pierde, hay que rotarla para obtener una nueva.

Entornos

El prefijo de la llave indica su entorno.

Prefijo	Entorno	Para qué
`sai_test_…`	Pruebas	Desarrollo e integración.
`sai_live_…`	Producción	Avalúos reales.

Scopes

Cada endpoint exige uno o varios scopes, que aparecen en su ficha de la referencia. Si la llave no los tiene, la respuesta es 403.

Scope	Permite
`avaluos:read`	Consultar avalúos, su estado, hallazgos y documentos; seguir el avance; leer los catálogos básicos.
`avaluos:write`	Subir PDFs, crear avalúos, re-subir documentos, lanzar la evaluación y emitir el certificado.
`avaluos:justify`	Justificar hallazgos y quitar justificaciones.
`avaluos:verify`	Verificar un certificado contra su PDF.
`avaluos:delete`	Eliminar avalúos creados por la misma llave.
`control:read`	Consultar las bandejas y el detalle del panel del controlador.
`control:write`	Registrar verificaciones y emitir o reabrir dictámenes.
`catalogos:read`	Consultar los catálogos completos, incluidas las filas inactivas.
`catalogos:write`	Dar de alta, editar y dar de baja filas de los catálogos.
`config:read`	Consultar los parámetros del motor de evaluación.
`config:write`	Modificar esos parámetros.
`metrics:read`	Consultar métricas agregadas.

Qué pedir según tu caso

avaluos:read, avaluos:write, avaluos:justify y, si permite borrar, avaluos:delete.

Sube avalúos, sigue su avance, justifica hallazgos y emite el certificado.

Ciclo de vida de una llave

Estado	Qué significa
Activa	Funciona con normalidad.
Desactivada	Suspendida temporalmente. Responde `401` hasta que se reactive.
Revocada	Retirada para siempre. Responde `401`.

Rotar una llave genera un secreto nuevo y revoca el anterior. Es lo que hay que pedir si una llave se filtró: actualiza el secreto en tu sistema en cuanto recibas el nuevo.

Cada llave tiene su propia cuota de peticiones por minuto, además de un límite global de 100 peticiones cada 60 segundos. Al superarlo la respuesta es 429: espera y reintenta con backoff exponencial.

Errores de autenticación

Se devuelven antes de validar el cuerpo de la petición, y no llevan code.

HTTP	`message`	Qué hacer
`401`	`API Key requerida (header x-api-key)`	Añade la cabecera `x-api-key`.
`401`	`API Key inválida, revocada o expirada`	Revisa que copiaste la llave completa y que siga activa.
`403`	`Faltan scopes: …`	Pide que añadan a tu llave los scopes que indica el mensaje.
`429`	—	Reduce el ritmo y reintenta más tarde.

401

{
  "statusCode": 401,
  "timestamp": "2026-06-24T18:30:00.000Z",
  "path": "/v1/avaluos/AVL-2026-000123",
  "method": "GET",
  "message": "API Key inválida, revocada o expirada",
  "error": "Unauthorized"
}