API Soporte LambiTenant

API REST para voicebot de soporte al cliente

https://devapi.lambicom.com/api/v1
Autenticacion Clientes Servicios Validaciones Tickets Catalogos Errores Flujos Voicebot
Autenticacion requerida

Todas las rutas requieren un Bearer Token en el header:
Authorization: Bearer {token}   Accept: application/json

Autenticacion

POST/auth/token
Genera un token de acceso. Rate limit: 5 req/min.
// Request
{
  "email": "voicebot@lambitenant.com",
  "password": "voicebot2026",
  "device_name": "voicebot"
}

// Response 200
{
  "success": true,
  "message": "Token generado exitosamente",
  "data": {
    "token": "1|abc123def456...",
    "type": "Bearer"
  }
}
GET/auth/me
Retorna info del usuario autenticado.
POST/auth/logout
Revoca el token actual.

Clientes

GET/clients/{client_number}
Buscar cliente por numero. Ej: CLI-10025
// Response 200
{
  "success": true,
  "message": "Consulta exitosa",
  "data": {
    "client_number": "CLI-10025",
    "full_name": "Juan Perez Lopez",
    "phone": "5512345678",
    "email": "juan@test.com",
    "status": "active"
  }
}
GET/clients/by-phone/{phone}
Buscar cliente por telefono. Ej: 5512345678
GET/clients/{client_number}/services
Listar todos los servicios contratados por el cliente.
// Response 200
{
  "success": true,
  "data": [
    {
      "service_number": "SRV-9001",
      "service_type": "internet",
      "service_name": "Internet Fibra 200MB",
      "status": "active",
      "address": "Av. Insurgentes Sur 1234, CDMX"
    }
  ]
}
GET/clients/{client_number}/tickets
Listar tickets de soporte del cliente.

Servicios

GET/services/{service_number}
Detalle completo de un servicio. Ej: SRV-9001
GET/services/{service_number}/status
Estatus con speak_text y bot_context para voicebot.
// Response 200
{
  "success": true,
  "data": {
    "service_number": "SRV-9001",
    "service_type": "internet",
    "service_name": "Internet Fibra 200MB",
    "status": "active",
    "status_label": "Servicio activo",
    "speak_text": "Tu servicio de Internet Fibra 200MB se encuentra activo y funcionando correctamente",
    "last_update": "2026-04-20 16:46:23",
    "bot_context": {
      "can_create_ticket": true,
      "can_transfer_agent": false,
      "requires_validation": false,
      "next_step": "ask_issue_type"
    }
  }
}

Estatus posibles

active
Servicio activo y funcionando
suspended
Suspendido por falta de pago
technical_failure
Falla tecnica detectada
pending_installation
Pendiente de instalacion
under_review
En revision tecnica
cancelled
Servicio cancelado

Campos de bot_context

CampoTipoDescripcion
can_create_ticketbooleanSi el bot puede ofrecer crear ticket
can_transfer_agentbooleanSi puede transferir a agente humano
requires_validationbooleanSi requiere validacion adicional
next_stepstringSiguiente accion sugerida para el bot
intent_hintstringIntent sugerido (billing_support, technical_support)

Validaciones

POST/validations/client
Validar identidad por numero de cliente + telefono.
// Request
{ "client_number": "CLI-10025", "phone": "5512345678" }

// Response 200 (valido)
{ "success": true, "data": { "valid": true, "client_id": 1, "message": "Cliente validado correctamente" } }

// Response 422 (invalido)
{ "success": false, "data": { "valid": false, "message": "No se pudo validar el cliente" } }
POST/validations/service
Validar que un servicio pertenezca al cliente.
// Request
{ "service_number": "SRV-9001", "client_number": "CLI-10025" }
POST/validations/otp
Validar codigo OTP. En pruebas el OTP valido es: 123456
// Request
{ "client_number": "CLI-10025", "otp_code": "123456" }

Tickets

POST/tickets
Crear un nuevo ticket de soporte.
// Request
{
  "client_number": "CLI-10025",
  "service_number": "SRV-9001",    // opcional
  "category": "internet_down",      // del catalogo
  "description": "Sin internet",    // opcional
  "priority": "high"                // low|medium|high|critical (default: medium)
}

// Response 201
{
  "success": true,
  "message": "Ticket creado exitosamente",
  "data": {
    "ticket_number": "TCK-20260421-001",
    "status": "open",
    "priority": "high",
    "created_at": "2026-04-21 00:15:46",
    "speak_text": "Tu ticket ha sido creado con el folio TCK-20260421-001. Te daremos seguimiento lo antes posible."
  }
}

Reglas de negocio

ReglaErrorCodigo
Servicio no pertenece al clienteEl servicio no pertenece al cliente422
Servicio canceladoNo se puede crear ticket para un servicio cancelado422
Ticket duplicadoYa existe un ticket abierto para este servicio409
GET/tickets/{ticket_number}
Consultar ticket por folio. Ej: TCK-20260420-001

Catalogos

GET/catalogs/service-types
Tipos de servicio: internet, telefonia, tv, iptv, pbx, cloud_pbx, enlace_dedicado, soporte_empresarial
GET/catalogs/service-statuses
Estatus: active, suspended, pending_installation, under_review, technical_failure, cancelled
GET/catalogs/ticket-categories
Categorias: internet_down, slow_internet, phone_no_tone, tv_no_signal, billing_issue, service_change, cancellation, installation, equipment_issue, general_inquiry

Respuestas de Error

CodigoMensajeCausa
401No autenticado. Se requiere un token valido.Sin token o token expirado
404Recurso no encontradoCliente, servicio o ticket no existe
422Error de validacionCampos faltantes o invalidos
429Demasiadas solicitudesRate limit excedido (60 req/min)

Flujos del Voicebot

Consultar estatus de servicio

1
Usuario dice: "Quiero saber el estado de mi internet"
2
Bot pide numero de cliente
3
POST /validations/client — valida identidad
4
GET /clients/{id}/services — lista servicios
5
GET /services/{id}/status — obtiene speak_text
6
Bot responde con el speak_text del servicio

Reportar falla

1
Usuario dice: "No tengo internet"
2
POST /validations/client — valida al cliente
3
GET /clients/{id}/tickets — verifica tickets abiertos
4
POST /tickets — crea ticket nuevo
5
Bot responde con el folio del ticket

Validacion de identidad

1
Usuario da numero de cliente + telefono
2
POST /validations/client
3
Si valid=true: continua flujo. Si valid=false: pide otro dato o transfiere.

Datos de Prueba

Usuario APIPasswordUso
admin@lambitenant.comadmin123Administracion
voicebot@lambitenant.comvoicebot2026Voicebot
ClienteNombreTelefonoEscenario
CLI-10025Juan Perez Lopez5512345678Servicios activos
CLI-10030Maria Garcia Hernandez5587654321Suspendido
CLI-10042Roberto Sanchez Martinez5598765432Falla tecnica
CLI-10055Ana Torres Ramirez5543219876Pendiente instalacion
CLI-10060Carlos Mendoza Diaz5567891234Cancelado
OTP de prueba

El codigo OTP valido para pruebas siempre es: 123456

API Soporte LambiTenant v1.0 | Laravel 13 | PostgreSQL 16 | PHP 8.4