{ "openapi": "3.1.0", "info": { "title": "SIPCOM API — Servicios y Repuestos Changan", "version": "0.1.0", "description": "Contrato propuesto para que NODO consulte clientes, vehículos y servicios en SIPCOM. Implementación mock alimentada por el CSV de vehículos vendidos. Solo lectura." }, "servers": [ { "url": "https://sipcom.nodoassist.com", "description": "Mock NODO (datos de muestra)" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Consulta NODO", "description": "Vista 360 en una sola llamada" }, { "name": "Cliente" }, { "name": "Vehículo" }, { "name": "Servicio" }, { "name": "Utilidades" } ], "paths": { "/api/v1/consulta": { "get": { "tags": [ "Consulta NODO" ], "summary": "Cliente + vehículos + resumen de servicios por teléfono, RIF, placa o VIN", "description": "Pensado para el agente de NODO: identifica al cliente con el dato que tenga a mano (p. ej. el número de WhatsApp) y devuelve todo lo necesario para responder.", "parameters": [ { "name": "telefono", "in": "query", "required": false, "description": "Acepta +58414..., 58414..., 0414... o 414...", "schema": { "type": "string" } }, { "name": "rif", "in": "query", "required": false, "description": "RIF del cliente, p. ej. V-12345678-9", "schema": { "type": "string" } }, { "name": "placa", "in": "query", "required": false, "description": "Placa del vehículo", "schema": { "type": "string" } }, { "name": "vin", "in": "query", "required": false, "description": "VIN del vehículo", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Consulta360" } } } } } }, "400": { "$ref": "#/components/responses/ErrorParametros" }, "401": { "$ref": "#/components/responses/NoAutorizado" }, "404": { "$ref": "#/components/responses/NoEncontrado" } } } }, "/api/v1/clientes": { "get": { "tags": [ "Cliente" ], "summary": "Listar / buscar clientes", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Texto libre en NOMBRE, RIF o CORREO", "schema": { "type": "string" } }, { "name": "rif", "in": "query", "required": false, "description": "RIF exacto", "schema": { "type": "string" } }, { "name": "telefono", "in": "query", "required": false, "description": "Teléfono (normalizado)", "schema": { "type": "string" } }, { "name": "ciudad", "in": "query", "required": false, "description": "Ciudad", "schema": { "type": "string" } }, { "name": "correo", "in": "query", "required": false, "description": "Correo exacto", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Página (1..n)", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página (máx. 200)", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cliente" } }, "meta": { "$ref": "#/components/schemas/Paginacion" } } } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" } } } }, "/api/v1/clientes/{rif}": { "get": { "tags": [ "Cliente" ], "summary": "Obtener cliente por RIF", "parameters": [ { "name": "rif", "in": "path", "required": true, "description": "RIF", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cliente" } } } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" }, "404": { "$ref": "#/components/responses/NoEncontrado" } } } }, "/api/v1/clientes/{rif}/vehiculos": { "get": { "tags": [ "Cliente" ], "summary": "Vehículos del cliente", "parameters": [ { "name": "rif", "in": "path", "required": true, "description": "RIF", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehiculo" } } } } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" }, "404": { "$ref": "#/components/responses/NoEncontrado" } } } }, "/api/v1/clientes/{rif}/servicios": { "get": { "tags": [ "Cliente" ], "summary": "Servicios del cliente", "parameters": [ { "name": "rif", "in": "path", "required": true, "description": "RIF", "schema": { "type": "string" } }, { "name": "tipo", "in": "query", "required": false, "description": "Falla | Mantenimiento", "schema": { "type": "string" } }, { "name": "clasificacion", "in": "query", "required": false, "description": "Particular | Garantía | Licencia | Interno | Paralizada", "schema": { "type": "string" } }, { "name": "estatus", "in": "query", "required": false, "description": "Estatus exacto, o \"abiertos\" / \"cerrados\"", "schema": { "type": "string" } }, { "name": "paralizado", "in": "query", "required": false, "description": "Sí | No", "schema": { "type": "string" } }, { "name": "concesionario", "in": "query", "required": false, "description": "Nombre (coincidencia parcial)", "schema": { "type": "string" } }, { "name": "desde", "in": "query", "required": false, "description": "FECHASERVICIO >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "hasta", "in": "query", "required": false, "description": "FECHASERVICIO <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "nrofactura", "in": "query", "required": false, "description": "Número de factura", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "required": false, "description": "cliente,vehiculo — reemplaza la relación por el objeto completo", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Página (1..n)", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página (máx. 200)", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Servicio" } }, "meta": { "$ref": "#/components/schemas/Paginacion" } } } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" }, "404": { "$ref": "#/components/responses/NoEncontrado" } } } }, "/api/v1/vehiculos": { "get": { "tags": [ "Vehículo" ], "summary": "Listar / buscar vehículos", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Texto libre en VIN, PLACA, MODELO o nombre del cliente", "schema": { "type": "string" } }, { "name": "vin", "in": "query", "required": false, "description": "VIN exacto", "schema": { "type": "string" } }, { "name": "placa", "in": "query", "required": false, "description": "Placa", "schema": { "type": "string" } }, { "name": "modelo", "in": "query", "required": false, "description": "Modelo", "schema": { "type": "string" } }, { "name": "anio", "in": "query", "required": false, "description": "Año", "schema": { "type": "integer" } }, { "name": "color", "in": "query", "required": false, "description": "Color", "schema": { "type": "string" } }, { "name": "rif", "in": "query", "required": false, "description": "RIF del propietario", "schema": { "type": "string" } }, { "name": "sin_placa", "in": "query", "required": false, "description": "true = solo vehículos sin placa asignada", "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "required": false, "description": "cliente", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Página (1..n)", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página (máx. 200)", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehiculo" } }, "meta": { "$ref": "#/components/schemas/Paginacion" } } } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" } } } }, "/api/v1/vehiculos/{id}": { "get": { "tags": [ "Vehículo" ], "summary": "Obtener vehículo por VIN o placa", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "VIN o placa", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "required": false, "description": "cliente", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehiculo" } } } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" }, "404": { "$ref": "#/components/responses/NoEncontrado" } } } }, "/api/v1/vehiculos/{id}/servicios": { "get": { "tags": [ "Vehículo" ], "summary": "Historial de servicios del vehículo", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "VIN o placa", "schema": { "type": "string" } }, { "name": "tipo", "in": "query", "required": false, "description": "Falla | Mantenimiento", "schema": { "type": "string" } }, { "name": "clasificacion", "in": "query", "required": false, "description": "Particular | Garantía | Licencia | Interno | Paralizada", "schema": { "type": "string" } }, { "name": "estatus", "in": "query", "required": false, "description": "Estatus exacto, o \"abiertos\" / \"cerrados\"", "schema": { "type": "string" } }, { "name": "paralizado", "in": "query", "required": false, "description": "Sí | No", "schema": { "type": "string" } }, { "name": "concesionario", "in": "query", "required": false, "description": "Nombre (coincidencia parcial)", "schema": { "type": "string" } }, { "name": "desde", "in": "query", "required": false, "description": "FECHASERVICIO >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "hasta", "in": "query", "required": false, "description": "FECHASERVICIO <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "nrofactura", "in": "query", "required": false, "description": "Número de factura", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "required": false, "description": "cliente,vehiculo — reemplaza la relación por el objeto completo", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Página (1..n)", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página (máx. 200)", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Servicio" } }, "meta": { "$ref": "#/components/schemas/Paginacion" } } } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" }, "404": { "$ref": "#/components/responses/NoEncontrado" } } } }, "/api/v1/servicios": { "get": { "tags": [ "Servicio" ], "summary": "Listar / filtrar servicios (más recientes primero)", "parameters": [ { "name": "vin", "in": "query", "required": false, "description": "VIN", "schema": { "type": "string" } }, { "name": "placa", "in": "query", "required": false, "description": "Placa", "schema": { "type": "string" } }, { "name": "rif", "in": "query", "required": false, "description": "RIF del cliente", "schema": { "type": "string" } }, { "name": "tipo", "in": "query", "required": false, "description": "Falla | Mantenimiento", "schema": { "type": "string" } }, { "name": "clasificacion", "in": "query", "required": false, "description": "Particular | Garantía | Licencia | Interno | Paralizada", "schema": { "type": "string" } }, { "name": "estatus", "in": "query", "required": false, "description": "Estatus exacto, o \"abiertos\" / \"cerrados\"", "schema": { "type": "string" } }, { "name": "paralizado", "in": "query", "required": false, "description": "Sí | No", "schema": { "type": "string" } }, { "name": "concesionario", "in": "query", "required": false, "description": "Nombre (coincidencia parcial)", "schema": { "type": "string" } }, { "name": "desde", "in": "query", "required": false, "description": "FECHASERVICIO >= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "hasta", "in": "query", "required": false, "description": "FECHASERVICIO <= (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "nrofactura", "in": "query", "required": false, "description": "Número de factura", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "required": false, "description": "cliente,vehiculo — reemplaza la relación por el objeto completo", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Página (1..n)", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página (máx. 200)", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Servicio" } }, "meta": { "$ref": "#/components/schemas/Paginacion" } } } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" } } } }, "/api/v1/servicios/{id}": { "get": { "tags": [ "Servicio" ], "summary": "Obtener servicio por NROSERVICIO o IDINTERNO", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NROSERVICIO (OS-000123) o IDINTERNO", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "required": false, "description": "cliente,vehiculo", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Servicio" } } } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" }, "404": { "$ref": "#/components/responses/NoEncontrado" } } } }, "/api/v1/catalogos": { "get": { "tags": [ "Utilidades" ], "summary": "Valores válidos para filtros", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" } } } }, "/api/v1/estadisticas": { "get": { "tags": [ "Utilidades" ], "summary": "Conteos agregados", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/NoAutorizado" } } } }, "/api/v1/health": { "get": { "tags": [ "Utilidades" ], "summary": "Estado del servicio (sin API key)", "security": [], "responses": { "200": { "description": "OK" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Solicitar la key al equipo de NODO" } }, "responses": { "NoAutorizado": { "description": "API key ausente o inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NoEncontrado": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ErrorParametros": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Cliente": { "type": "object", "required": [ "RIF", "NOMBRE" ], "properties": { "RIF": { "type": "string", "description": "Identificador fiscal", "example": "V-12345678-9" }, "NOMBRE": { "type": "string", "description": "Nombre o razón social" }, "DIRECCION": { "type": "string", "description": "Dirección física" }, "CIUDAD": { "type": "string" }, "TELEFONO": { "type": "string", "description": "Formato E.164", "example": "+584141234567" }, "CORREO": { "type": "string", "format": "email" } } }, "Vehiculo": { "type": "object", "required": [ "VIN", "MODELO", "CLIENTE" ], "properties": { "VIN": { "type": "string", "description": "Identificador único del vehículo", "example": "LS5A3DKR3SA964911" }, "SERIALMOTOR": { "type": "string" }, "PLACA": { "type": [ "string", "null" ], "description": "null si aún no tiene placa" }, "MODELO": { "type": "string", "example": "CS35 Plus" }, "COLOR": { "type": "string" }, "ANIO": { "type": "integer", "example": 2025 }, "CLIENTE": { "description": "RIF del propietario (u objeto Cliente con expand=cliente)", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Cliente" } ] }, "FECHACOMPRA": { "type": "string", "format": "date", "description": "Extensión: fecha de venta" }, "ESTADO": { "type": "string", "description": "Extensión: estado de la venta (entregado)" } } }, "Servicio": { "type": "object", "required": [ "IDINTERNO", "NROSERVICIO", "FECHASERVICIO", "TIPO", "ESTATUS", "VEHICULO", "CLIENTE" ], "properties": { "IDINTERNO": { "type": "integer" }, "NROSERVICIO": { "type": "string", "example": "OS-000123" }, "FECHASERVICIO": { "type": "string", "format": "date" }, "TIPO": { "type": "string", "enum": [ "Falla", "Mantenimiento" ] }, "CLASIFICACION": { "type": "string", "enum": [ "Particular", "Garantía", "Licencia", "Interno", "Paralizada" ] }, "ESTATUS": { "type": "string", "enum": [ "Recibido", "En diagnóstico", "Esperando repuesto", "En reparación", "Listo para entrega", "Entregado", "Facturado" ] }, "REPORTECLIENTE": { "type": "string" }, "REPORTETECNICO": { "type": "string" }, "DIAGNOSTICO": { "type": [ "string", "null" ] }, "CONCESIONARIO": { "type": "string" }, "VEHICULO": { "description": "VIN (u objeto Vehiculo con expand=vehiculo)", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Vehiculo" } ] }, "KM": { "type": "integer" }, "PARALIZADO": { "type": "string", "enum": [ "Sí", "No" ] }, "CLIENTE": { "description": "RIF (u objeto Cliente con expand=cliente)", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Cliente" } ] }, "FECHAFACTURA": { "type": [ "string", "null" ], "format": "date" }, "NROFACTURA": { "type": [ "string", "null" ] } } }, "Consulta360": { "type": "object", "properties": { "cliente": { "$ref": "#/components/schemas/Cliente" }, "vehiculos": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Vehiculo" }, { "type": "object", "properties": { "servicios": { "type": "object", "properties": { "total": { "type": "integer" }, "abiertos": { "type": "integer" }, "paralizados": { "type": "integer" }, "ultimo_servicio": { "$ref": "#/components/schemas/Servicio" }, "ultimo_mantenimiento": { "type": [ "object", "null" ] } } }, "servicios_abiertos": { "type": "array", "items": { "$ref": "#/components/schemas/Servicio" } } } } ] } } } }, "Paginacion": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "pages": { "type": "integer" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }