Loading Optiviera...

REST API

Referencia API REST Optiviera

JSON · Auth JWT · Multi-tenant

Integre cualquier sistema con Optiviera a través de una API REST completamente documentada. Todos los endpoints requieren un token JWT Bearer y se limitan automáticamente a su tenant.

Inicio rápido

De cero a tu primera llamada API en tres pasos

1

Autenticarse

Envíe sus credenciales a POST /api/auth/login. La respuesta contiene un token JWT válido por 24 horas.

2

Agregar encabezado Auth

Adjunte el token a cada solicitud: Authorization: Bearer [token]

3

Llamar a la API

Todos los endpoints están bajo https://optiviera.com/api y responden con JSON. El contexto del tenant se deriva automáticamente de su token.

Autenticación

Cada solicitud debe llevar un token JWT Bearer válido obtenido del endpoint de inicio de sesión

Cómo funciona

  • POST a /api/auth/login con su email y contraseña
  • Almacene el token de forma segura (cookie httpOnly o en memoria)
  • Incluya Authorization: Bearer [token] en cada solicitud posterior
  • Los tokens caducan después de 24 horas — renueve con POST /api/auth/refresh
Solicitud de inicio de sesiónbash
curl -X POST https://optiviera.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"••••"}'
Respuesta exitosajson
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400,
  "tokenType": "Bearer"
}
Usar el tokenhttp
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

URL base y Formato

Todo lo que necesita saber antes de su primera llamada

URL base: https://optiviera.com/api — Todos los endpoints son relativos a esta URL base. Use siempre HTTPS.

Formato JSON

Todas las solicitudes y respuestas usan application/json. Establezca Content-Type: application/json en operaciones de escritura.

Alcance de tenant

Los datos se filtran automáticamente a su organización usando el TenantId incluido en su JWT.

Paginación

Los endpoints de lista admiten ?page=1&pageSize=20. La respuesta incluye totalCount, page y pageSize.

Filtrado y Ordenación

La mayoría de los endpoints de lista aceptan parámetros como ?status=Open&sortBy=createdAt&sortDir=desc.

Grupos de endpoints API

12 grupos de recursos que cubren todos los módulos de la plataforma

Autenticación

  • POST/api/auth/login
  • POST/api/auth/refresh
  • POST/api/auth/logout

Tickets y HelpDesk

  • GET/api/tickets
  • POST/api/tickets
  • GET/api/tickets/{id}
  • PUT/api/tickets/{id}
  • DELETE/api/tickets/{id}
  • POST/api/tickets/{id}/comments

Finanzas y Contabilidad

  • GET/api/invoices
  • POST/api/invoices
  • GET/api/journal-entries
  • POST/api/journal-entries
  • GET/api/balance-sheet
  • GET/api/trial-balance

RRHH y Empleados

  • GET/api/employees
  • POST/api/employees
  • GET/api/employees/{id}
  • PUT/api/employees/{id}
  • GET/api/positions
  • GET/api/departments

Nómina

  • GET/api/payroll
  • POST/api/payroll/run
  • GET/api/payroll/{id}
  • PUT/api/payroll/{id}/approve

Ventas y Pedidos

  • GET/api/orders
  • POST/api/orders
  • GET/api/quotations
  • POST/api/quotations
  • GET/api/customers
  • POST/api/customers

Compras

  • GET/api/purchase-orders
  • POST/api/purchase-orders
  • GET/api/suppliers
  • POST/api/suppliers
  • GET/api/purchase-orders/{id}

Inventario

  • GET/api/products
  • POST/api/products
  • GET/api/stock-movements
  • POST/api/stock-movements
  • GET/api/warehouses

CRM y Leads

  • GET/api/leads
  • POST/api/leads
  • GET/api/contacts
  • POST/api/contacts
  • GET/api/pipeline-stages

Órdenes de trabajo

  • GET/api/work-orders
  • POST/api/work-orders
  • GET/api/work-orders/{id}
  • PUT/api/work-orders/{id}
  • DELETE/api/work-orders/{id}

Informes y Análisis

  • GET/api/reports/tickets
  • GET/api/reports/finance
  • GET/api/reports/hr
  • GET/api/reports/sales
  • GET/api/reports/inventory

Configuración

  • GET/api/settings/tenant
  • PUT/api/settings/tenant
  • GET/api/settings/users
  • GET/api/sla-configs
  • POST/api/sla-configs

Códigos de estado HTTP

La semántica HTTP estándar se utiliza de forma coherente en toda la API

200OK

Solicitud exitosa. El cuerpo contiene el resultado.

201Creado

Recurso creado. El cuerpo contiene el nuevo objeto con su ID.

204Sin contenido

Solicitud exitosa. Sin cuerpo (usado para DELETE).

400Solicitud incorrecta

Solicitud mal formada o campos obligatorios faltantes.

401No autorizado

Token JWT faltante, caducado o inválido.

403Prohibido

Token válido pero permisos insuficientes para esta acción.

404No encontrado

El recurso no existe o pertenece a otro tenant.

422Error de validación

La validación de entrada falló. Vea el array details en el cuerpo de la respuesta.

500Error del servidor

Error inesperado del servidor. Contacte al soporte con el ID de solicitud.

Formato de respuestas de error

Todas las respuestas de error siguen una estructura JSON coherente

Cuando una solicitud falla, la API devuelve un cuerpo JSON estructurado. Use el array details para retroalimentación de validación a nivel de campo.

  • status — HTTP status code
  • error — Error type identifier
  • message — Human-readable description
  • details — Field-level validation errors (array)
Ejemplo de respuesta de errorjson
{
  "status": 422,
  "error": "ValidationError",
  "message": "Request validation failed",
  "details": [
    { "field": "email", "message": "Email is required" },
    { "field": "password", "message": "Minimum 8 characters" }
  ]
}

¿Listo para integrar?

Explore la documentación Swagger interactiva completa o contacte a nuestro equipo para acceso a la API.