# Crear una credencial; la clave se muestra una sola vez

> POST /api/configuracion/api-externa/credenciales

`POST /api/configuracion/api-externa/credenciales`

Exige el plan Enterprise: sin él, 403 `PLAN_SIN_API` con `upgrade_url`.

> Autenticación: sesión del panel de Turnova (dueña o administradora). No se llama con una clave de la API.

## Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `nombre` | string | Sí | Hasta 80 caracteres. |
| `tipo` | `PUBLICA`, `SECRETA` | Sí |  |
| `scopes` | array de `catalogo:leer`, `disponibilidad:leer`, `reservas:crear`, `reservas:leer` | Sí | `reservas:leer` solo para SECRETA. Entre 1 y N elementos. |
| `origenes` | array de string | No | Obligatorio (1 a 10) para PUBLICA; prohibido para SECRETA. https, o http://localhost / 127.0.0.1. Entre 0 y 10 elementos. |

## Ejemplo

```js
// Desde el panel de Turnova, con la sesión iniciada (cookie).
const res = await fetch("/api/configuracion/api-externa/credenciales", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "nombre": "Masaje descontracturante",
    "tipo": "PUBLICA",
    "scopes": [
      "catalogo:leer",
      "disponibilidad:leer",
      "reservas:crear"
    ]
  }),
});
const r = await res.json();
```

## Respuestas

| HTTP | Qué significa |
| --- | --- |
| 201 | Creada |
| 400 | Datos inválidos: mirá `error.campos` (`ENTRADA_INVALIDA`, `IDEMPOTENCY_KEY_FALTANTE`…). |
| 401 | Clave faltante, inválida o revocada. |
| 403 | Origen no permitido, permiso faltante, clave secreta desde un navegador o plan sin la API (`PLAN_SIN_API`). |
| 404 | No existe o no es de este negocio. |

### Respuesta 201

```json
{
  "ok": true,
  "datos": {
    "credencial": {
      "id": "cmh4k2n9x0001",
      "nombre": "Masaje descontracturante",
      "tipo": "PUBLICA",
      "prefijo": "tnv_pk_ab12cd34",
      "scopes": [
        "catalogo:leer",
        "disponibilidad:leer",
        "reservas:crear"
      ],
      "origenes": [
        "https://mi-spa.com"
      ],
      "createdAt": "2026-11-01T13:00:00.000Z",
      "ultimoUsoEn": "2026-11-01T13:05:00.000Z",
      "revocadaEn": null
    },
    "clave": "tnv_pk_ab12cd34EjemploNoUsarEstaClave0123456789",
    "aviso": "Copiá la clave ahora: no se vuelve a mostrar."
  }
}
```

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `datos.credencial` | object | No |  |
| `datos.credencial.id` | string | No |  |
| `datos.credencial.nombre` | string | No |  |
| `datos.credencial.tipo` | `PUBLICA`, `SECRETA` | No |  |
| `datos.credencial.prefijo` | string | No |  |
| `datos.credencial.scopes` | array de string | No |  |
| `datos.credencial.origenes` | array de string | No |  |
| `datos.credencial.createdAt` | string (date-time) | No |  |
| `datos.credencial.ultimoUsoEn` | string (date-time) o null | No |  |
| `datos.credencial.revocadaEn` | string (date-time) o null | No |  |
| `datos.clave` | string | No | Única vez que se devuelve. |
| `datos.aviso` | string | No |  |

Los errores siguen el formato común: ver [Errores](https://turnovapp.com/docs/errores.md).