openapi: 3.0.3 info: title: API Merchants Finantial description: Integración de puntos de venta y servicios merchant con Seguridad JWT. version: 1.0.0 contact: name: Soporte de Integración servers: - url: https://dev.api.spuntodeventa.com description: Sandbox - Entorno de pruebas para desarrollo e integración - url: https://api.spuntodeventa.com description: Production - Entorno de producción paths: /api/v1/merchants: post: summary: Registrarte como comercio description: >- Endpoint público para registro (Onboarding). Crea un nuevo merchant y devuelve su ID. operationId: createMerchant tags: - Merchants requestBody: required: true content: application/json: schema: type: object description: Datos para registrar un nuevo comercio. required: - legalName - taxId - email - password properties: legalName: type: string description: Nombre legal del comercio. example: Inversiones Spidi C.A. taxId: type: string description: RIF o identificación fiscal del comercio. example: J-12345678-0 email: type: string format: email description: Dirección de correo electrónico. example: admin@comercio.com password: type: string nullable: false description: Contraseña de acceso del usuario. phone: type: string description: Número de teléfono. example: '+584141234567' address: type: string description: Dirección del comercio. example: Av. Principal, Edif. Central responses: '201': description: Comercio creado. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Comercio Recuperado detail: example: >- Los detalles del comercio han sido obtenidos exitosamente de la base de datos. data: type: object properties: id: description: Identificador único en formato UUID del comercio type: string format: uuid example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 legalName: type: string description: Nombre legal del comercio. example: Inversiones Spidi C.A. status: type: string enum: - ACTIVE - PENDING example: ACTIVE createdAt: type: string format: date-time description: Fecha y hora de creación en formato ISO 8601. '400': description: Datos inválidos. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/merchants/auth/login: post: summary: Iniciar Sesión como comercio description: >- Te permite intercambiar tus credenciales como por un token de acceso (JWT). operationId: loginMerchant security: [] tags: - Merchants requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email description: Dirección de correo electrónico. example: admin@comercio.com password: type: string nullable: false description: Contraseña de acceso del usuario. example: email: '[EMAIL_ADDRESS]' password: '[PASSWORD]' responses: '200': description: Login exitoso. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Autenticación Exitosa detail: example: >- Se ha generado el token de acceso correctamente y el usuario ha sido autenticado. data: type: object properties: accessToken: type: string description: Token JWT para usar en los headers Authorization. example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... tokenType: type: string description: Tipo de token de autenticación. example: Bearer expiresIn: type: integer description: Tiempo en segundos antes de expirar. example: 3600 merchantId: description: Identificador único en formato UUID del comercio type: string format: uuid example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 '401': description: Credenciales inválidas content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. example: title: Credenciales inválidas detail: 'Invalid Credentials ' /api/v1/merchants/{merchantId}/pos-terminals/{serialNumber}/pairing: post: summary: Generar OTP para Pairing description: >- Solicita vincular un sistema terminal con el Serial de Hardware y genera un código de activación (OTP). tags: - Merchants security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: serial: type: string description: Serial de Hardware del dispositivo POS. required: - serial responses: '200': description: Código de activación (OTP) generado exitosamente. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: OTP Generado detail: example: >- El código de activación ha sido generado exitosamente para el terminal solicitado. data: type: object properties: code: type: string description: >- Código de activación (OTP) generado para el dispositivo POS. required: - code '400': description: Error en la petición o terminal ya vinculada. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/pos-terminals/{serialNumber}/pairing/activate: post: summary: Activar dispositivo POS description: >- Valida el código OTP ingresado en el punto de venta y genera el Secret Key del dispositivo. tags: - Terminales requestBody: required: true content: application/json: schema: type: object properties: serial: type: string description: Serial de Hardware del dispositivo POS. code: type: string description: Código de activación (OTP) generado en la fase de Pairing. required: - serial - code responses: '200': description: Dispositivo activado exitosamente. Retorna la Secret Key. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Dispositivo Activado detail: example: >- La vinculación ha sido completada y el dispositivo ha recuperado su Secret Key. data: type: object properties: secret_key: type: string description: >- Clave secreta generada (ej. SHA-256) en el servidor vinculada al Serial, para autenticación mediante HMAC. required: - secret_key '400': description: Error de validación o OTP incorrecto. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/merchants/{merchantId}/transactions: post: summary: Solicitar Pago description: >- Crea una transacción en el sistema. Nótese que las transacciones deben ser confirmadas; el hecho de que esté creada no significa que esté confirmada. operationId: createTransaction security: - BearerAuth: [] tags: - Merchants parameters: - name: merchantId in: path required: true schema: description: Identificador único en formato UUID del comercio type: string format: uuid example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 requestBody: required: true content: application/json: schema: type: object required: - amountReference - currency - serial - orderId properties: orderId: type: string format: uuid description: Identificador único de la orden generado por el comercio. example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. allowAmountChange: type: boolean description: Si es true, permite editar el monto en el POS. default: false clientIdentification: type: string description: Cédula o RIF del cliente. example: V14143800 terminalSerial: type: string description: Serial del terminal físico. example: '98202003219630' deeplinkConfig: type: object description: >- Configuración para el retorno a la app (Deep Linking). Estos campos se usan cuando la app merchant se ubica en el punto, pues al terminar la transacción de compra, el app financiero va a abrir la app en la pantalla específica esperada por parte del merchant. properties: returnPackage: type: string example: com.tuapp.kiosco returnActivity: type: string example: com.tuapp.kiosco.PaymentResultActivity responses: '201': description: Transacción creada exitosamente. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Operación Procesada detail: example: >- La transacción ha sido procesada y se ha devuelto el estado actual de la operación. data: type: object properties: id: type: string format: uuid description: Identificador único en formato UUID. status: type: string description: >- Indica el status del pago. ```PENDING```: la orden fue creada y el POS aún no ha confirmado el pago. ```CANCELED```: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). ```PAID```: el POS confirmó exitosamente el pago. ```VOID_PENDING```: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. ```VOIDED```: el POS confirmó la anulación del pago. enum: - PENDING - CANCELED - PAID - VOID_PENDING - VOIDED example: PAID amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' confirmData: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 cancellationDara: type: object properties: commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). '400': description: Datos inválidos. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. '401': description: No autorizado (Token faltante). '403': description: Prohibido (El token no pertenece a este merchant_id). /api/v1/merchants/{merchantId}/transactions/{orderId}: get: summary: Consultar pago description: >- Consulta información sobre una transacción por medio de su ```id``` incluyendo el estado actual operationId: getTransaction security: - BearerAuth: [] tags: - Merchants parameters: - name: merchantId in: path required: true schema: description: Identificador único en formato UUID del comercio type: string format: uuid example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 - name: orderId in: path required: true schema: type: string responses: '200': description: Detalle de la transacción. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Operación Procesada detail: example: >- La transacción ha sido procesada y se ha devuelto el estado actual de la operación. data: type: object properties: id: type: string format: uuid description: Identificador único en formato UUID. status: type: string description: >- Indica el status del pago. ```PENDING```: la orden fue creada y el POS aún no ha confirmado el pago. ```CANCELED```: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). ```PAID```: el POS confirmó exitosamente el pago. ```VOID_PENDING```: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. ```VOIDED```: el POS confirmó la anulación del pago. enum: - PENDING - CANCELED - PAID - VOID_PENDING - VOIDED example: PAID amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' confirmData: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 cancellationDara: type: object properties: commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). '404': description: Transacción no encontrada. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/merchants/{merchantId}/transactions/{orderId}/cancellation: post: summary: Anular Pago description: >- Solicita la cancelación o anulación de una transacción. Si la transacción está en estado PENDING (no confirmada por el POS), pasa a CANCELED. Si la transacción está en estado PAID (ya confirmada por el POS), pasa a VOID_PENDING a la espera de la confirmación de anulación por parte del POS. operationId: voidTransaction security: - BearerAuth: [] tags: - Merchants parameters: - name: merchantId in: path required: true schema: description: Identificador único en formato UUID del comercio type: string format: uuid example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 - name: orderId in: path required: true schema: type: string responses: '200': description: Transacción anulada. content: application/json: schema: type: object nullable: true description: >- Detalles del éxito. Estándar basado en la estructura de 'Problem Details' (RFC 9457) para estandarizar las respuestas exitosas en toda la arquitectura de microservicios. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen (ej. 200, 201). minimum: 200 maximum: 299 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de éxito. detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del éxito. data: description: >- Contenedor de información que puede almacenar un objeto único o una lista de objetos. oneOf: - type: object - type: array items: type: object '409': description: No se puede anular. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/pos-terminals/{serialNumber}/transactions: get: summary: Listar pagos del POS description: Listar pagos del POS operationId: getTransactionsByTerminalSerial security: - POSSignature: [] tags: - Terminales parameters: - name: serialNumber in: path required: true schema: type: string description: Serial del terminal físico. example: '98202003219630' description: Identificador / Serial del terminal. - name: status in: query required: false style: deepObject explode: true schema: type: object additionalProperties: type: string description: >- Filtro dinámico (LHS Brackets) para filtrar transacciones por estado. Ej: `?status=PENDING` requestBody: required: true content: application/json: schema: type: object required: - amountReference - currency - serial - orderId properties: orderId: type: string format: uuid description: Identificador único de la orden generado por el comercio. example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. allowAmountChange: type: boolean description: Si es true, permite editar el monto en el POS. default: false clientIdentification: type: string description: Cédula o RIF del cliente. example: V14143800 terminalSerial: type: string description: Serial del terminal físico. example: '98202003219630' deeplinkConfig: type: object description: >- Configuración para el retorno a la app (Deep Linking). Estos campos se usan cuando la app merchant se ubica en el punto, pues al terminar la transacción de compra, el app financiero va a abrir la app en la pantalla específica esperada por parte del merchant. properties: returnPackage: type: string example: com.tuapp.kiosco returnActivity: type: string example: com.tuapp.kiosco.PaymentResultActivity responses: '200': description: Lista de transacciones recuperada exitosamente. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un arreglo de objetos. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: array description: Representa una colección de entidades de negocio. items: type: object - type: object properties: title: example: Listado de Transacciones detail: example: >- Se ha recuperado el historial de transacciones del terminal solicitado. data: type: array items: type: object properties: id: type: string format: uuid description: Identificador único en formato UUID. status: type: string description: >- Indica el status del pago. ```PENDING```: la orden fue creada y el POS aún no ha confirmado el pago. ```CANCELED```: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). ```PAID```: el POS confirmó exitosamente el pago. ```VOID_PENDING```: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. ```VOIDED```: el POS confirmó la anulación del pago. enum: - PENDING - CANCELED - PAID - VOID_PENDING - VOIDED example: PAID amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' confirmData: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 cancellationDara: type: object properties: commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). '400': description: Datos inválidos. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. example: title: Datos Inválidos detail: El query param especificado no es válido. '401': description: No autorizado (Token faltante). content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. example: title: No Autorizado detail: Token faltante en las cabeceras. '403': description: Prohibido (El token no pertenece a este serialNumber o merchant_id). content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. example: title: Prohibido detail: >- El token provisto no posee permisos de acceso sobre este terminal. /api/v1/pos-terminals/{serialNumber}/transactions/{orderId}: get: summary: Consultar el estado de un pago desde el POS description: >- Consulta información sobre una transacción por medio de su ```id``` incluyendo el estado actual operationId: getTransaction security: - POSSignature: [] tags: - Terminales parameters: - name: serialNumber in: path required: true schema: type: string description: Serial del POS example: '98202003219630' - name: orderId in: path required: true schema: type: string responses: '200': description: Detalle de la transacción. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Operación Procesada detail: example: >- La transacción ha sido procesada y se ha devuelto el estado actual de la operación. data: type: object properties: id: type: string format: uuid description: Identificador único en formato UUID. status: type: string description: >- Indica el status del pago. ```PENDING```: la orden fue creada y el POS aún no ha confirmado el pago. ```CANCELED```: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). ```PAID```: el POS confirmó exitosamente el pago. ```VOID_PENDING```: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. ```VOIDED```: el POS confirmó la anulación del pago. enum: - PENDING - CANCELED - PAID - VOID_PENDING - VOIDED example: PAID amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' confirmData: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 cancellationDara: type: object properties: commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). '404': description: Transacción no encontrada. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/pos-terminals/{serialNumber}/transactions/{orderId}/commit: post: summary: Confirmar Pago description: >- Pasa una transacción que estaba en estado PENDING a PAID. Adicionalmente, si la orden fue cancelada (estado CANCELED) antes de la confirmación del POS, emitir esta llamada sobrescribirá la cancelación y confirmará el pago con estado PAID. operationId: commitTransaction security: - POSSignature: [] tags: - Terminales parameters: - name: serialNumber in: path required: true schema: type: string description: Serial del terminal físico. example: '98202003219630' - name: orderId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 responses: '200': description: Transacción confirmada. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Operación Procesada detail: example: >- La transacción ha sido procesada y se ha devuelto el estado actual de la operación. data: type: object properties: id: type: string format: uuid description: Identificador único en formato UUID. status: type: string description: >- Indica el status del pago. ```PENDING```: la orden fue creada y el POS aún no ha confirmado el pago. ```CANCELED```: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). ```PAID```: el POS confirmó exitosamente el pago. ```VOID_PENDING```: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. ```VOIDED```: el POS confirmó la anulación del pago. enum: - PENDING - CANCELED - PAID - VOID_PENDING - VOIDED example: PAID amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' confirmData: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 cancellationDara: type: object properties: commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). '409': description: >- Conflicto o error al confirmar. Sucede si la orden ya fue procesada, liquidada o finalizada. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/pos-terminals/{serialNumber}/transactions/{orderId}/cancellation/commit: post: summary: Confirmar Anulación description: Confirma la ejecución de la anulación. operationId: commitCancellation security: - POSSignature: [] tags: - Terminales parameters: - name: serialNumber in: path required: true schema: type: string description: Serial del terminal físico. example: '98202003219630' - name: orderId in: path required: true schema: type: string responses: '200': description: Anulación confirmada. content: application/json: schema: type: object nullable: true description: >- Detalles del éxito. Estándar basado en la estructura de 'Problem Details' (RFC 9457) para estandarizar las respuestas exitosas en toda la arquitectura de microservicios. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen (ej. 200, 201). minimum: 200 maximum: 299 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de éxito. detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del éxito. data: description: >- Contenedor de información que puede almacenar un objeto único o una lista de objetos. oneOf: - type: object - type: array items: type: object '409': description: Error al confirmar anulación. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/merchants/{merchantId}/pos-terminals/{serialNumber}/settlements: get: summary: Listar Cierres de Lote de Terminal description: >- Obtiene el historial de cierres de lote del terminal especificado para el comercio. operationId: listSettlementsByMerchantAndTerminal security: - BearerAuth: [] tags: - Merchants parameters: - name: merchantId in: path required: true schema: description: Identificador único en formato UUID del comercio type: string format: uuid example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 - name: serialNumber in: path required: true schema: type: string description: Serial del terminal físico. example: '98202003219630' - name: page in: query required: false schema: type: integer default: 1 description: Número asociado a la página solicitada (Indizado desde 1). - name: size in: query required: false schema: type: integer default: 20 description: Cantidad máxima de elementos por página. - name: sort in: query required: false schema: type: string default: '-closedAt' description: >- Criterio de ordenamiento. Usar el prefijo `-` para orden descendente. Ejemplo: `-closedAt` o `+name`. responses: '200': description: Lista de cierres recuperada exitosamente. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un arreglo de objetos. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: array description: Representa una colección de entidades de negocio. items: type: object - type: object properties: title: example: Listado de Cierres detail: example: >- Se ha recuperado el historial de cierres de lote del terminal. data: type: array items: type: object properties: batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 transactionCount: type: integer example: 12 closedAt: type: string format: date-time example: '2023-04-04T15:26:51.187Z' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. terminal: type: object properties: id: type: string example: TMS ID affiliateCode: type: string example: '0010800050' number: type: string description: Numero de terminal. example: '98202003219630' serial: type: string description: Serial del terminal físico. example: '98202003219630' bankId: type: string example: '3' bankCode: type: string nullable: false description: >- Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). debitBatch: type: string description: Falta ser definido por Carlos Cardenas '400': description: Datos de petición inválidos. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/pos-terminals/{serialNumber}/settlements: get: summary: Listar Cierres description: Obtiene el historial de cierres de lote. operationId: listSettlements security: - POSSignature: [] tags: - Terminales parameters: - name: serialNumber in: path required: true schema: type: string description: Serial del terminal físico. example: '98202003219630' - name: page in: query required: false schema: type: integer default: 1 description: Número asociado a la página solicitada (Indizado desde 1). - name: size in: query required: false schema: type: integer default: 20 description: Cantidad máxima de elementos por página. - name: sort in: query required: false schema: type: string default: '-closedAt' description: >- Criterio de ordenamiento. Usar el prefijo `-` para orden descendente. Ejemplo: `-closedAt` o `+name`. responses: '200': description: Lista de cierres. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un arreglo de objetos. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: array description: Representa una colección de entidades de negocio. items: type: object - type: object properties: title: example: Listado de Cierres detail: example: >- Se ha recuperado el historial de cierres de lote del terminal. data: type: array items: type: object properties: batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 transactionCount: type: integer example: 12 closedAt: type: string format: date-time example: '2023-04-04T15:26:51.187Z' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. terminal: type: object properties: id: type: string example: TMS ID affiliateCode: type: string example: '0010800050' number: type: string description: Numero de terminal. example: '98202003219630' serial: type: string description: Serial del terminal físico. example: '98202003219630' bankId: type: string example: '3' bankCode: type: string nullable: false description: >- Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). debitBatch: type: string description: Falta ser definido por Carlos Cardenas post: summary: Crear Cierre description: Con este endpoint el pos notifica el cierre del lote. operationId: createSettlement security: - POSSignature: [] tags: - Terminales parameters: - name: serialNumber in: path required: true schema: type: string description: Serial del terminal físico. example: '98202003219630' requestBody: required: true content: application/json: schema: type: object properties: batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 transactionCount: type: integer example: 12 closedAt: type: string format: date-time example: '2023-04-04T15:26:51.187Z' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. terminal: type: object properties: id: type: string example: TMS ID affiliateCode: type: string example: '0010800050' number: type: string description: Numero de terminal. example: '98202003219630' serial: type: string description: Serial del terminal físico. example: '98202003219630' bankId: type: string example: '3' bankCode: type: string nullable: false description: >- Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). debitBatch: type: string description: Falta ser definido por Carlos Cardenas responses: '200': description: Cierre ejecutado exitosamente. content: application/json: schema: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Cierre de Lote detail: example: Detalles del cierre de lote solicitado. data: type: object properties: batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 transactionCount: type: integer example: 12 closedAt: type: string format: date-time example: '2023-04-04T15:26:51.187Z' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. terminal: type: object properties: id: type: string example: TMS ID affiliateCode: type: string example: '0010800050' number: type: string description: Numero de terminal. example: '98202003219630' serial: type: string description: Serial del terminal físico. example: '98202003219630' bankId: type: string example: '3' bankCode: type: string nullable: false description: >- Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). debitBatch: type: string description: Falta ser definido por Carlos Cardenas '400': description: Error en la solicitud de cierre. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. /api/v1/pos-terminals/{serialNumber}/settlements/{batchNumber}: get: summary: Consultar Cierre description: Obtiene la información detallada de un cierre específico. operationId: getSettlementDetail security: - BearerAuth: [] tags: - Terminales parameters: - name: serialNumber in: path required: true schema: type: string description: Serial del terminal físico. example: '98202003219630' - name: batchNumber in: path required: true schema: type: integer responses: '200': description: Detalle completo del cierre. content: application/json: schema: type: object properties: batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 transactionCount: type: integer example: 12 closedAt: type: string format: date-time example: '2023-04-04T15:26:51.187Z' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. terminal: type: object properties: id: type: string example: TMS ID affiliateCode: type: string example: '0010800050' number: type: string description: Numero de terminal. example: '98202003219630' serial: type: string description: Serial del terminal físico. example: '98202003219630' bankId: type: string example: '3' bankCode: type: string nullable: false description: >- Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). debitBatch: type: string description: Falta ser definido por Carlos Cardenas '404': description: Lote no encontrado. content: application/json: schema: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: >- Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: >- Puntero al campo específico en el cuerpo de la solicitud. components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Requiere el uso de el token obtenido en /auth/login BasicAuth: type: http scheme: basic description: >- Requiere el uso de las credenciales (Usuario/Contraseña) codificadas en Base64 POSSignature: type: apiKey in: header name: x-pos-signature description: >- Requiere el uso de la firma HMAC para verificar la autenticidad de la solicitud schemas: legalName: type: string description: Nombre legal del comercio. example: Inversiones Spidi C.A. taxId: type: string description: RIF o identificación fiscal del comercio. example: J-12345678-0 email: type: string format: email description: Dirección de correo electrónico. example: admin@comercio.com password: type: string nullable: false description: Contraseña de acceso del usuario. phone: type: string description: Número de teléfono. example: '+584141234567' address: type: string description: Dirección del comercio. example: Av. Principal, Edif. Central MerchantRequest: type: object description: Datos para registrar un nuevo comercio. required: - legalName - taxId - email - password properties: legalName: type: string description: Nombre legal del comercio. example: Inversiones Spidi C.A. taxId: type: string description: RIF o identificación fiscal del comercio. example: J-12345678-0 email: type: string format: email description: Dirección de correo electrónico. example: admin@comercio.com password: type: string nullable: false description: Contraseña de acceso del usuario. phone: type: string description: Número de teléfono. example: '+584141234567' address: type: string description: Dirección del comercio. example: Av. Principal, Edif. Central successDetailsObject: type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. merchant_id: description: Identificador único en formato UUID del comercio type: string format: uuid example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 createdAt: type: string format: date-time description: Fecha y hora de creación en formato ISO 8601. MerchantResponse: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Comercio Recuperado detail: example: >- Los detalles del comercio han sido obtenidos exitosamente de la base de datos. data: type: object properties: id: description: Identificador único en formato UUID del comercio type: string format: uuid example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 legalName: type: string description: Nombre legal del comercio. example: Inversiones Spidi C.A. status: type: string enum: - ACTIVE - PENDING example: ACTIVE createdAt: type: string format: date-time description: Fecha y hora de creación en formato ISO 8601. problemDetails: type: object nullable: true description: >- Detalles del problema. Implementación del estándar RFC 9457 extendido para incluir lista de errores detallados y soporte de retrocompatibilidad multiformato. required: - title properties: status: type: integer description: El código de estado HTTP generado por el servidor de origen. minimum: 100 maximum: 599 title: type: string description: Un resumen breve y legible por humanos sobre el tipo de problema. type: type: string format: uri-reference description: Una referencia URI que identifica el tipo de problema. default: about:blank detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del problema. message: deprecated: true oneOf: - type: string example: El monto es inválido. - type: array items: type: string example: - El monto debe ser numérico - El monto no puede ser negativo instance: type: string format: uri-reference description: >- Una referencia URI que identifica la ocurrencia específica del problema. errors: type: array description: >- Lista de errores específicos de validación con punteros JSON (RFC 6901). items: type: object properties: detail: type: string description: Descripción técnica del error. pointer: type: string description: Puntero al campo específico en el cuerpo de la solicitud. accessToken: type: string description: Token JWT para usar en los headers Authorization. example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... tokenType: type: string description: Tipo de token de autenticación. example: Bearer expiresIn: type: integer description: Tiempo en segundos antes de expirar. example: 3600 LoginResponse: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Autenticación Exitosa detail: example: >- Se ha generado el token de acceso correctamente y el usuario ha sido autenticado. data: type: object properties: accessToken: type: string description: Token JWT para usar en los headers Authorization. example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... tokenType: type: string description: Tipo de token de autenticación. example: Bearer expiresIn: type: integer description: Tiempo en segundos antes de expirar. example: 3600 merchantId: description: Identificador único en formato UUID del comercio type: string format: uuid example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 PairingRequest: type: object properties: serial: type: string description: Serial de Hardware del dispositivo POS. required: - serial PairingResponse: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: OTP Generado detail: example: >- El código de activación ha sido generado exitosamente para el terminal solicitado. data: type: object properties: code: type: string description: Código de activación (OTP) generado para el dispositivo POS. required: - code PairingActivateRequest: type: object properties: serial: type: string description: Serial de Hardware del dispositivo POS. code: type: string description: Código de activación (OTP) generado en la fase de Pairing. required: - serial - code PairingActivateResponse: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Dispositivo Activado detail: example: >- La vinculación ha sido completada y el dispositivo ha recuperado su Secret Key. data: type: object properties: secret_key: type: string description: >- Clave secreta generada (ej. SHA-256) en el servidor vinculada al Serial, para autenticación mediante HMAC. required: - secret_key orderId: type: string format: uuid description: Identificador único de la orden generado por el comercio. example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. allowAmountChange: type: boolean description: Si es true, permite editar el monto en el POS. default: false clientIdentification: type: string description: Cédula o RIF del cliente. example: V14143800 terminal_serial: type: string description: Serial del terminal físico. example: '98202003219630' deeplinkConfig: type: object description: >- Configuración para el retorno a la app (Deep Linking). Estos campos se usan cuando la app merchant se ubica en el punto, pues al terminar la transacción de compra, el app financiero va a abrir la app en la pantalla específica esperada por parte del merchant. properties: returnPackage: type: string example: com.tuapp.kiosco returnActivity: type: string example: com.tuapp.kiosco.PaymentResultActivity TransactionRequest: type: object required: - amountReference - currency - serial - orderId properties: orderId: type: string format: uuid description: Identificador único de la orden generado por el comercio. example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90 amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. allowAmountChange: type: boolean description: Si es true, permite editar el monto en el POS. default: false clientIdentification: type: string description: Cédula o RIF del cliente. example: V14143800 terminalSerial: type: string description: Serial del terminal físico. example: '98202003219630' deeplinkConfig: type: object description: >- Configuración para el retorno a la app (Deep Linking). Estos campos se usan cuando la app merchant se ubica en el punto, pues al terminar la transacción de compra, el app financiero va a abrir la app en la pantalla específica esperada por parte del merchant. properties: returnPackage: type: string example: com.tuapp.kiosco returnActivity: type: string example: com.tuapp.kiosco.PaymentResultActivity id: type: string format: uuid description: Identificador único en formato UUID. paymentMerchant_status: type: string description: >- Indica el status del pago. ```PENDING```: la orden fue creada y el POS aún no ha confirmado el pago. ```CANCELED```: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). ```PAID```: el POS confirmó exitosamente el pago. ```VOID_PENDING```: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. ```VOIDED```: el POS confirmó la anulación del pago. enum: - PENDING - CANCELED - PAID - VOID_PENDING - VOIDED example: PAID commitAt: type: string nullable: false format: date-time description: Fecha y hora de la confirmacion de la operacion (ISO 8601). terminal_number: type: string description: Numero de terminal. example: '98202003219630' posBatchId: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 confirmData: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 TransactionEntity: type: object properties: id: type: string format: uuid description: Identificador único en formato UUID. status: type: string description: >- Indica el status del pago. ```PENDING```: la orden fue creada y el POS aún no ha confirmado el pago. ```CANCELED```: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). ```PAID```: el POS confirmó exitosamente el pago. ```VOID_PENDING```: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. ```VOIDED```: el POS confirmó la anulación del pago. enum: - PENDING - CANCELED - PAID - VOID_PENDING - VOIDED example: PAID amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' confirmData: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 cancellationDara: type: object properties: commitAt: type: string nullable: false format: date-time description: Fecha y hora de la confirmacion de la operacion (ISO 8601). TransactionResponse: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Operación Procesada detail: example: >- La transacción ha sido procesada y se ha devuelto el estado actual de la operación. data: type: object properties: id: type: string format: uuid description: Identificador único en formato UUID. status: type: string description: >- Indica el status del pago. ```PENDING```: la orden fue creada y el POS aún no ha confirmado el pago. ```CANCELED```: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). ```PAID```: el POS confirmó exitosamente el pago. ```VOID_PENDING```: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. ```VOIDED```: el POS confirmó la anulación del pago. enum: - PENDING - CANCELED - PAID - VOID_PENDING - VOIDED example: PAID amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' confirmData: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 cancellationDara: type: object properties: commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). successDetails: type: object nullable: true description: >- Detalles del éxito. Estándar basado en la estructura de 'Problem Details' (RFC 9457) para estandarizar las respuestas exitosas en toda la arquitectura de microservicios. required: - title properties: status: type: integer description: >- El código de estado HTTP generado por el servidor de origen (ej. 200, 201). minimum: 200 maximum: 299 title: type: string description: Un resumen breve y legible por humanos sobre el tipo de éxito. detail: type: string description: >- Una explicación legible por humanos específica para esta ocurrencia del éxito. data: description: >- Contenedor de información que puede almacenar un objeto único o una lista de objetos. oneOf: - type: object - type: array items: type: object successDetailsArray: type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un arreglo de objetos. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: array description: Representa una colección de entidades de negocio. items: type: object TransactionsResponse: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un arreglo de objetos. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: array description: Representa una colección de entidades de negocio. items: type: object - type: object properties: title: example: Listado de Transacciones detail: example: >- Se ha recuperado el historial de transacciones del terminal solicitado. data: type: array items: type: object properties: id: type: string format: uuid description: Identificador único en formato UUID. status: type: string description: >- Indica el status del pago. ```PENDING```: la orden fue creada y el POS aún no ha confirmado el pago. ```CANCELED```: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). ```PAID```: el POS confirmó exitosamente el pago. ```VOID_PENDING```: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. ```VOIDED```: el POS confirmó la anulación del pago. enum: - PENDING - CANCELED - PAID - VOID_PENDING - VOIDED example: PAID amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' confirmData: type: object nullable: true description: >- Datos de confirmación bancaria. **Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'.** En estados pendientes o cancelados, este campo será null o no existirá. properties: authorizationCode: type: string description: Código de autorización bancaria. example: '171599' processCode: type: string example: '002000' commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). amountReference: description: >- Monto de referencia en la moneda especificada en currencyReference con 2 decimales. type: number nullable: false format: double example: '100.001' terminalNumber: type: string description: Numero de terminal. example: '98202003219630' trace: type: string description: Número de traza (Trace). example: '000535' utcDate: type: string description: Timestamp UTC del banco. example: '1007151715' cardTypeForRpt: type: string description: Tipo de tarjeta (C=Crédito, D=Débito). example: C visOrMccCard: type: string description: Franquicia de la tarjeta. example: MCC batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 cancellationDara: type: object properties: commitAt: type: string nullable: false format: date-time description: >- Fecha y hora de la confirmacion de la operacion (ISO 8601). serialPos: type: string description: Serial del POS example: '98202003219630' bankCode: type: string nullable: false description: Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). terminal: type: object properties: id: type: string example: TMS ID affiliateCode: type: string example: '0010800050' number: type: string description: Numero de terminal. example: '98202003219630' serial: type: string description: Serial del terminal físico. example: '98202003219630' bankId: type: string example: '3' bankCode: type: string nullable: false description: Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). settlementSummary: type: object properties: batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 transactionCount: type: integer example: 12 closedAt: type: string format: date-time example: '2023-04-04T15:26:51.187Z' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. terminal: type: object properties: id: type: string example: TMS ID affiliateCode: type: string example: '0010800050' number: type: string description: Numero de terminal. example: '98202003219630' serial: type: string description: Serial del terminal físico. example: '98202003219630' bankId: type: string example: '3' bankCode: type: string nullable: false description: Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). debitBatch: type: string description: Falta ser definido por Carlos Cardenas SettlementsResponse: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un arreglo de objetos. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: array description: Representa una colección de entidades de negocio. items: type: object - type: object properties: title: example: Listado de Cierres detail: example: Se ha recuperado el historial de cierres de lote del terminal. data: type: array items: type: object properties: batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 transactionCount: type: integer example: 12 closedAt: type: string format: date-time example: '2023-04-04T15:26:51.187Z' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. terminal: type: object properties: id: type: string example: TMS ID affiliateCode: type: string example: '0010800050' number: type: string description: Numero de terminal. example: '98202003219630' serial: type: string description: Serial del terminal físico. example: '98202003219630' bankId: type: string example: '3' bankCode: type: string nullable: false description: >- Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). debitBatch: type: string description: Falta ser definido por Carlos Cardenas SettlementResponse: allOf: - type: object nullable: true description: >- Variante de SuccessDetails donde 'data' es estrictamente un objeto único. required: - title - data properties: status: type: integer minimum: 200 maximum: 299 title: type: string detail: type: string data: type: object description: Representa una entidad única de negocio. - type: object properties: title: example: Cierre de Lote detail: example: Detalles del cierre de lote solicitado. data: type: object properties: batchNumber: description: >- Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones. type: integer example: 3 transactionCount: type: integer example: 12 closedAt: type: string format: date-time example: '2023-04-04T15:26:51.187Z' currencyReference: type: string nullable: false enum: - USD - EUR - COP - USDT - VES description: >- Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. terminal: type: object properties: id: type: string example: TMS ID affiliateCode: type: string example: '0010800050' number: type: string description: Numero de terminal. example: '98202003219630' serial: type: string description: Serial del terminal físico. example: '98202003219630' bankId: type: string example: '3' bankCode: type: string nullable: false description: >- Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137). debitBatch: type: string description: Falta ser definido por Carlos Cardenas