External Sales Data Integration

You can import sales data from various third-party sources into the Petrosoft back-office system. This ensures that transactions occurring outside of the managed Points of Sale (POS) are captured, providing a unified view of all sales activity.

This integration is currently utilized by partners such as Vroom Delivery to synchronize their external sales data with Petrosoft Cloud.

How it Works

External systems send sales data to Petrosoft Cloud as PJR (POS Journal Report) transactions, fully compliant with the Conexxus standard.

CStoreOffice® aggregates these PJR transactions and generates shift reports. Once generated, these shifts are processed through the standard CStoreOffice® workflow alongside POS data, providing a complete picture of daily sales activity at the station.

Integration Guide

Follow the steps below to connect the third-party systems to Petrosoft Cloud:

1. Get access credentials

To interact with Petrosoft Cloud, obtain a dedicated username and password. Submit a support ticket to request your API credentials.

2. Authenticate

Before sending data, you must receive a JWT (JSON Web Token). This token must be included in the Authorization header of all subsequent requests.

Create a request to https://cnnx35-api.petrosoft.cloud/api/auth/by-password endpoint with Content-Type header equals to application/x-www-form-urlencoded. Send you access credentials in a request body.

curl -X 'POST' \
  'https://cnnx35-api.petrosoft.cloud/api/auth/by-password' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'email={UserLogin}&password={UserPassword}'

3. Send PJR Data

Send a POST request to https://cnnx35-api.petrosoft.cloud/api/journals/pos endpoint. Use the following parameters:

• Authorization header: a JWT token received on Step 2.
• Content-Type header: multipart/form-data
• Payload: The POS Journal Report (PJR) file formatted according to the Conexxus standard.

curl -X 'POST' \
  'https://cnnx35-api.petrosoft.cloud/api/journals/pos' \
  -H 'Accept: application/xml' \
  -H 'Authorization: Bearer <JWT>' \
  -F 'PJR=@PJR20251111060400820.xml;type=text/xml'

The backend will respond with an acknowledgment in XML format containing the following data:

XML Path	Description
NAXML-Acknowledgement/TransmissionHeader/StoreLocationID	Store location ID
NAXML-Acknowledgement/TransmissionHeader/VendorName	Vendor name
NAXML-Acknowledgement/TransmissionHeader/VendorModelVersion	Vendor model version
NAXML-Acknowledgement/TransmissionHeader/@timeStamp	Acknowledgement date and time
NAXML-Acknowledgement/AckHeader/DocumentName	Original document name
NAXML-Acknowledgement/AckHeader/DocumentType	Original document type
NAXML-Acknowledgement/AckHeader/ReferenceID	Unique document reference ID
NAXML-Acknowledgement/AckHeader/ValidationStatus	Validation status: Success FatalError NonFatalError
NAXML-Acknowledgement/AckHeader/StatusMessage	Status message
NAXML-Acknowledgement/Detail/LineNumber	Original document line number
NAXML-Acknowledgement/Detail/LinePosition	Original document line position
NAXML-Acknowledgement/Detail/ValidationMessage	Validation message
NAXML-Acknowledgement/Detail/Severity	Processing status code: Error Warning Info

Example acknowledgment (success):

<?xml version="1.0" encoding="UTF-8"?> 
<NAXML-Acknowledgement version="3.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
	<TransmissionHeader timeStamp="2018-08-01T09:30:47Z"> 
		<StoreLocationID/> 
		<VendorName/> 
		<VendorModelVersion/> 
	</TransmissionHeader> 
	<AckHeader> 
		<ReferenceID>67c8246a22b452001329a0cc</ReferenceID> 
		<DocumentName>PJR20250217012300.xml</DocumentName> 
		<DocumentType>JournalReport</DocumentType> 
		<ValidationStatus>Success</ValidationStatus> 
		<StatusMessage>OK</StatusMessage>		 
	</AckHeader> 
</NAXML-Acknowledgement>

4. Monitor POS connection

Call /api/location/<locationId>/connection-state endpoint every 5 minutes to check the availability of the POS system. Provide a JWT token received on Step 2 in the Authorization header.

curl -X 'POST' \
  'https://cnnx35-api.petrosoft.cloud/api/location/<CSO_LocationId>/connection-state' \ 
  -H 'Accept: application/json' \ 
  -H 'Authorization: Bearer <TOKEN>' \ 
  -H 'Content-Type: application/json' \ 
  -d '{"state":"OK","recordedAt":"2025-02-21T08:00:03-0500"}'

Supported PJR Event Types

The system aggregates all PJR transactions received during a 24-hour window into a single daily shift report in accordance with the NAXML Conexxus 3.5 standard.

Only Sale (SaleEvent) and Refund (RefundEvent) transaction types are currently supported.