Egencia Approval Customisation SPI

{"openapi":"3.1.0","info":{"title":"Openconnect Approval Service","description":"<h1>Introduction to the Document</h1>\n<p>This document provides a detailed overview of the Approval Customisation SPI and how it can be used to customize the approval process as per clients requirements. The document contains both functional and technical details, which are intended to help developers understand the functionality of the SPI and how it can be implemented in their applications.</p>\n<h2>Audience</h2>\n<p>This document is aimed for Egencia customers, partners and software developers who would like to consume the Approval Customisation SPI.</p>\n<h2>Overview</h2>\n<p>Approval Customisation SPI gives Egencia customers greater control over their approval process and allows them to customize certain steps along the approval process. This provides more flexibility to each customer as per their unique and specific approval use case. This document will help you to find links to different SPI endpoints and a general overview of the SPI status codes you can expect from Approval Customisation SPI endpoints.</p>\n\n<h1>Openconnect Approval Service</h1>\n\n<h2>What Is Openconnect Approval Service?</h2>\n<p>Clients will be able to provide the approval required for both level 1 and 2 as well as the approvers for both these levels based on booking data.</p>\n\n<h2>Definitions</h2>\n<div>\n    <table style=\"width:50%; border-spacing:5px\"  border=\"1\" cellpadding=\"5px\">\n        <thead>\n            <tr >\n                <th style=\"padding:10px; width:30%\">Term</th>\n                <th style=\"padding:10px;\">Definition</th>\n            </tr>\n        </thead>\n        <tbody>\n            <tr>\n                <td style=\"padding:10px;\">Third Party Service Provider</td>\n                <td style=\"padding:10px;\">A Company that provides a software to Egencia client, e.g.: Expense Tool provider, ERP provider, HRIS provider.</td>\n            </tr>\n            <tr>\n                <td style=\"padding:10px;\">Connected System</td>\n                <td style=\"padding:10px;\">A Third Party Service Provider or Home built software, e.g.: Expense tool, Enterprise Resource Planning, Reconciliation Tool, Accounting Software. </br> The software that will provide the web service and receive the Expense Data.</td>\n            </tr>\n            <tr>\n                <td style=\"padding:10px;\">Consumer</td>\n                <td style=\"padding:10px;\">Anybody who consumes the API.</td>\n            </tr>\n            <tr>\n                <td style=\"padding:10px;\">Shared Client</td>\n                <td style=\"padding:10px;\">A company that is both client of Egencia and client of the Third Party Service Provider.</td>\n            </tr>\n            <tr>\n                <td style=\"padding:10px;\">Major version</td>\n                <td style=\"padding:10px;\">Please refer to Versions section in this document.</td>\n            </tr>\n            <tr>\n                <td style=\"padding:10px;\">CDF</td>\n                <td style=\"padding:10px;\">Means Custom Data Fields. These are the fields that are configurable for the Customer. They represent the analytical data or reporting data. This information will be in billing data, receipt and invoices. It helps generally for budget allocation and reconciliation.</td>\n            </tr>\n            <tr>\n                <td style=\"padding:10px;\">GDS</td>\n                <td style=\"padding:10px;\">\"A global distribution system (GDS) is a computerised network system owned or operated by a company that enables transactions between travel industry service providers, mainly airlines, hotels, car rental companies, and travel agencies.\" (source: Wikipedia - https://en.wikipedia.org/wiki/Global_distribution_system).</td>\n            </tr>\n            <tr>\n                <td style=\"padding:10px;\">Trip</td>\n                <td style=\"padding:10px;\">A Trip is a functional container which regroups a list of products and services. For example, a Trip Rio can contain a flight from a destination A to Rio and a hotel.</td>\n            </tr>\n        </tbody>\n    </table>\n</div>\n\n<h2>Authentication</h2>\n<p>OAS uses API Key Authentication scheme or Basic Auth Credentials scheme for Authorization access to its API. The authorization is done using the following steps.</p>\n<ol>\n    <li>We send HTTP request to the server with the <i>Api key added to x-api-key header</i> or <i>Base64 encoded credentials added to the Authorization header</i>.</li>\n    <li>The client server decodes and verifies the credentials and authenticates the request if the username & password is valid.</li>\n</ol>\n\n<h3><u>API Key Authentication scheme</u></h3>\n<p>The OAS uses API keys to authenticate requests. An application programming interface key (API key) is a unique identifier used to authenticate a user, developer, or calling program to an API.</p>\n<p>The partner provides API Key. This API Key is securely stored in our Vault and will be used for authenticating with the partner every time we make a call.</p>\n<p>You can authenticate the requests by validating the API Key when you receive an incoming request call from OAS. We will pass the API key with every request and you (the partner) will validate the API Key, if the API key is valid then you can accept and process request.</p>\n\n<h3><u>Basic Auth Credentials scheme</u></h3>\n<p>To work with the Approval Customisation SPIs, the partner will need to share the Auth Credentials to Egencia. Once the Auth credentials are shared, this (username & Password) will be securely stored in our Vault and will be used for authenticating with the partner every time we make a call. While making an authentication request we transmit the credentials as user-id/ password pairs, encoded using Base64.</p>\n<p>To authenticate we send the HTTP requests with the Authorization header that contains the \"Basic\" word followed by a space and a base64 encoded username:password string.</p>\n<p><strong>Signature sample</strong></p>\n<p>\n    <code style=\"display:block;color:black;white-space:pre-wrap;\">Authorization: Basic Zm9vOmJhcg==</code>\n</p>\n<p>The credentials are not encrypted or hashed while transmitting, but are merely encoded with Base64. Therefore, we use basic authentication in conjunction with HTTPS to provide confidentiality.</p>\n\n<p><strong><u>Note:</u> API Key Authentication Scheme is the preferred mode for authentication.</strong></p>\n\n<h3>401- Unauthorized Response</h3>\n<p>401 \"Unauthorized\" response is returned for requests with missing or incorrect credentials or api key. This response includes the WWW-Authenticate header.</p>\n\n\n<h2>Openconnect approval service</h2>\n\n<h3>Functional description</h3>\n<p>When a user clicks on the Book Now button on the Egencia checkout page, the approval process is triggered. During this approval process, the Approval Customisation feature comes into play and provides organisations with greater control over their approvals. Currently in version 1, this feature allows organisations to customize the approval required for both level 1 and level 2, as well as customize the approvers for both levels. We make an API call to the external system with the booking data to fetch this information which is then plugged into the approval process. This enhances the client's approval experience.</p>\n\n<h4>What</h4>\n<p>Clients will be able to provide the approval required for both level 1 and 2 as well as the approvers for both these levels based on booking data.</p>\n\n<h4>When</h4>\n<p>At checkout time, when the user clicks on the book button, Egencia platform will call the clients web service to send the booking data. This booking data is a SPI contract mentioned below. Depending on the clients response, we will plug in the approval required data and approvers into our approval process.</p>\n\n<h4>Mobile / Smartphone</h4>\n<p>The Approval Customisation Interface is compatible with mobile and it will have the same behaviour. Although there might be an impact on response time and processing time due to network/infra related issues.</p>\n\n<h4>Operations and methods</h4>\n<div>\n    <table style=\"width:50%; border-spacing:5px\"  border=\"1\" cellpadding=\"5px\">\n        <thead>\n        <tr >\n            <th style=\"padding:10px;\">Method</th>\n            <th style=\"padding:10px;\">Endpoint</th>\n        </tr>\n        </thead>\n        <tbody>\n        <tr>\n            <td style=\"padding:10px;\">GET</td>\n            <td style=\"padding:10px;\">/v1/approval-details</td>\n        </tr>\n        </tbody>\n    </table>\n</div>\n\n<h3>Security</h3>\n<div>\n    <table style=\"width:50%; border-spacing:5px\"  border=\"1\" cellpadding=\"5px\">\n        <thead>\n            <tr >\n                <th style=\"padding:10px;\">Type</th>\n                <th style=\"padding:10px;\">Name</th>\n                <th style=\"padding:10px;\">In</th>\n            </tr>\n        </thead>\n        <tbody>\n            <tr>\n                <td style=\"padding:10px;\">Api Key</td>\n                <td style=\"padding:10px;\">x-api-key</td>\n                <td style=\"padding:10px;\">Header</td>\n            </tr>\n            <tr>\n                <td style=\"padding:10px;\">Basic Auth</td>\n                <td style=\"padding:10px;\">Authorization</td>\n                <td style=\"padding:10px;\">Header</td>\n            </tr>\n        </tbody>\n    </table>\n</div>\n\n<h4>Communication Security</h4>\n<p>For Data Security, all the Egencia communication will happen over the SSL/TLS channel. This ensures that all data that travels between the Egencia server and your program are encrypted. This protects your credentials and the transmitted data.</p>\n\n<h2>Versioning</h2>\n<p>Egencia will notify the client about the availability of new major versions and provide the timeframe for the upgrades. Major version is a new version of the software with a significant change(s). Minor version is a new version of the software with possible backward compatibility and with a minor degree of change. The changes can be structural, and can contain enhancements, major bug fixes, or change of behaviour, endpoint changes, new fields added, or fields removed. The version change log will list all the changes included in the corresponding version from the previous one.</p>\n<h3>Version Change Log</h3>\n<p>You can also see a full API version change log under this heading.</p>\n<div>\n    <table style=\"width:50%; border-spacing:5px\"  border=\"1\" cellpadding=\"5px\">\n        <thead>\n        <tr >\n            <th style=\"padding:10px;\">API</th>\n            <th style=\"padding:10px;\">Current Version</th>\n            <th style=\"padding:10px;\">What has changed?</th>\n        </tr>\n        </thead>\n        <tbody>\n        <tr>\n            <td style=\"padding:10px;\">Approval Customisation SPI</td>\n            <td style=\"padding:10px;\">Version 1</td>\n            <td style=\"padding:10px;\">First stable version.</td>\n        </tr>\n        </tbody>\n    </table>\n</div>\n\n<h2>Approval Customisation SPI Details</h2>","version":"v1.0"},"servers":[{"url":"https://apis.egencia.com/openconnect/api","description":"Generated server url"}],"tags":[{"name":"Approval","description":"Approval interface that will get approval custom detail from external client based on the booking data passed in request"}],"paths":{"/v1/custom-approval":{"post":{"tags":["Approval"],"description":"It will return the custom approval details, for example - approvers and approval required for both the level based on the booking data passed in request","operationId":"getApprovalDetails","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRequest"}}},"required":true},"responses":{"500":{"description":"<b>Internal Server Error</b> : Failed to execute with custom approval details (1st or 2nd level)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/OpenconnectApprovalErrorResponseBean"}}}},"400":{"description":"<b>Bad Request</b> : Approval to execute with provided custom approval details (1st or 2nd level)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/OpenconnectApprovalErrorResponseBean"}}}},"200":{"description":"<b>Ok</b> : Approval to execute with provided custom approval details (1st or 2nd level)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalApprovalDetailsResponse"}}}},"401":{"description":"<b>Unauthorized</b> : Approval to execute with provided custom approval details (1st or 2nd level)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalApprovalDetailsResponse"}}}},"403":{"description":"<b>Forbidden</b> : Approval to execute with provided custom approval details (1st or 2nd level)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalApprovalDetailsResponse"}}}}}}}},"components":{"schemas":{"ErrorResponseDataBean":{"description":"Data","properties":{"attribute":{"type":"string","description":"Attribute"},"message":{"type":"string","description":"Message"},"external_attributes":{"type":"object","additionalProperties":{"type":"object"}}}},"ErrorSourceBean":{"description":"Source","properties":{"application_name":{"type":"string","description":"Application Name"},"error_code":{"type":"string","description":"Error Code"},"error_description":{"type":"string","description":"Error Description"}}},"OpenconnectApprovalErrorResponseBean":{"properties":{"error_code":{"type":"string","description":"Error Code"},"error_subcode":{"type":"string","description":"Error Sub Code"},"error_description":{"type":"string","description":"Error Description"},"detail_error_message":{"type":"string","description":"Details about Error Message"},"source":{"$ref":"#/components/schemas/ErrorSourceBean"},"data":{"type":"array","description":"Data","items":{"$ref":"#/components/schemas/ErrorResponseDataBean"}}}},"ApprovalRequest":{"description":"Approval request","properties":{"line_of_business":{"type":"string","description":"Stores the lob information."},"company":{"$ref":"#/components/schemas/Company"},"travelers":{"type":"array","description":"Stores the traveler information.","items":{"$ref":"#/components/schemas/Traveler"}}},"required":["company","line_of_business","travelers"]},"Company":{"description":"Stores the company information.","properties":{"id":{"type":"integer","format":"int32","description":"Stores the company id"},"point_of_sale":{"type":"string","description":"Stores the point of sale"}},"required":["id","point_of_sale"]},"CustomDataField":{"description":"Stores CDF information","properties":{"name":{"type":"string","description":"Stores the cdf name"},"value":{"type":"string","description":"Stores the cdf value"}},"required":["name","value"]},"Price":{"description":"Price of the booking.","properties":{"currency":{"type":"string"},"amount":{"type":"number","format":"double"}}},"Traveler":{"description":"Stores the traveler information.","properties":{"email_id":{"type":"string","description":"Stores Traveler Email"},"price":{"$ref":"#/components/schemas/Price"},"custom_data_fields":{"type":"array","description":"Stores CDF information","items":{"$ref":"#/components/schemas/CustomDataField"}},"guest_traveler":{"type":"boolean"}},"required":["custom_data_fields","email_id","price"]},"ExternalApprovalDetail":{"properties":{"level":{"type":"string","description":"denotes approver level","enum":["LEVEL_ONE","LEVEL_TWO"]},"required":{"type":"boolean","description":"denotes whether approver is required or not"},"approvers":{"type":"array","description":"denotes list of approver tuids","items":{"type":"string","description":"denotes list of approver tuids"}}}},"ExternalApprovalDetailsResponse":{"properties":{"approval_details":{"type":"array","items":{"$ref":"#/components/schemas/ExternalApprovalDetail"}}}}}}}