{ "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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, "description": "Este campo se incluyo para que jose puediera crear el endpoint de forma mas sencilla sin embargo se debe priorizar el uso de 'detail' y 'errors' solo se mantendra hasta que jose pueda hacer la migracion.", "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" } } } } } ] } } } }