JN.devBackend Modular · API

Referencia de la API

Endpoints reales del Backend Modular (POS). Todas las rutas usan el prefijo /api y autenticación con Bearer token (Sanctum).

Auth

core/AuthCore

Autenticación con Sanctum por correo o número telefónico. Emite el token de acceso con el plan vigente del cliente.

POST/api/auth/loginPúblico

Inicia sesión con correo o teléfono. Aplica rate limit.

Request body

Campo	Tipo	Req.	Descripción
identifier	string	requerido	Correo electrónico o número telefónico.
credential	string	requerido	Contraseña o código de acceso.

Respuesta: token, user, plan

POST/api/auth/logoutauth:sanctum

Cierra la sesión del token actual.

POST/api/auth/request-codePúblico

Solicita un código de verificación para iniciar sesión.

POST/api/auth/logout-allauth:sanctum

Cierra la sesión en todos los dispositivos.

Register

clients/RegisterClients

Registro de empresa / cliente con plan seleccionado. Devuelve el checkout de Stripe para el pago inicial.

POST/api/registerPúblico

Registra una empresa y genera el checkout de pago.

Request body

Campo	Tipo	Req.	Descripción
plan_ulid	string	requerido	ULID del plan (exists:plans).
name	string	opcional	Nombre corto / nombre comercial.
legal_name	string	opcional	Razón social.
email	email	opcional	Correo de contacto.
phone_number	string	requerido	Teléfono (único).

Respuesta: Registro exitoso + checkout de Stripe

POST/api/register/renoveauth:sanctum

Renueva la suscripción con un nuevo plan.

Request body

Campo	Tipo	Req.	Descripción
plan_ulid	string	requerido	ULID del plan a renovar.

Seguridad (OTP)

core/SecurityCore

Códigos OTP por propósito (login, 2FA) y contraseñas encriptadas para clientes.

POST/api/otp/send/{purpose}auth:sanctum

Envía un código OTP para el propósito indicado.

POST/api/otp/validatePúblico

Valida el código OTP recibido.

POST/api/security/password/enableauth:sanctum

Habilita una contraseña encriptada.

POST/api/security/password/revealauth:sanctum

Revela la contraseña encriptada.

Payments

core/PaymentsCore

Pagos abstractos sobre proveedores (Stripe, etc.). Stripe se integra como capa interna con gateways y handlers de webhook.

GET/api/paymentsauth:sanctum + licencia

Lista los pagos (con cache).

POST/api/paymentsauth:sanctum + licencia

Crea un pago para un modelo (payable).

Request body

Campo	Tipo	Req.	Descripción
payable_type	string	requerido	Modelo al que pertenece el pago (morfo).
payable_id	string	requerido	ULID del modelo relacionado.
amount	numeric	requerido	Monto del pago.
tip	numeric	opcional	Propina (opcional).
method	string	requerido	Método de pago.
provider	string	requerido	Proveedor (ej. stripe).
status	integer	opcional	Estado del pago (default 1).

GET/api/payments/{payment}auth:sanctum + licencia

Detalle de un pago.

PUT/api/payments/{payment}auth:sanctum + licencia

Actualiza un pago.

POST/api/webhooks/{provider}Público

Webhook público del proveedor (ej. stripe) para eventos como payment_intent.succeeded.

Users

core/UsersCore

Administración de usuarios con roles, propietarios y estado.

GET/api/usersauth:sanctum + licencia

Lista usuarios.

GET/api/users/{ulid}auth:sanctum + licencia

Detalle de un usuario.

POST/api/usersauth:sanctum + licencia

Crea un usuario.

Request body

Campo	Tipo	Req.	Descripción
name	string	requerido	Nombre del usuario.
client_ulid	string	opcional	Cliente / empresa al que pertenece.
email	email	requerido	Correo único.
password	string	opcional	Mín. 8 caracteres, requiere confirmation.
lastname	string	opcional	Apellido.
phone_number	string	opcional	Teléfono único.
role_ulid	string	opcional	Rol asignado (exists:roles).
user	string	opcional	Nombre de usuario (auto: slug del nombre).

PATCH/api/users/{ulid}auth:sanctum + licencia

Actualiza un usuario.

DELETE/api/users/{ulid}auth:sanctum + licencia

Elimina un usuario.

Roles

core/RolesCore

Roles de acceso con slug automático.

GET/api/rolesauth:sanctum + feature:mesas

Lista roles.

GET/api/roles/{ulid}auth:sanctum + feature:mesas

Detalle de un rol.

POST/api/rolesauth:sanctum + feature:mesas

Crea un rol.

Request body

Campo	Tipo	Req.	Descripción
name	string	requerido	Nombre único del rol.
slug	string	opcional	Auto-generado por Str::slug.
description	string	opcional	Descripción del rol.

PATCH/api/roles/{ulid}auth:sanctum + feature:mesas

Actualiza un rol.

DELETE/api/roles/{ulid}auth:sanctum + feature:mesas

Elimina un rol.

Permissions

core/PermissionsCore

Catálogo de permisos disponible en el sistema (solo lectura).

GET/api/permissionsauth:sanctum

Lista permisos (cache 60s).

GET/api/permissions/{permission}auth:sanctum

Detalle de un permiso.

IA

core/AICore

Asistencia con inteligencia artificial: chat de operación (ventas, consultas) y soporte público con webhook del proveedor.

POST/api/ai/chatauth:sanctum

Chat con IA para asistir en operación, ventas y consultas.

POST/api/ai/webhookauth:sanctum

Recibe eventos del proveedor de IA (estado de respuestas).

POST/api/ai/ventasauth:sanctum

Análisis de ventas asistido por IA (utilidad de prueba).

POST/api/ai/support/chatPúblico

Chat público de soporte al cliente con IA.

Chat

core/ChatCore

Envío de mensajes entre dispositivos / usuarios en tiempo real.

POST/api/chat/sendPúblico

Envía un mensaje.

core/WhatsAppCore

Integración con WhatsApp: verificación y recepción de mensajes por webhook.

GET/api/whatsapp/webhookPúblico

Verificación del webhook con el proveedor de WhatsApp.

POST/api/whatsapp/webhookPúblico

Recibe los mensajes entrantes de WhatsApp.

Legal

core/LegalCore

Documentos legales y aceptaciones: firma electrónica por enlace, aprobación, auditoría (PDF/ZIP) y verificación pública con sello de tiempo RFC 3161.

GET/api/legal/pendingauth:sanctum

Documentos legales pendientes del cliente.

POST/api/legal/documentsauth:sanctum

Crea un documento legal.

POST/api/legal/documents/previewauth:sanctum

Vista previa de un documento legal.

GET/api/legal/documents/{ulid}auth:sanctum

Detalle de un documento legal.

POST/api/legal/documents/{ulid}/acceptauth:sanctum

Acepta un documento legal.

POST/api/legal/documents/{document}/approveauth:sanctum

Aprueba un documento legal.

POST/api/legal/documents/{document}/rejectauth:sanctum

Rechaza un documento legal.

GET/api/legal/acceptances/{ulid}auth:sanctum

Detalle de una aceptación.

GET/api/legal/acceptances/{ulid}/audit/pdfauth:sanctum

Auditoría de la aceptación en PDF.

GET/api/legal/acceptances/{ulid}/audit/zipauth:sanctum

Auditoría de la aceptación en ZIP (evidencia).

GET/api/legal/sign/{token}auth:sanctum

Muestra el documento para firmar por enlace.

POST/api/legal/sign/{token}auth:sanctum

Firma el documento por enlace.

GET/api/legal/verify/{hash}Público

Verificación pública de un documento firmado.

GET/api/legal/rfc3161/{hash}Público

Verificación con sello de tiempo RFC 3161.

Signatures

core/SignaturesCore

Servicio de firmas electrónicas: generación de documentos firmados y PDFs certificados.

ℹ️ Módulo de servicio (sin endpoints REST propios): genera y certifica documentos firmados con vistas PDF.

Files

core/FilesCore

Almacenamiento de archivos con subida, descarga (pública/privada) y enlaces temporales firmados.

GET/api/filesauth:sanctum

Lista archivos (cache 60s).

POST/api/filesauth:sanctum

Sube un archivo (rate limit 5).

GET/api/files/{ulid}auth:sanctum

Detalle de un archivo.

PATCH/api/files/{ulid}auth:sanctum

Actualiza un archivo.

DELETE/api/files/{ulid}auth:sanctum

Elimina un archivo.

GET/api/files/{ulid}/downloadauth:sanctum

Descarga de un archivo privado.

GET/api/files/{ulid}/temporary-downloadFirmado (signed)

Descarga temporal firmada.

GET/api/files/{ulid}/temporary-generateFirmado (signed)

Genera un enlace temporal de descarga.

Notifications

core/NotificationsCore

Bandeja de notificaciones por cliente y marcado como leídas.

GET/api/notificationsauth:sanctum

Lista notificaciones (cache 60s).

PATCH/api/notifications/{notification}auth:sanctum

Marca una notificación como leída (rate limit 10).

Document Generator

core/DocumentGeneratorCore

Generación de documentos (template) y conversión a PDF.

POST/api/documents/generate

Genera un documento a partir de una plantilla.

POST/api/documents/pdf

Convierte / genera el documento en PDF.

Settings

core/SettingsCore

Configuración por grupos y claves (pares group/key).

GET/api/settings/group/{group}auth:sanctum

Lee todas las claves de un grupo.

GET/api/settings/{group}/{key}auth:sanctum

Lee una configuración.

POST/api/settings/{group}/{key}auth:sanctum

Crea una configuración.

PATCH/api/settings/{group}/{key}auth:sanctum

Actualiza una configuración.

DELETE/api/settings/{group}/{key}auth:sanctum

Elimina una configuración.

ApiSupport

core/ApiSupportCore

Capa transversal de la API: middlewares y servicios compartidos por todos los módulos.

ℹ️ Infraestructura sin endpoints propios: rate limiting (60 req/s), límite de payload (2 MB), cache de respuestas, anti-replay, cabeceras de rendimiento y firmado de solicitudes.

Sales

clients/SalesClients

Ventas con detalle de items y estados (pending, paid). El monto se compone de unit_price × quantity por item.

GET/api/sales

Lista ventas.

GET/api/sales/{ulid}

Detalle de una venta.

POST/api/sales

Crea una venta con items.

Request body

Campo	Tipo	Req.	Descripción
client_ulid	string	requerido	Cliente que realiza la venta.
branch_ulid	string	opcional	Sucursal.
source_type	string	opcional	Origen (morfo).
source_ulid	string	opcional	ULID del origen.
discount	numeric	opcional	Descuento (default 0).
tax	numeric	opcional	Impuesto (default 0).
currency	string	opcional	Moneda (default MXN).
meta	object	opcional	Metadatos adicionales.
items[]	array	requerido	Items: { type?, ulid?, description, unit_price, quantity, total }.

Respuesta: Venta con status=pending, paid_amount=0, balance=total

Products

clients/ProductsClients

Catálogo de productos por cliente con licencia de módulo.

GET/api/productsauth:sanctum + módulo products

Lista productos.

POST/api/productsauth:sanctum + módulo products

Crea un producto.

GET/api/products/{product}auth:sanctum + módulo products

Detalle de un producto.

PUT/api/products/{product}auth:sanctum + módulo products

Actualiza un producto.

DELETE/api/products/{product}auth:sanctum + módulo products

Elimina un producto.

Orders

clients/OrdersClients

Órdenes con código auto-generado (ORD-YYYYMMDD-XXXX).

GET/api/ordersauth:sanctum + licencia

Lista órdenes.

GET/api/orders/{ulid}auth:sanctum + licencia

Detalle de una orden.

POST/api/ordersauth:sanctum + licencia

Crea una orden.

Request body

Campo	Tipo	Req.	Descripción
ticket_ulid	string	opcional	Ticket asociado (exists:tickets).
code	string	opcional	Auto: ORD-YYYYMMDD-XXXX.
subtotal	numeric	opcional	Subtotal del pedido.
iva	numeric	opcional	IVA.
total	numeric	opcional	Total (default 0).
status	integer	opcional	Estado (default 1).

PATCH/api/orders/{ulid}auth:sanctum + licencia

Actualiza una orden.

DELETE/api/orders/{ulid}auth:sanctum + licencia

Elimina una orden.

Cashbox

clients/CashboxClients

Apertura de cajas por sucursal y registro de movimientos (entradas / salidas).

POST/api/cashboxesauth:sanctum

Abre una caja.

Request body

Campo	Tipo	Req.	Descripción
name	string	requerido	Nombre de la caja.
client_ulid	string	requerido	Cliente propietario.
branch_ulid	string	opcional	Sucursal (opcional).
opening_balance	numeric	opcional	Saldo inicial (min 0).

POST/api/cashboxes/{cashbox}/movementsauth:sanctum

Registra un movimiento en la caja.

Request body

Campo	Tipo	Req.	Descripción
type	enum	requerido	in \| out.
amount	numeric	requerido	Monto (min 0.01).
concept	string	requerido	Concepto del movimiento (máx. 255).

Invoices (CFDI)

clients/InvoicesClients

Facturación electrónica: genera, descarga (XML/PDF) y cancela comprobantes con motivo de cancelación.

POST/api/invoices

Genera una factura a partir de un pago (rate limit 5).

Request body

Campo	Tipo	Req.	Descripción
payment_id	ulid	requerido	Pago a facturar.
rfc	string	requerido	RFC del receptor (máx. 13).
name	string	requerido	Razón social del receptor (máx. 255).

POST/api/invoices/{ulid}/cancel

Cancela un CFDI.

Request body

Campo	Tipo	Req.	Descripción
reason	enum	requerido	Motivo de cancelación: 01, 02, 03 o 04.

GET/api/invoices/{ulid}/xml

Descarga el XML del comprobante.

GET/api/invoices/{ulid}/pdf

Descarga el PDF del comprobante.

POST/api/webhooks/pacPúblico

Webhook público del PAC para actualizar el timbrado (status / pac_response).

Wallets

clients/WalletsClients

Monederos por propietario (ULID) con historial de transacciones.

GET/api/v1/wallets/{ownerUlid}

Obtiene el wallet del propietario.

GET/api/v1/wallets/{ownerUlid}/transactions

Transacciones del wallet.

Clients (empresas)

admin/ClientsAdmin

Administración central de clientes / empresas (tenant) con datos fiscales.

GET/api/clientsauth:sanctum

Lista clientes / empresas.

GET/api/clients/{ulid}auth:sanctum

Detalle de un cliente.

POST/api/clientsauth:sanctum

Crea un cliente / empresa.

Request body

Campo	Tipo	Req.	Descripción
name	string	requerido	Nombre único.
legal_name	string	requerido	Razón social única.
email	email	requerido	Correo único.
type	enum	opcional	1 = persona física, 2 = moral.
rfc	string	opcional	RFC (máx. 13, único).
phone	string	opcional	Teléfono (máx. 20, único).
owner_user_ulid	string	opcional	Usuario propietario (exists:users).

PATCH/api/clients/{ulid}auth:sanctum

Actualiza un cliente.

DELETE/api/clients/{ulid}auth:sanctum

Elimina un cliente.

Plans

admin/PlansAdmin

Planes de suscripción disponibles para los clientes.

GET/api/plansauth:sanctum

Lista planes.

GET/api/plans/{ulid}auth:sanctum

Detalle de un plan.

POST/api/plansauth:sanctum

Crea un plan.

PATCH/api/plans/{ulid}auth:sanctum

Actualiza un plan.

DELETE/api/plans/{ulid}auth:sanctum

Elimina un plan.

Subscriptions

admin/SubscriptionsAdmin

Suscripciones de los clientes. La creación se gestiona vía pagos / registro / renovación.

GET/api/subscriptionsauth:sanctum

Lista suscripciones.

GET/api/subscriptions/{ulid}auth:sanctum

Detalle de una suscripción.

PATCH/api/subscriptions/{ulid}auth:sanctum

Actualiza una suscripción.

DELETE/api/subscriptions/{ulid}auth:sanctum

Elimina una suscripción.

Licences

admin/LicencesAdmin

Activación de licencias por llave; responde con una firma firmada.

POST/api/licences/{key}/activateauth:sanctum

Activa una licencia por llave.

Respuesta: HTTP 201 · licencia activada con firma

Referencia de la API

Auth

Register

QR Login

Seguridad (OTP)

Payments

Users

Roles

Permissions

IA

Chat

WhatsApp

Legal

Signatures

Files

Notifications

Document Generator

Settings

ApiSupport

Sales

Products

Orders

Cashbox

Invoices (CFDI)

Wallets

Clients (empresas)

Plans

Subscriptions

Licences