API食谱:API任务

本系列API Recipes描述了与开发应用程序相关的API任务，这些应用程序适用于旅行管理公司(TMC)、旅行供应商和需要获取员工旅行相关预订数据的企业。此方法假设您是当前客户或平台合作伙伴。

在你开始之前

检查下面的检查表，以确保您能够执行这个食谱中的任务。要查看参考信息，请单击要点中的链接

获取行程和行程细节:拉行程行程数据

开发人员、差旅供应商和差旅管理公司将希望使用本菜谱中描述的流程。

  • 有了授权的Oauth token，开发人员可以检索用户或用户组的详细行程。通过使用这些数据，开发人员可以创建符合特定地区、地区或国家用户兴趣的应用程序。例如，电视食物地图(TV Food Maps)匹配用户行程中的目的地，通知他们来自《食客》(Diners)、《dri静脉》(dri静脉)和《潜水》(dive)等电视节目的特色餐厅位于用户行程的附近
  • 旅游供应商可以使用这些流程分析行程/行程中的差距，如汽车租赁和酒店住宿，并使用这些信息提供这些服务。如果您想为您的用户提供更好的旅行体验，这是特别有用的
  • 差旅管理公司可以使用这些流程来分析个人或公司的旅行数据、提供旅行者支持服务、Triplink支持或商业智能和分析吗

大多数合作伙伴获取旅行数据的顺序是:

  1. 手动添加一个新的行程。这将创建一个示例行程，允许开发人员通过API检索他们的第一个行程，并使用响应和XSD构建模式或数据结构。
  2. 通过构建一个计划好的流程来根据特定的功能参数轮询行程，从而填充内部系统。
  3. 使用行程列表来获取更多的旅行细节。大多数旅行供应商和TMC会根据日期、时间段或用户来检索旅行细节。

这些过程中的每一个都可以单独使用。例如，如果一个旅行供应商只想获取行程细节，他们可以遵循下面描述的获取行程细节流程。

获得行程清单:

GET Itinerary端点所需的GET行程列表位于官方SAP Concur开发人员页面中在这里．

如果你是一个开发人员，只想获得get Itinerary API，请使用以下流程:

如果您还没有将沙箱配置为获取访问权限，则可以从支持页面发出该请求在这里．记住要包括与您一起在表单中工作的SAP Concur代表的名称。

如果您已经配置了沙箱，那么GET Itinerary端点所需的GET List of Itineraries就位于正式的SAP Concur开发人员页面中在这里．

重要的
  • 使用Itinerary范围。更多的细节在这里．使用搜索词ITINER
  • 使用Web流或Apps Center流身份验证
  • 确保你的约会是最近的

此任务检索在Oauth令牌中指定的旅行者的旅行摘要。这个端点还可以用于获取不同用户、组织或整个公司的旅行细节。当旅行管理公司(TMC)需要代表用户或公司检索旅行列表时，最常使用Get List of Itineraries。

例子:

整个公司(Oauth消费者必须具有Admin用户角色)

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate= {startdate可以}&endDate = {enddate} &_createdAfterDate = {_date} &createdBeforeDate ={日期}&lastModifiedDate ={日期}&bookingType ={类型}&userid_type = login&userid_value =

个人用户(Oauth消费者)

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate= {startdate可以}&endDate = {enddate} &_createdAfterDate = {_date} &createdBeforeDate ={日期}&lastModifiedDate ={日期}&bookingType ={类型}

个人用户(Oauth消费者除外)

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate= {startdate可以}&endDate = {enddate} &_createdAfterDate = {_date} &createdBeforeDate ={日期}&lastModifiedDate ={日期}&bookingType ={类型}&userid_type = login_id&userid_value = {loginID}

可以查看其他示例在这里．

函数参数
的名字 描述
tripId 这次旅行ID
startDate可以= {日期｝ url编码的UTC旅行开始日期。格式:YYYY-MM-DD。如果没有提供查询参数，则开始日期设置为今天的日期—30天。
endDateArunachal Pradesh，= {日期｝ url编码的UTC旅行结束日期。格式:YYYY-MM-DD。如果不提供查询参数，则结束日期设置为今天的日期+ 12个月。
createdAfterDateArunachal Pradesh，= {日期｝ url编码的UTC日期，用于表示创建旅行的时间。查询字符串将返回在该日期或之后创建的行程。与createdafterdate一起使用，用于查找在日期范围内创建的行程。格式:YYYY-MM-DD
createdBeforeDateArunachal Pradesh，= {日期｝ 旅行及其相关预订的最后修改UTC日期。此查询字符串将仅返回行程或其任何关联预订的最后修改日期大于或等于提供的时间的行程
lastModifiedDateArunachal Pradesh，= {日期｝ 这次旅行至少包括一次这种类型的预订。形式:空中，汽车，餐饮，酒店，停车场，铁路，或乘坐
bookingType = {类型｝ 这次旅行至少包括一次这种类型的预订。形式:空中，汽车，餐饮，酒店，停车场，铁路，或乘坐
userid_type = login&userid_value ={loginID} loginID是用户的SAP Concur登录ID。可以发送ALL的userid_value来获取公司所有用户的旅行总结。userid_type和userid_value参数只能在OAuth消费者具有上面列出的用户角色之一的情况下使用。
includeMetadata = true&ItemsPerPage = {数量}和页面= {数量｝ includeMetadata查询参数结合ItemsPerPage和Page查询参数将导致响应被划分为页面。
includeVirtualTrip =1 虚拟旅行是通过“旅行请求”产品进行离线预订的部分。将includeVirtualTrip查询参数设置为1，以便将这些行程包含在列表中
includeCanceledTrips ={真/假} inclecanceledtrips查询参数也将导致请求返回状态为Canceled的行程。

参考样品XML GET Itinerary Details获取请求为指导。

把行程细节

这个过程允许开发人员、差旅供应商和差旅管理公司获得特定行程的详细信息。默认情况下，Oauth消费者应该是旅行的所有者。Get Itinerary端点还可以用于获取Oauth消费者不拥有的行程的详细信息。差旅管理公司使用这个流程代表用户获取差旅细节。这假设TMC已向SAP Concur注册，并拥有一个具有以下用户角色的有效帐户:Professional的Web Services Administrator或Standard的Can administrtor。

函数参数
的名字 描述
｛tripId｝ 必需的。所需行程的标识符
userid_type = login&userid_value ={loginID} loginID是用户的SAP Concur登录ID。可以发送ALL的userid_value来获取公司所有用户的旅行总结。
systemFormat ={格式} systemFormat查询参数可用于指定对不同系统的响应进行格式化。支持的取值为Tripit。

该请求返回一个包含子元素子集的旅程父元素。部分列表如下。已找到完整的列表在这里．

父元素的参数
的名字 描述
BookedByFirstName 预定行程的人的名字。
BookedByLastName 预定行程的人的姓。
BookedVia 这次旅行的预订方法。
CancelComments 行程取消时提供的评论。最大长度为256个字符。
评论 可选的评论。最大长度512个字符。
DateBookedLocal 预定行程的日期，预定地点的当地时间。格式:YYYY-MM-DDThh: mm: ss
DateCreatedUtc 创建此旅行的日期，以UTC为单位。格式:YYYY-MM-DDThh: mm: ss
预订子元素
的名字 描述
BookingSource 此预订的预订来源的名称。预订源是系统用来跟踪预订发生地点的文本名称。
DateBookedLocal 此预订的预订来源的名称。预订源是系统用来跟踪预订发生地点的文本名称。
DateCreatedUtc 以UTC为单位创建预订的日期。格式:YYYY-MM-DDThh: mm: ss
DateModifiedUtc 最后修改预订的日期，以UTC为单位。格式:YYYY-MM-DDThh: mm: ss
FormOfPaymentName 姓名、付款方式为预订。
FormOfPaymentType 付款方式。
PassengerCount 预订的乘客人数。

让旅行的细节

开发者应该建立一个定期的流程，以便在用户登录他们的网站进行预订时，对行程进行民意调查或根据需求获得行程。使用您想要其详细信息的用户的Oauth令牌作为授权，执行以下两步过程:

  1. 为用户获取旅行列表。
  2. 每次获取一个行程的详细信息。

有关如何使用Oauth令牌为用户获取旅行列表的更多信息，请访问在这里．

获取旅行清单请求:

得到https:// {InstanceURL} / api /旅游/旅行/ v1.1HTTP/1．1授权：OAuth{用户访问令牌}接受：应用程序/ xml

您还可以通过使用TripID获得每次旅行的详细信息。Get Trip List响应包括每个旅行的唯一TripID。

示例行程细节请求

得到https:// {InstanceURL} / api /旅游/旅行/ v1.1 / {TripID}HTTP/1．1授权：OAuth{用户访问令牌}接受：应用程序/ xml

参考样品获取旅行ID的旅行详细信息为指导。

重要的

任何行程都不能包含所有可能的元素，因为响应始终是可能返回值的子集。有关完整的响应细节，请查看公开行程XSD．

一旦你有了旅行的细节，寻找那些缺少你的细分类型的旅行。

  • 例如，如果你是TripLink汽车供应商，寻找可能包括航班，但没有租车预订的旅行。

  • 如果你是TripLink酒店供应商，寻找可能包括航班但没有酒店预订的旅行。如果您是定期对行程进行投票，您可以选择向旅行者发送电子邮件，向他们提供您的服务，以添加到他们即将到来的行程中。例如，如果你是TripLink酒店的合作伙伴，你可以选择给旅行者发电子邮件:“如果你想为12月13日的波士顿之旅预订一家酒店，我们在市中心的酒店提供特价。登录这里，为您的旅行添加酒店预订。”

  • 当旅行者登录你的手机应用程序或网站进行预订时，如果你正在检查即将到来的旅行，你可以选择向旅行者提供一份缺少你的细分类型的即将到来的旅行清单。例如，如果你是TripLink汽车供应商，您可以选择提供一个没有租车预订的即将到来的旅行列表，并允许旅行者轻松地将租车添加到该旅行中，使用旅行细节中的信息预先填充取车和落车地点和日期/时间。

在…的情况下用户连接通过SAP Concur平台预订酒店的客户:

  • 如果你的用户下载了电视美食地图，他们会在旅行日期临近时收到一封电子邮件
  • 这封电子邮件将表明，哪些电视节目上的哪些餐厅将在员工下榻的地方附近

先进的信息

这部分的信息是不拟供…使用用户连接开发人员。

行程状况及预订来源

旅行管理公司在获取旅行详情时，会发现GET行程回复中的以下两个要素非常有用:

  • 行程状态:0-已确认;1-代理购票;2 -取消
  • 预订来源(见下表)
行程是如何发送到SAP Concur平台的 BookingOwner BookingSource
手动添加的行程 OpenBookingEmail 手册
行程电邮至plans@concur.com OpenBookingEmail 供应商名称，如果解析器不能确定供应商，则使用Manual
行程电邮至plans@tripit.com TripIt 供应商名称，如果解析器不能确定供应商，则使用Manual
TMC使用Itinerary API发布的行程 ConcurConnectAPI 供应商名称
开放预订供应商使用行程API发布预订。折扣仍然适用。 OpenBookingSupplier 洲际酒店
在Concur Travel(即Cliqbook)或通过代理预订(并发送回Concur Travel)，或通过直接连接。折扣仍然适用于代理商预订。我们无法在API中区分用户通过Concur Travel预订和通过代理预订。我们会在内部追踪 ConcurTravel GDS名称，或直接连接供应商名称
Amadeus e-Travel Management (AeTM)是一个集成了Concur Expense的在线自助预订工具。 AmadeusETravel

订阅和退订

请注意作为我们身份验证基础设施安全改进的一部分，我们决定取消对用户或公司的Profile、Form of Payment和Itinerary的通知，因为它们对OAuth令牌的处理。该功能已于2020年6月取消。

Concur差旅供应商和差旅管理公司可能需要知道如何发布公司通知订阅，以便更改行程。使用下面的信息来指导你。关于这些主题的更多信息可以在SAP Concur Developer Center的资源中找到:订阅或取消订阅通知．

订阅通知，当通过Concur travel预订旅行的员工通过添加、修改或取消旅行计划而更改其旅行计划时，将收到通知邮寄公司通知订阅行程变更请求．

要创建此请求，请使用以下示例作为模板。请注意，请求参数为行程．Request XML字符串还需要公司的管理用户的宣誓令牌。用户必须具有以下用户角色之一:公司管理员(Professional)或Web服务管理员(Web Services Administrator)或标准管理员(Can administrat)。

订阅请求示例:

帖子http://www.concursolutions.com/api/company/v1.0/subscribe?type=itineraryHTTP/1．1授权：OAuth{访问令牌}．..

通知被发送到合作伙伴在应用程序审查期间注册的Postback URL。对于所有通知类型，合作伙伴只能有一个回发URL。通知将包括类型、oauth_token_key、userid_type和userid_value查询参数，指定更新后的用户，如示例所示:

https://postbackurl.com?type=itinerary&oauth_token_key= {oauthtoken} &userid_type = login&userid_value = cm@example.com

虽然响应主体包括一个Notification父元素，但也有几个子元素。

元素 描述
ObjectType 行程
ObjectURI 对象的URI。开发人员可以使用适当的GET端点和ObjectURI来获取旅行的完整细节。
EventDateTime 当事件发生时。格式:YYYY-MM-DDThh: mm: ss
EventType 改变的类型。格式:CREATE、UPDATE、CANCEL
上下文 这还没有使用，但将在未来用于指定行程中的变化。开发人员可以将其与EventType结合使用，以决定如何处理通知。
TripID 旅行的唯一标识符。格式:字符串

取消预定行程变更的示例请求:

https://www.concursolutions.com/api/company/v1.0/unsubscribe?type=itinerary

参考样品邮寄公司通知订阅行程更改回应为指导。