@gojinko/api-client 2.13.0 → 2.15.0

package/public-api.yaml

@@ -14,6 +14,136 @@ 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.
+      properties:
+        offer_id:
+          type: string
+          description: Stable id used to select this ancillary.
+        type:
+          type: string
+          description: Normalized category, e.g. "bag", "seat", "cabin_bag_upgrade", "assistance".
+        label:
+          type: string
+          description: Raw provider label (source of truth). May contain HTML entities and "&" joiners.
+        display_label:
+          type: string
+          description: >-
+            Human-readable label derived from `label` (HTML entities decoded,
+            provider "&" component-joiners normalized to ", "). Prefer this for
+            display; falls back to `label` when absent.
+        description:
+          type: string
+        price_per_unit:
+          type: object
+          properties:
+            amount:
+              type: number
+            currency:
+              type: string
+            decimal_places:
+              type: integer
+        per_pax:
+          type: boolean
+          description: When true the ancillary is priced/selected per passenger.
+        max_quantity:
+          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:
@@ -605,7 +735,7 @@ components:
               available_ancillaries:
                 type: array
                 items:
-                  nullable: true
+                  $ref: "#/components/schemas/AncillaryOffer"
               selected_ancillaries:
                 type: array
                 items:
@@ -747,24 +877,7 @@ components:
               available_ancillaries:
                 type: array
                 items:
-                  type: object
-                  properties:
-                    offer_id:
-                      type: string
-                    type:
-                      type: string
-                    label:
-                      type: string
-                    description:
-                      type: string
-                    price_per_unit:
-                      type: object
-                    per_pax:
-                      type: boolean
-                    max_quantity:
-                      type: integer
-                  required:
-                    - offer_id
+                  $ref: "#/components/schemas/AncillaryOffer"
               selected_ancillaries:
                 type: array
                 items:
@@ -891,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:
@@ -1504,6 +1584,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:
@@ -2024,8 +2257,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: []
@@ -2033,44 +2267,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: