Push transactions

How to set up pushing of transactions from Proactis

For transactional documents the Proactis API supports the option to POST the document to a specified endpoint each time the document reaches the correct status. For requisitions, ERP orders, receipts and timecards the status is fixed, for invoices the status is configurable.

Document types

The option to push documents to a specified customer application is only available for transactional documents: requisitions, ERP orders, receipts, invoices and timecards. All other documents require a GET request initiated by the client application.

Configuration of the endpoint, and in some cases the preferred export status, can be done thru the Communication Settings. Communication settings endpoints are available in the API reference or Swagger.

Communication settings

Configuration of the Communication Settings is usually done once for every environment and won't change unless the endpoint changes. Depending on your requirements the API has methods to setup, retrieve, update or delete endpoint configuration.

Document types like the requisition, receipt, invoice and timecard support one endpoint. The ERP order supports multiple endpoints. In that case each endpoint will receive the same message.

Communication settings support the following configuration items:

Element	Description
id	Endpoint name: A unique name for the endpoint. This is supported for ERP orders only
url	Endpoint URI: The endpoint supports URIs starting with `http://`, `https://`, `ftp://` or `sftp://`
multipartContentType	Attachment Type: To setup a default multipart content-type whenever the client application requires a different one from the default `multipart/mixed`
contentType	Content Type: Configure a default content type whenever the client application requires a different one from the default `application/xml`
authentications	The communication settings support zero, one or multiple authentication types. For example the type `OAUTH2` and `API_KEY` can be used together
type	Authentication type: Specify the type of authentication to be performed for the specified endpoint. Possible types: `BASIC` (for Basic Authentication), `USERNAME_PASSWORD` (for FTP or SFTP), `OAUTH2` (only Client Credentials flow is supported) or `API_KEY`
username	Username: To be used with Authentication type `BASIC` or `USERNAME_PASSWORD`
password	Password: To be used with Authentication type `BASIC` or `USERNAME_PASSWORD`
clientId	Client ID: OAuth Client ID for the client credentials flow. To be used with Authentication type `OAUTH2`
clientSecret	Client Secret: OAuth Client Secret for the client credentials flow. To be used with Authentication type `OAUTH2`
scope	Scope: Optional OAuth scope for the client credentials flow. To be used with Authentication type `OAUTH2`. Multiple scopes have to be separated by spaces
tokenUrl	Token URL: URL to retrieve the OAuth client credentials token. To be used with Authentication type `OAUTH2`
apiKeyHeaderName	API Key Header name: The name of the API Key HTTP header. To be used with Authentication type `API_KEY`
apiKey	API Key: A fixed value which is used for the API Key HTTP header. To be used with Authentication type `API_KEY`
headers	Additional custom HTTP-headers can be set for each `POST` request. Specify these additional HTTP-headers as a key/value pair. Currently supported for ERP orders only
header-name	header-value
exportStatus	Invoice Export Status: Invoices can be exported in one or multiple statuses. Invoices will be exported once the invoice reaches the specified status. Possible statuses: `CONCEPT`, `EXCEPTION`, `FORAPPROVAL`, `PROCESSED`, `CLEARED`, `SENT`, `ONHOLD`, `FORVALIDATION`, `REJECTED`, `DELETED`, `ARCHIVED`, `FOREVALUATION`

Response

Processed messages will be added to the relevant widgets. These widgets will also show the result of the delivery based on the response received from the endpoint. The API expects a cXML response and is able to update the widget status depending on the code attribute. In case of an error, the contents of the Status element will be shown in the widget.

Successful
Failure

<?xml version="1.0"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.011/cXML.dtd"> 
<cXML version="1.2.011" payloadID="20211105102252322.f3922af03e1911ecb9bbae8b9e28f068" timestamp="2023-06-20T10:22:52-CET">
   <Response>
      <Status code="200" text="OK"></Status>
   </Response>
</cXML>

<?xml version="1.0"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.011/cXML.dtd"> 
<cXML version="1.2.011" payloadID="20211105102252322.f3922af03e1911ecb9bbae8b9e28f068" timestamp="2023-06-20T10:22:52-CET">
   <Response>
      <Status code="500" text="The incoming cXML is not in a known format">The incoming cXML is not in a known format</Status>
   </Response>
</cXML>

Example configuration

Below you will find example configurations for most used cases. Remove the comments before posting the communication settings to the API.

Requisition

{
   "url": "https://endpoint.com/requisition"               // URL where the requisition will be sent to
}

{
   "url": "https://endpoint.com/requisition",              // URL where the requisition will be sent to
   "authentications":
   [
      {
         "type": "BASIC",                                  // Basic Authentication
         "username": "username",                           // Username used for Basic Authentication
         "password": "password"                            // Password used for Basic Authentication
      }
   ]
}

{
   "url": "sftp://endpoint.com/requisition",               // URL of the SFTP server and folder
   "authentications":
   [
      {
         "type": "USERNAME_PASSWORD",                      // Username+password authentication
         "username": "username",                           // Username used for authentication
         "password": "password"                            // Password used for authentication
      }
   ]
}

{
   "url": "https://endpoint.com/requisition",              // URL where the requisition will be sent to
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      }
   ]
}

{
   "url": "https://endpoint.com/requisition",              // URL where the requisition will be sent to
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      },
      {
         "type": "API_KEY",                                // API Key authentication
         "apiKeyHeaderName": "x-api-key",                  // HTTP header name
         "apiKey": "apikeyvalue"                           // HTTP header value
      }
   ]
}

{
   "url": "https://endpoint.com/requisition",              // URL where the requisition will be sent to
   "headers": [
      {
         "key-1": "value-1",                               // HTTP-header as a key/value pair
         "key-2": "value-2"                                // Additional custom HTTP-header
      }
   ]
}

ERP order

{
   "id": "My endpoint name",                               // A unique name for the endpoint
   "url": "https://endpoint.com/order",                    // URL where the order will be sent to
   "includeAttachments": false                             // Will remove attachments
}

{
   "id": "My endpoint name",                               // A unique name for the endpoint
   "url": "https://endpoint.com/order",                    // URL where the order will be sent to
   "includeAttachments": false,                            // Will remove attachments
   "authentications":
   [
      {
         "type": "BASIC",                                  // Basic Authentication
         "username": "username",                           // Username used for Basic Authentication
         "password": "password"                            // Password used for Basic Authentication
      }
   ]
}

{
   "id": "My endpoint name",                               // A unique name for the endpoint
   "url": "sftp://endpoint.com/order",                     // URL where the order will be sent to
   "includeAttachments": false,                            // Will remove attachments
   "authentications":
   [
      {
         "type": "USERNAME_PASSWORD",                      // Username+password authentication
         "username": "username",                           // Username used for authentication
         "password": "password"                            // Password used for authentication
      }
   ]
}

{
   "id": "My endpoint name",                               // A unique name for the endpoint
   "url": "https://endpoint.com/order",                    // URL where the order will be sent to
   "includeAttachments": false,                            // Will remove attachments
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      }
   ]
}

{
   "id": "My endpoint name",                               // A unique name for the endpoint
   "url": "https://endpoint.com/order",                    // URL where the order will be sent to
   "includeAttachments": false,                            // Will remove attachments
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      },
      {
         "type": "API_KEY",                                // API Key authentication
         "apiKeyHeaderName": "x-api-key",                  // HTTP header name
         "apiKey": "apikeyvalue"                           // HTTP header value
      }
   ]
}

{
   "id": "My endpoint name",                               // A unique name for the endpoint
   "url": "https://endpoint.com/order",                    // URL where the order will be sent to
   "includeAttachments": false,                            // Will remove attachments
   "headers": [
      {
         "key-1": "value-1",                               // HTTP-header as a key/value pair
         "key-2": "value-2"                                // Additional custom HTTP-header
      }
   ]
}

Receipt

{
   "url": "https://endpoint.com/receipt"                   // URL where the receipt will be sent to
}

{
   "url": "https://endpoint.com/receipt",                  // URL where the receipt will be sent to
   "authentications":
   [
      {
         "type": "BASIC",                                  // Basic Authentication
         "username": "username",                           // Username used for Basic Authentication
         "password": "password"                            // Password used for Basic Authentication
      }
   ]
}

{
   "url": "sftp://endpoint.com/receipt",                   // URL where the receipt will be sent to
   "authentications":
   [
      {
         "type": "USERNAME_PASSWORD",                      // Username+password authentication
         "username": "username",                           // Username used for authentication
         "password": "password"                            // Password used for authentication
      }
   ]
}

{
   "url": "https://endpoint.com/receipt",                  // URL where the receipt will be sent to
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      }
   ]
}

{
   "url": "https://endpoint.com/receipt",                  // URL where the receipt will be sent to
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      },
      {
         "type": "API_KEY",                                // API Key authentication
         "apiKeyHeaderName": "x-api-key",                  // HTTP header name
         "apiKey": "apikeyvalue"                           // HTTP header value
      }
   ]
}

{
   "url": "https://endpoint.com/receipt",                  // URL where the receipt will be sent to
   "headers": [
      {
         "key-1": "value-1",                               // HTTP-header as a key/value pair
         "key-2": "value-2"                                // Additional custom HTTP-header
      }
   ]
}

Invoice

{
   "url": "https://endpoint.com/invoice",                  // URL where the invoice will be sent to
   "exportStatus":
   [
      "PROCESSED"                                          // Invoice will be exported in PROCESSED status
   ]
}

{
   "url": "https://endpoint.com/invoice",                  // URL where the invoice will be sent to
   "authentications":
   [
      {
         "type": "BASIC",                                  // Basic Authentication
         "username": "username",                           // Username used for Basic Authentication
         "password": "password"                            // Password used for Basic Authentication
      }
   ],
   "exportStatus":
   [
      "PROCESSED"                                          // Invoice will be exported in PROCESSED status
   ]
}

{
   "url": "sftp://endpoint.com/invoice",                   // URL of the SFTP server and folder
   "authentications":
   [
      {
         "type": "USERNAME_PASSWORD",                      // Username+password authentication
         "username": "username",                           // Username used for authentication
         "password": "password"                            // Password used for authentication
      }
   ],
   "exportStatus":
   [
      "PROCESSED"                                          // Invoice will be exported in PROCESSED status
   ]
}

{
   "url": "https://endpoint.com/invoice",                  // URL where the invoice will be sent to
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      }
   ],
   "exportStatus":
   [
      "PROCESSED"                                          // Invoice will be exported in PROCESSED status
   ]
}

{
   "url": "https://endpoint.com/invoice",                  // URL where the invoice will be sent to
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      },
      {
         "type": "API_KEY",                                // API Key authentication
         "apiKeyHeaderName": "x-api-key",                  // HTTP header name
         "apiKey": "apikeyvalue"                           // HTTP header value
      }
   ],
   "exportStatus":
   [
      "PROCESSED"                                          // Invoice will be exported in PROCESSED status
   ]
}

{
   "url": "https://endpoint.com/invoice",                  // URL where the invoice will be sent to
   "authentications":
   [
      {
         "type": "BASIC",                                  // Basic Authentication
         "username": "username",                           // Username used for Basic Authentication
         "password": "password"                            // Password used for Basic Authentication
      }
   ],
   "exportStatus":
   [
      "FORAPPROVAL",                                       // Invoice will be exported in 3 statuses
      "FORVALIDATION",
      "PROCESSED"
   ]
}

{
   "url": "https://endpoint.com/invoice",                  // URL where the invoice will be sent to
   "headers": [
      {
         "key-1": "value-1",                               // HTTP-header as a key/value pair
         "key-2": "value-2"                                // Additional custom HTTP-header
      }
   ],
   "exportStatus":
   [
      "PROCESSED"                                          // Invoice will be exported in PROCESSED status
   ]
}

Timecard

{
   "url": "https://endpoint.com/timecard"                  // URL where the timecard will be sent to
}

{
   "url": "https://endpoint.com/timecard",                 // URL where the timecard will be sent to
   "authentications":
   [
      {
         "type": "BASIC",                                  // Basic Authentication
         "username": "username",                           // Username used for Basic Authentication
         "password": "password"                            // Password used for Basic Authentication
      }
   ]
}

{
   "url": "sftp://endpoint.com/timecard",                  // URL of the SFTP server and folder
   "authentications":
   [
      {
         "type": "USERNAME_PASSWORD",                      // Username+password authentication
         "username": "username",                           // Username used for authentication
         "password": "password"                            // Password used for authentication
      }
   ]
}

{
   "url": "https://endpoint.com/timecard",                 // URL where the timecard will be sent to
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      }
   ]
}

{
   "url": "https://endpoint.com/timecard",                 // URL where the timecard will be sent to
   "authentications":
   [
      {
         "type": "OAUTH2",                                 // OAuth2 Client Credentials
         "clientId": "clientidvalue",                      // OAuth2 Client ID
         "clientSecret": "clientsecretvalue",              // OAuth2 Client Secret
         "scope": "scope1 scope2",                         // OAuth2 Scope
         "tokenUrl": "https://endpoint.com/oauth2/token"   // URL of the token endpoint
      },
      {
         "type": "API_KEY",                                // API Key authentication
         "apiKeyHeaderName": "x-api-key",                  // HTTP header name
         "apiKey": "apikeyvalue",                          // HTTP header value
      }
   ]
}

{
   "url": "https://endpoint.com/timecard",                 // URL where the timecard will be sent to
   "headers": [
      {
         "key-1": "value-1",                               // HTTP-header as a key/value pair
         "key-2": "value-2"                                // Additional custom HTTP-header
      }
   ]
}

Push transactions

Document types​

Communication settings​

Response​

Example configuration​

Requisition​

ERP order​

Receipt​

Invoice​

Timecard​

Contents