import { Steps, Aside } from "@astrojs/starlight/components";

Toda llamada a la API (salvo el sandbox local) se autentica con una API key
en el header `X-API-Key`. El tenant y el ambiente de DGII con el que vas a
trabajar salen de la propia key, así que no los mandas en el payload.

## El formato de la key

Una API key tiene este formato:

```
sk_nfe_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

El segmento después de `sk_nfe_` te dice de un vistazo con qué ambiente vas
a emitir: `test` (TesteCF), `cert` (CerteCF, el ambiente de certificación) o
`prod` (Producción). **La key es el único selector de ambiente**: es
imposible emitir en producción con una key de prueba.

<Aside type="caution" title="Se muestra una sola vez">
  NovaFE guarda solo el hash de tu key. Si la pierdes, no hay forma de
  recuperarla: hay que revocarla y acuñar una nueva.
</Aside>

## Obtén una key

<Steps>

1. En el panel de NovaFE, ve a las API keys de tu tenant y pide una key
   indicando una etiqueta, el ambiente (`test`, `cert` o `prod`) y el
   rol. La creación de keys es una acción de administración que se hace
   desde el panel, no forma parte de la API de integración.

2. El panel muestra el token en claro **una sola vez**, con este formato:

   ```text
   sk_nfe_test_ab12cd34ef56...
   ```

3. Guárdalo como variable de entorno y mándalo en cada request:

   ```bash
   export NOVAFE_API_KEY="sk_nfe_test_ab12cd34ef56..."

   curl https://api.novafe.example/api/v1/ecf/{id} \
     -H "X-API-Key: $NOVAFE_API_KEY"
   ```

</Steps>

## Roles

El rol queda fijo en la key (para cambiarlo, se revoca y se acuña otra):

| Rol            | Puede                                                |
| -------------- | ---------------------------------------------------- |
| `consultor`    | Consultar comprobantes y su estado.                  |
| `emisor`       | Emitir y reencolar e-CF, más todo lo de `consultor`. |
| `admin_tenant` | Certificados, secuencias y conexión con la DGII.     |

## Probar sin credenciales reales

Para desarrollo local, `POST /api/v1/dev/sandbox` crea un contribuyente de
prueba completo (perfil, certificado autofirmado y rango de secuencias) y
devuelve una API key lista para usar en el ambiente de prueba, sin tener que
pasar por el onboarding real.