The POS Sales Service (Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Nelsoncg98/InnovaTech/llms.txt
Use this file to discover all available pages before exploring further.
servicio-ventapos) is the transaction orchestrator for InnovaTech’s physical store channel. When a cashier completes a sale at a point-of-sale terminal, the POS frontend sends the sale request to this service, which takes responsibility for coordinating every downstream operation: validating the customer, decrementing inventory, and processing payment. Because these steps span multiple independent microservices — each with its own database — the orchestrator implements the SAGA pattern to guarantee that partial failures do not leave the system in an inconsistent state. All POS sales endpoints are accessed through the API Gateway at the /api/v1/ventas-pos/** namespace.
Base Path
Access the POS Sales API through the gateway:8082 for local debugging:
Transaction Flow
A complete sale transaction follows these orchestration steps in sequence:Receive sale request
The POS frontend submits a sale payload to
POST /api/v1/ventas-pos/... via the API Gateway. The payload includes the customer identifier, a list of products with quantities, and the chosen payment method.Validate customer
The orchestrator calls
servicio-clientes to confirm that the customer exists and is in good standing. If the customer cannot be validated, the transaction is rejected immediately and no further steps are taken.Decrement inventory
For each line item in the sale, the orchestrator calls
POST /api/inventario/{productoId}/descontar?cantidad={n} on servicio-inventario (port 8081). Each call is atomic and transactional within the inventory service. If any product has insufficient stock, the SAGA enters rollback mode.Process payment
With inventory secured, the orchestrator submits the payment to the configured external payment gateway. This step is currently planned and under development.
Confirm sale and return receipt
If all steps succeed, the orchestrator persists the sale record and returns a receipt to the POS frontend. The transaction is considered complete.
SAGA Rollback
InnovaTech’s SAGA implementation uses logical compensating transactions rather than two-phase commit (2PC). This means that if a failure occurs mid-transaction, the orchestrator does not attempt to undo database changes at the protocol level — instead, it explicitly calls corrective operations on each affected service. The most common rollback scenario is a payment failure after inventory has already been decremented. In this case, the orchestrator calls a stock-restore operation onservicio-inventario to add back the units that were subtracted during step 3. Each compensating action is idempotent where possible to handle retries safely.
Because SAGA uses compensating rollback rather than 2PC, there is a brief window between a step succeeding and its compensation completing where the system is in an intermediate state. This is eventual consistency by design. Clients should not assume that a failed sale response means zero state change occurred — always verify system state through the individual service endpoints if precise consistency is required.
Integration Dependencies
The POS Sales Orchestrator depends on the following services being reachable at their respective ports:| Dependency | Port | Status |
|---|---|---|
servicio-inventario | 8081 | Active — inventory decrement and restore |
servicio-clientes | TBD | Planned — customer validation |
| External payment gateway | — | Planned — payment processing |
servicio-inventario is unavailable when a sale is submitted, the transaction will fail at step 3 and no inventory changes will have been made. Ensure all active dependencies are running before processing sales.
Running the Service
Start the POS Sales Orchestrator from the project root:8082 and register with the Eureka service registry at http://localhost:8761/eureka/.