# Zapini API — Autenticación

**Versión:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticación

La API soporta dos métodos de autenticación:

### 1. Tokens de Usuario (Sanctum)
Después de iniciar sesión vía `/auth/login`, recibes un token de usuario para acceso completo a la plataforma.

### 2. Tokens de API de Instancia (Recomendado para Integraciones)
Genera tokens de API (prefijo `sk_`) para instancias específicas de WhatsApp. Estos tokens:
- No requieren inicio de sesión de usuario
- Están limitados a una sola instancia
- Pueden ser revocados independientemente
- Funcionan con todos los endpoints de la API

### Encabezados Requeridos

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

---

## POST /auth/login

Autenticar y recibir token de acceso.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| email | string | Sí | Email del usuario |
| password | string | Sí | Contraseña del usuario |
| device_name | string | No | Nombre del dispositivo |

**Ejemplo de Solicitud:**

```bash
curl -X POST https://zapini.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password",
    "device_name": "My App"
  }'
```

**Respuesta Exitosa:**

```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 1,
      "name": "User",
      "email": "user@example.com",
      "role": "admin",
      "locale": "en",
      "tenant": {
        "id": 1,
        "name": "My Company",
        "status": "active"
      }
    },
    "token": "1|abc123xyz...",
    "token_type": "Bearer",
    "expires_at": null
  }
}
```

**Respuesta cuando se Requiere 2FA:**

```json
{
  "success": true,
  "two_factor_required": true,
  "message": "Two-factor verification required"
}
```

---

## POST /auth/two-factor

Completar inicio de sesión con código 2FA.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| email | string | Sí | Email del usuario |
| password | string | Sí | Contraseña del usuario |
| code | string | Sí | Código 2FA (6 dígitos) |
| device_name | string | No | Nombre del dispositivo |

---

## POST /auth/register

Registrar un nuevo usuario.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| name | string | Sí | Nombre completo |
| email | string | Sí | Email (único) |
| password | string | Sí | Contraseña (mín. 8 caracteres) |
| password_confirmation | string | Sí | Confirmación de contraseña |
| device_name | string | No | Nombre del dispositivo |
| terms_accepted | boolean | Sí | Aceptación de términos |

---

## GET /auth/me

Retorna datos del usuario autenticado.

**Headers:** Requiere autenticación

**Respuesta:**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "User",
      "email": "user@example.com",
      "role": "admin",
      "locale": "en",
      "timezone": "America/New_York",
      "email_verified": true,
      "two_factor_enabled": false,
      "tenant": {
        "id": 1,
        "name": "My Company",
        "status": "active"
      }
    }
  }
}
```

---

## PATCH /auth/me

Actualizar perfil del usuario.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| name | string | No | Nuevo nombre |
| locale | string | No | Idioma (en, pt-BR, es) |
| timezone | string | No | Zona horaria |

---

## POST /auth/logout

Finalizar sesión actual (revocar token).

---

## POST /auth/logout-all

Finalizar todas las sesiones (revocar todos los tokens).

---

## POST /auth/refresh

Renovar el token de acceso.

**Respuesta:**

```json
{
  "success": true,
  "message": "Token refreshed",
  "data": {
    "token": "2|new_token...",
    "token_type": "Bearer",
    "expires_at": null
  }
}
```

---

## POST /auth/password/forgot

Enviar email de recuperación de contraseña.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| email | string | Sí | Email del usuario |

---

## POST /auth/password/reset

Restablecer contraseña con token de recuperación.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| token | string | Sí | Token de recuperación |
| email | string | Sí | Email del usuario |
| password | string | Sí | Nueva contraseña |
| password_confirmation | string | Sí | Confirmación |

---

## POST /auth/password/change

Cambiar contraseña (usuario autenticado).

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| current_password | string | Sí | Contraseña actual |
| password | string | Sí | Nueva contraseña |
| password_confirmation | string | Sí | Confirmación |

---

## GET /auth/sessions

Listar todas las sesiones activas del usuario.

**Respuesta:**

```json
{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 1,
        "name": "Chrome - Windows",
        "last_used_at": "2025-01-15T10:30:00Z",
        "created_at": "2025-01-10T08:00:00Z",
        "is_current": true
      }
    ]
  }
}
```

---

## DELETE /auth/sessions/{id}

Revocar una sesión específica.

---

*Generado por Zapini — https://zapini.app*