Location API
The Location API endpoint runs on the Simphony workstation, providing direct, low-latency access to POS services within the venue's network. This setup ensures resilience during WAN or cloud outages (allowing requests to continue locally), delivers higher performance for high-throughput use cases like kiosks, and offers predictable behavior based on the location's current configuration. However, it requires local certificate management, network controls, per-workstation endpoint availability, and disciplined operational practices for patching, version alignment, and monitoring. The local endpoint is ideal for on-premises workflows that must operate during internet disruptions, while the cloud endpoint remains valuable for enterprise governance and multi-site coordination.
Considerations for Location API Deployments
- On-premises implementation authentication:
The Location API deployment method uses TLS 1.2 with server-side X.509 certificates to ensure transport security (see the Oracle Simphony Configuration Guide). Application calls are authorized with short-lived access tokens issued by Enterprise Back Office through the cloud STS. Refresh tokens are time-bound, requiring each endpoint to connect to the STS at least once every 10 days to renew credentials. If an endpoint stays offline longer than this period, its refresh token will expire, and it cannot authenticate until it reconnects to the STS and completes a new sign-in or registration. Make sure outbound HTTPS access to the STS is permitted, and schedule token refreshes well before their expiration.
When creating API accounts for STS Gen 2 in Enterprise Back Office API Account Management, set the Client Scope to Both or Local. This configuration allows tokens obtained for that client to authorize access to the on-premises API.
- TLS Certificate Requirement: HTTPS is mandatory for Location API deployments. Ensure that every workstation has a valid TLS certificate issued by a trusted root certificate authority.
- Default port and API path:
- The default port for Location API deployments is 5443.
- API paths beyond the base URL mirror those of the cloud endpoints.
- The Notification API and Connection status are only available from Cloud API deployments; they are not available for Location API deployments.
- Shifting API request and response handling from the cloud to the location (typically hosted on workstation clients) may increase the compute and resource demands on those clients.
- Certificates and Security: Someone with access to the Simphony workstation hosting the endpoint must handle certificate provisioning and rotation, enforce mutual TLS, and set least-privilege scopes per device or application.
- Performance: Typically offers lower latency and greater consistency during peak times, making it ideal for kiosks and other high-throughput use cases.
- Resilience: Operates independently during WAN or cloud outages, remaining aligned with the location's live configuration.
- Deployment and Operations: Requires per-workstation availability, local network and firewall configuration, as well as regular patching, monitoring, and version alignment.
- Scale: Scaling across multiple sites involves more setup overhead; consider tools for automated provisioning, mobile device management (MDM), and certificate lifecycle management.
- Observability: Local endpoints provide less reportability, as enterprise cloud-based dashboards are unavailable.
- Compliance: Ensure local devices and networks adhere to PCI and corporate standards.
- Organization Service:
- Location search within an organization
- Revenue center search within a location
- Configuration Service:
- Barcode collection retrieval
- Organizations Notification
- Configuration Notification
- Employees Notification
Note:
Only the Check Notification is supported for Location API integrations.See Location-Based API Requirements for Simphony Transaction Services Gen 2 for more information.