Autenticación

Descripción general

Cotizera usa autenticación basada en sesiones con NextAuth y el proveedor de credenciales. Después de autenticarte, se emite una cookie de sesión JWT que debes incluir en todas las solicitudes posteriores a la API.

Obtener una sesión

Envía una solicitud POST al endpoint de credenciales de NextAuth:

curl -X POST https://cotizera.com/api/auth/callback/credentials \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}' \
  -c cookies.txt

Si la solicitud es exitosa, la respuesta establece una cookie next-auth.session-token. Guarda esta cookie e inclúyela en las solicitudes siguientes.

Hacer solicitudes autenticadas

Incluye la cookie de sesión en cada llamada a la API:

curl https://cotizera.com/api/quotes \
  -b cookies.txt

Estructura de la sesión

La sesión incluye los siguientes campos:

Campo	Tipo	Descripción
`user.id`	`string`	ID del usuario
`user.email`	`string`	Correo del usuario
`user.name`	`string`	Nombre para mostrar
`user.role`	`string`	`OWNER` o `COLLABORATOR`
`user.tenantId`	`string`	ID del tenant (negocio)
`user.plan`	`string`	`FREE` o `PRO`

Control de acceso basado en roles (RBAC)

Cada endpoint de la API verifica el rol del usuario antes de permitir el acceso. La matriz de permisos a continuación muestra lo que puede hacer cada rol.

Matriz de permisos

Permiso	OWNER	COLLABORATOR
`quotes:create`	✅	✅
`quotes:read`	✅	✅
`quotes:read_all`	✅	❌
`products:manage`	✅	❌
`products:read`	✅	✅
`products:create`	✅	❌
`products:update`	✅	❌
`products:delete`	✅	❌
`clients:manage`	✅	❌
`clients:read`	✅	✅
`clients:create`	✅	✅
`clients:update`	✅	❌
`clients:delete`	✅	❌
`config:manage`	✅	❌
`pipeline:view`	✅	❌
`dashboard:view`	✅	❌
`collaborators:manage`	✅	❌

Notas importantes

COLLABORATOR tiene acceso limitado: crear cotizaciones, consultar productos, consultar/crear clientes
OWNER tiene acceso completo al tenant, incluyendo configuración, pipeline, dashboard y gestión de equipo
Los colaboradores solo pueden ver sus propias cotizaciones (quotes:read), mientras que los Owners pueden ver todas las cotizaciones (quotes:read_all)

Funciones según el plan

Algunas funciones requieren el plan PRO. Si intentas acceder a una función restringida por plan con el plan FREE, recibirás un error 403.

Función	FREE	PRO
Webhooks	❌	✅
Pipeline	❌	✅
Dashboard	❌	✅
Colaboradores	❌	✅
Firmas digitales	❌	✅
Versionado de cotizaciones	❌	✅
Multi-moneda	❌	✅
Registro de auditoría	❌	✅
Portal de clientes	❌	✅
Branding en PDF	❌	✅

Ejemplo: Flujo completo de autenticación

# 1. Login and save the session cookie
curl -X POST https://cotizera.com/api/auth/callback/credentials \
  -H "Content-Type: application/json" \
  -d '{"email": "owner@mybusiness.com", "password": "s3cret"}' \
  -c cookies.txt
 
# 2. List your quotes
curl https://cotizera.com/api/quotes \
  -b cookies.txt
 
# 3. Create a new client
curl -X POST https://cotizera.com/api/clients \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name": "Acme Corp", "email": "contact@acme.com"}'

Respuestas de error

Código	Significado
`401`	No autenticado — la cookie de sesión falta o expiró
`403`	Permisos insuficientes — la verificación de rol o plan falló

Consulta la guía de Errores para la lista completa de códigos de error.

AnteriorIntroduction SiguienteErrors