TIPP Transactions – API Endpoints

This is a TIPP PRO page. It is a read-only reference that lists every API route of the TIPP Transactions service (the service that posts orders, receipts, returns and similar transactions into Exact Globe), with the fields each route accepts, an example request body and a cURL example. It also shows whether the service is reachable. It is normally used by TIPP administrators, integrators and consultants who want to connect another system to TIPP Transactions, or who want to check that the service is running. It is opened with the Available Endpoints button on the TIPP Engine Settings page.

Before you start

• A TIPP PRO licence is needed to use the page fully. Without it, the catalog is still visible but the page is read-only, only Close stays active, and the message “Failed: No TIPP PRO licence available; please reach out to TICE-IT. TIPP Transactions requires a TIPP PRO licence to process transactions (the current licence is ‘…’). Install the TIPP PRO licence file on the Synergy License Management page (Modules > TIPP > Setup > License).” is shown. The licence file is installed on the License page (Modules > TIPP > Setup > General > License).
• The TIPP Transactions Windows service must be installed and running. The page finds its catalog file (Endpoints.xml) automatically from the running service, or downloads it from the service when the service runs on another server. Nobody types in a file location.
• The Service Base URL is set on the TIPP Engine Settings page (Modules > TIPP > Setup > Connections > Engine Settings). That page has a Check Running Service button to verify the connection.

How to find a route

1. Open the page. Wait until “Loading endpoints catalog…” is replaced by the list of backends, entities and operations. The number of operations is shown next to the filter box.
2. Type part of an entity name, operation name or path in the box with the hint “Filter by entity, operation or path…”. The list narrows as you type and the counter changes to “[n] matching”. Entities, groups and backends with no match are hidden.
3. Optionally narrow the list to one functional group, for example salesorders, with the drop-down next to the filter box (see How to show one functional group across all backends).
4. Click a route row to open it. It expands to show the description, the Body fields table, and the tabs Example body and cURL. Click the row again to close it.
5. Use Expand all to open every route, and Collapse all to close them again.

How to show one functional group across all backends

1. Open the drop-down next to the filter box. Its first choice is “All groups”. The other choices are every functional group found in the catalog, in alphabetical order, for example salesorders or purchaseorders. Groups whose entities are all disabled are not listed.
2. Choose a group. Only the operations of that group stay visible, in every backend that has them. The counter changes to “[n] matching”.
3. Backends with nothing left to show are hidden. For example, when you pick the salesorders group, a backend that has no sales order operations disappears.
4. You can combine the group choice with text in the filter box. An operation is shown when it matches the typed text and belongs to the chosen group.
5. Choose “All groups” and clear the filter box to see everything again. The counter then shows the total number of operations.

How to copy the full URL of a route

1. Find the route and click Copy URL on its row. You do not need to expand it.
2. The button briefly changes to “Copied” and the full address (Service URL plus the route path) is on your clipboard.

How to check that the service is running

1. Look at the Live service field after the catalog has loaded.
2. “OK (v…)” followed by a version number means the service answered. “Unreachable – …” followed by a reason means it did not. “Not configured” means there is no Service URL.
3. If it is unreachable, check that the TIPP Transactions Windows service is running and that the Service Base URL on the TIPP Engine Settings page is correct.

How to refresh the catalog

1. Click Refresh in the button bar, or reload the page. The catalog is read again from the service, so routes added or removed there appear without any other action.

Screen guide

Header fields

• Endpoints catalog: read only. Shows where the catalog comes from: the file location on the server, or “Downloaded from [service address]/api/endpoints (cached copy, refreshed automatically)” when the service runs on another server.
• Service URL: the address of the TIPP Transactions service. It is filled in from the TIPP settings. It is used to build the full URL for Copy URL and for the live check. The field can be typed in, but the page has no save action, so a change here only affects this page while you are on it.
• Catalog version: read only. The version number written in the catalog.
• Live service: read only. The result of the health check of the service. It is checked again when the Service URL field is changed.

Base URL and Authentication

• The call pattern is shown as POST [service-url]/api/{backend}/{entity}/{operation}.
• A table of Header, Required and Description lists the request headers the service expects. The cURL examples use X-API-Key, X-Globe-Server, X-Globe-Database and X-Globe-Division. X-Globe-Server and X-Globe-Database are sent together to point straight at an Exact Globe administration database, and then X-Globe-Division is optional.

Service Routes

• A table of Method, Path and Description for routes of the service itself, such as health checks, as listed in the catalog.

Endpoints

• Routes are grouped by backend (for example sdk and entityservices), then by entity, and sometimes by a named group that bundles related entities. Click a backend entity or group heading to collapse or expand it. Each shows how many entities and operations it holds.
• Each route row shows the method (for example POST), the path, a Copy URL button and a short description. Only operations that are enabled in the catalog are shown.
• Body fields table columns: Field (indented fields belong to the field above, for example lines of an order), Type, Required (required or optional), Max len (the maximum number of characters Exact Globe+ accepts for that field, or a dash when there is no limit), SDK property or ES property (the matching property name in the backend, or “(same)” when it has the same name), Description.
• Example body tab: a sample request with only the required fields and “waitForResult”: true filled with sample values. Replace the sample values with real ones.
• cURL tab: the same request as a cURL command, with placeholders for the service address, SQL server, database, division and API key.

Response Format

• A successful call (HTTP 200 or 202) returns requestId, success true, status “Success” and an entityCode, which is the number of the record that was created.
• A failed call (HTTP 422) returns requestId, success false, status “Failed”, an errorReason and an errorMessage, for example “Validation: YourReference is required.”

Buttons

• Refresh: reloads the page and the catalog. Disabled without a TIPP PRO licence.
• Close: leaves the page. Always available.
• Expand all, Collapse all: open or close every route row.
• Copy URL: copies the full route address.
• Group drop-down: next to the filter box. Shows “All groups” or one functional group.
• Favorite and Print buttons in the header: add the page to your favorites and open a printable view.

Messages and what to do

• “The Endpoints.xml catalog could not be located. It is read from the running TIPP Transactions service’s install folder, or downloaded from its /api/endpoints route when the service runs on another server (Service Base URL on the TIPP Engine Settings page) – check that the service is running and reachable from this web server (Check Running Service on the TIPP Engine Settings page), then reload this page.” Start the TIPP Transactions service or fix the Service Base URL, then reload.
• “Endpoints catalog not found at: [location] — the location is re-detected automatically from the running TIPP Transactions service; check the service (TIPP Engine Settings page) and reload this page.” Same fix: check the service and reload.
• “Error reading endpoints catalog: …” The catalog file could not be read. Ask your TIPP administrator to check the service installation.
• “Failed to load Endpoints.xml: …” or “Failed to parse Endpoints.xml: …” The catalog could not be loaded or is damaged. Click Refresh; if it persists, ask your TIPP administrator or TICE-IT (tipp@tice-it.com).
• “Unreachable – …” in Live service: the service did not answer at the Service URL. Check that the service is running and the address is right.
• “No backends defined.” The catalog contains no routes.

What you cannot do here

• You cannot add, edit or remove routes or fields. The page only displays the catalog of the running service. Routes are changed in the service’s catalog file.
• You cannot send test calls from this page. It only shows examples you can copy.
• You cannot set the Service Base URL here. Use the TIPP Engine Settings page.

Related pages

• TIPP Engine Settings: holds the Service Base URL, the Check Running Service button and the Available Endpoints button that opens this page.
• TIPP Backoffice Connection: sets up the link to the Exact Globe administrations that the routes post into.
• License page: where the TIPP PRO licence is installed.

Common questions

What is this page for? It lists all API routes of the TIPP Transactions service with their fields and examples, so you can connect another system to TIPP or see what the service offers.

How do I open this page? Click the Available Endpoints button on the TIPP Engine Settings page.

How do I find the route for a specific action? Type part of the entity, operation or path in the filter box, for example the name of the document type. Then click the row to see its fields.

How do I see only the sales order operations of all backends? Choose the group, for example salesorders, in the drop-down next to the filter box. Backends with no operations in that group are hidden. You can combine this with text in the filter box.

What does Live service say and what if it is Unreachable? It shows the result of a health check on the service. “OK (v…)” is good. “Unreachable” means the service did not answer, so check that the TIPP Transactions Windows service is running and the Service Base URL on the TIPP Engine Settings page is correct.

What does Max len mean? It is the maximum number of characters Exact Globe+ accepts for that field. A dash means no limit is given.

What do SDK property and ES property mean? They show the name of the field in the backend when it differs from the field name used in the request. “(same)” means the name is the same.

Why do I only see Close and everything else is greyed out? Your system has no TIPP PRO licence. Install the PRO licence on the License page.

Can I change a route or field here? No. The page only displays the catalog. Changes are made in the catalog of the service, and then you click Refresh.

What does a failed call return? A response with success false, the status “Failed”, an errorReason and an errorMessage, for example “Validation: YourReference is required.”.

How do I get the full URL of a route? Click Copy URL on the route row. It combines the Service URL with the route path.

Why is there an authentication header in the examples? The cURL examples show X-API-Key and the Exact Globe target headers. TIPP and the service are linked by the TIPP Transactions installer, so ask your TIPP administrator or TICE-IT if you need the key.