@gojinko/api-client 2.14.0 → 2.16.0

package/public-api.yaml

@@ -14,6 +14,56 @@ components:
       type: http
       scheme: bearer
   schemas:
+    AgentPaymentSubmitRequest:
+      type: object
+      properties:
+        trip_id:
+          type: string
+          example: trip_1048576
+        shared_payment_token:
+          type: string
+          example: spt_1Nq8L2eZvKYlo2C0
+      required:
+        - trip_id
+        - shared_payment_token
+    AgentPaymentSubmitResponse:
+      type: object
+      properties:
+        fulfillment_cart_id:
+          type: integer
+        status:
+          type: string
+          example: processing
+        payment_verified:
+          type: boolean
+        message:
+          type: string
+        checkout_url:
+          type: string
+          description: Hosted-checkout fallback, present only on a 3DS step-up / decline.
+        recap_token:
+          type: string
+    AgentSPTParams:
+      type: object
+      properties:
+        max_amount:
+          type: integer
+          description: Locked cart total in the smallest currency unit — scope the Shared
+            Payment Token to at most this.
+          example: 259449
+        currency:
+          type: string
+          example: EUR
+        stripe_profile:
+          type: string
+          description: Stripe Agentic Commerce network_business_profile id the SPT is
+            granted against. Empty until the preview account is provisioned.
+        expires_at:
+          type: string
+          example: 2026-06-10T13:04:56Z
+      required:
+        - max_amount
+        - currency
     AncillaryOffer:
       type: object
       description: A purchasable ancillary (bag, seat, bundle, ...) offered on a trip item.
@@ -51,6 +101,49 @@ components:
           type: integer
       required:
         - offer_id
+    CheckoutRequest:
+      type: object
+      properties:
+        trip_id:
+          type: string
+          example: trip_1048576
+      required:
+        - trip_id
+    CheckoutResponse:
+      type: object
+      properties:
+        session_id:
+          type: string
+          example: cs_1048576
+        checkout_url:
+          type: string
+          example: https://book.gojinko.com/checkout?sid=1048576
+        status:
+          type: string
+          example: pending_payment
+        expires_at:
+          type: string
+          example: 2026-06-01T13:04:56Z
+        total_amount:
+          type: object
+          properties:
+            amount:
+              type: number
+              example: 318.4
+            value:
+              type: number
+            currency:
+              type: string
+              example: USD
+            decimal_places:
+              type: integer
+              example: 2
+        items:
+          type: array
+          items:
+            nullable: true
+        agent_spt_params:
+          $ref: "#/components/schemas/AgentSPTParams"
     HealthResponse:
       type: object
       properties:
@@ -911,39 +1004,6 @@ components:
         - trip_id
         - item_id
         - selections
-    BookResponse:
-      type: object
-      properties:
-        session_id:
-          type: string
-        checkout_url:
-          type: string
-        status:
-          type: string
-        expires_at:
-          type: string
-        total_amount:
-          type: object
-          properties:
-            amount:
-              type: number
-            value:
-              type: number
-            currency:
-              type: string
-            decimal_places:
-              type: integer
-        items:
-          type: array
-          items:
-            nullable: true
-    BookRequest:
-      type: object
-      properties:
-        trip_id:
-          type: string
-      required:
-        - trip_id
     HotelSearchResponse:
       type: object
       properties:
@@ -1510,8 +1570,275 @@ components:
           type: string
         last_name:
           type: string
-  parameters: {}
+    AnalysisType:
+      type: string
+      enum: [snapshot, trend]
+    TravelPeriod:
+      type: string
+      enum: [Summer, Winter, Christmas, Easter, Next30Days, Next90Days, Custom]
+    TravelerType:
+      type: string
+      enum: [Solo, Couple, Group, Family]
+    TripType:
+      type: string
+      enum: [One-Way, Round-Trip]
+    DestinationRow:
+      type: object
+      required: [destination]
+      properties:
+        rank:
+          type: integer
+        destination:
+          type: string
+        share:
+          type: number
+          format: double
+    MarketRow:
+      type: object
+      required: [market]
+      properties:
+        rank:
+          type: integer
+        market:
+          type: string
+        share:
+          type: number
+          format: double
+    AudienceRow:
+      type: object
+      required: [audience]
+      properties:
+        rank:
+          type: integer
+        audience:
+          type: string
+        share:
+          type: number
+          format: double
+    DestinationResponse:
+      type: object
+      required: [analysis_type, rows]
+      properties:
+        analysis_type:
+          $ref: "#/components/schemas/AnalysisType"
+        rows:
+          type: array
+          items:
+            $ref: "#/components/schemas/DestinationRow"
+    MarketResponse:
+      type: object
+      required: [analysis_type, rows]
+      properties:
+        analysis_type:
+          $ref: "#/components/schemas/AnalysisType"
+        rows:
+          type: array
+          items:
+            $ref: "#/components/schemas/MarketRow"
+    AudienceResponse:
+      type: object
+      required: [analysis_type, rows]
+      properties:
+        analysis_type:
+          $ref: "#/components/schemas/AnalysisType"
+        rows:
+          type: array
+          items:
+            $ref: "#/components/schemas/AudienceRow"
+  parameters:
+    analysis:
+      name: analysis
+      in: query
+      required: true
+      description: Analysis mode. `trend` is accepted but currently returns snapshot-shaped data.
+      schema:
+        $ref: "#/components/schemas/AnalysisType"
+    originMarket:
+      name: origin_market
+      in: query
+      required: false
+      description: "Origin market filter as <Level>:<Code>, e.g. Country:US or City:NYC."
+      schema:
+        type: string
+    destinationFilter:
+      name: destination
+      in: query
+      required: false
+      description: "Optional destination filter as <Level>:<Code>, e.g. Country:TH."
+      schema:
+        type: string
+    destinationRequired:
+      name: destination
+      in: query
+      required: true
+      description: "Destination as <Level>:<Code>, e.g. Country:TH. Required for this endpoint."
+      schema:
+        type: string
+    travelPeriod:
+      name: travel_period
+      in: query
+      required: false
+      description: Named departure window (defaults to Next90Days server-side).
+      schema:
+        $ref: "#/components/schemas/TravelPeriod"
+    departureDateFrom:
+      name: departure_date_from
+      in: query
+      required: false
+      description: "Start of departure window (YYYY-MM-DD). Required when travel_period=Custom."
+      schema:
+        type: string
+        format: date
+    departureDateTo:
+      name: departure_date_to
+      in: query
+      required: false
+      description: "End of departure window (YYYY-MM-DD). Required when travel_period=Custom."
+      schema:
+        type: string
+        format: date
+    travelerType:
+      name: traveler_type
+      in: query
+      required: false
+      description: Optional traveler-type filter.
+      schema:
+        $ref: "#/components/schemas/TravelerType"
+    tripType:
+      name: trip_type
+      in: query
+      required: false
+      description: Optional trip-type filter.
+      schema:
+        $ref: "#/components/schemas/TripType"
+    limit:
+      name: limit
+      in: query
+      required: false
+      description: Max rows (1-200, default 20).
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 200
+        default: 20
 paths:
+  /v1/destination:
+    get:
+      tags:
+        - demand
+      summary: Top destinations by search demand
+      description: >-
+        Most-searched destinations by de-sampled request share. `destination` is optional
+        (omit to rank all destinations); set `origin_market` to scope to one source market.
+      security:
+        - ApiKeyAuth: []
+        - BearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/analysis"
+        - $ref: "#/components/parameters/originMarket"
+        - $ref: "#/components/parameters/destinationFilter"
+        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/departureDateFrom"
+        - $ref: "#/components/parameters/departureDateTo"
+        - $ref: "#/components/parameters/travelerType"
+        - $ref: "#/components/parameters/tripType"
+        - $ref: "#/components/parameters/limit"
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DestinationResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/market:
+    get:
+      tags:
+        - demand
+      summary: Top source markets for a destination
+      description: Which source markets generate the most demand for a given destination.
+      security:
+        - ApiKeyAuth: []
+        - BearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/analysis"
+        - $ref: "#/components/parameters/destinationRequired"
+        - $ref: "#/components/parameters/originMarket"
+        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/departureDateFrom"
+        - $ref: "#/components/parameters/departureDateTo"
+        - $ref: "#/components/parameters/travelerType"
+        - $ref: "#/components/parameters/tripType"
+        - $ref: "#/components/parameters/limit"
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MarketResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/audience:
+    get:
+      tags:
+        - demand
+      summary: Traveler-type mix for a destination
+      description: >-
+        Traveler-type composition (Solo / Couple / Family / Group) of demand for a destination.
+        `traveler_type` is not a valid filter here — this endpoint buckets by it.
+      security:
+        - ApiKeyAuth: []
+        - BearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/analysis"
+        - $ref: "#/components/parameters/destinationRequired"
+        - $ref: "#/components/parameters/originMarket"
+        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/departureDateFrom"
+        - $ref: "#/components/parameters/departureDateTo"
+        - $ref: "#/components/parameters/tripType"
+        - $ref: "#/components/parameters/limit"
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AudienceResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
   /health:
     get:
       tags:
@@ -1524,6 +1851,159 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/HealthResponse"
+  /v1/agent_payment/submit:
+    post:
+      tags:
+        - Pricing & booking
+      summary: Submit an agent payment — present trip_id + a Shared Payment Token to
+        schedule + authorize the booking; returns a checkout_url fallback if
+        customer action (3DS) is required
+      security:
+        - ApiKeyAuth: []
+        - BearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AgentPaymentSubmitRequest"
+      responses:
+        "200":
+          description: Authorization result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentPaymentSubmitResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: BAD_REQUEST
+                  message: Malformed JSON in request body.
+                  doc_url: https://docs.gojinko.com/concepts/errors
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: AUTH_REQUIRED
+                  message: Invalid or expired API key.
+                  doc_url: https://docs.gojinko.com/api-reference/authentication
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: BAD_REQUEST
+                  message: "origins: origins is required; trip_type: trip_type is required"
+                  doc_url: https://docs.gojinko.com/concepts/errors
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: RATE_LIMITED
+                  message: Rate limit or quota exceeded.
+                  doc_url: https://docs.gojinko.com/concepts/errors
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: UPSTREAM_ERROR
+                  message: Upstream travel provider returned an error. Please retry.
+                  doc_url: https://docs.gojinko.com/concepts/errors
+  /v1/checkout:
+    post:
+      tags:
+        - Pricing & booking
+      summary: Checkout a trip — returns a checkout URL the user opens to pay, plus
+        the Shared Payment Token params an agent can use to pay programmatically
+      security:
+        - ApiKeyAuth: []
+        - BearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CheckoutRequest"
+      responses:
+        "200":
+          description: Checkout session
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CheckoutResponse"
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: BAD_REQUEST
+                  message: Malformed JSON in request body.
+                  doc_url: https://docs.gojinko.com/concepts/errors
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: AUTH_REQUIRED
+                  message: Invalid or expired API key.
+                  doc_url: https://docs.gojinko.com/api-reference/authentication
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: BAD_REQUEST
+                  message: "origins: origins is required; trip_type: trip_type is required"
+                  doc_url: https://docs.gojinko.com/concepts/errors
+        "429":
+          description: Rate limit or quota exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: RATE_LIMITED
+                  message: Rate limit or quota exceeded.
+                  doc_url: https://docs.gojinko.com/concepts/errors
+        "502":
+          description: Upstream service error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: UPSTREAM_ERROR
+                  message: Upstream travel provider returned an error. Please retry.
+                  doc_url: https://docs.gojinko.com/concepts/errors
   /v1/find_destination:
     post:
       tags:
@@ -2044,8 +2524,9 @@ paths:
   /v1/book:
     post:
       tags:
-        - cart
-      summary: Checkout a trip (returns a payment/checkout URL)
+        - Pricing & booking
+      summary: DEPRECATED — use /checkout. Alias retained for backward compatibility.
+      deprecated: true
       security:
         - ApiKeyAuth: []
         - BearerAuth: []
@@ -2053,44 +2534,69 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/BookRequest"
+              $ref: "#/components/schemas/CheckoutRequest"
       responses:
         "200":
           description: Checkout session
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/BookResponse"
+                $ref: "#/components/schemas/CheckoutResponse"
         "400":
           description: Bad request
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: BAD_REQUEST
+                  message: Malformed JSON in request body.
+                  doc_url: https://docs.gojinko.com/concepts/errors
         "401":
           description: Authentication required
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: AUTH_REQUIRED
+                  message: Invalid or expired API key.
+                  doc_url: https://docs.gojinko.com/api-reference/authentication
         "422":
           description: Validation error
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: BAD_REQUEST
+                  message: "origins: origins is required; trip_type: trip_type is required"
+                  doc_url: https://docs.gojinko.com/concepts/errors
         "429":
           description: Rate limit or quota exceeded
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: RATE_LIMITED
+                  message: Rate limit or quota exceeded.
+                  doc_url: https://docs.gojinko.com/concepts/errors
         "502":
           description: Upstream service error
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+              example:
+                error:
+                  code: UPSTREAM_ERROR
+                  message: Upstream travel provider returned an error. Please retry.
+                  doc_url: https://docs.gojinko.com/concepts/errors
   /v1/hotel_search:
     post:
       tags: