@rippling/rippling-sdk 0.2.0-alpha.107 → 0.2.0-alpha.108

package/src/resources/card-transactions.ts

@@ -0,0 +1,718 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as BusinessPartnersAPI from './business-partners';
+import { APIPromise } from '../core/api-promise';
+import { PageCursorURL, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class CardTransactions extends APIResource {
+  /**
+   * A list of card transactions.
+   *
+   * - Requires: `Internal Testing`
+   * - Filterable fields: `worker_id`, `transaction_date`, `entity_id`, `vendor_id`,
+   *   `category_id`, `transaction_type`, `card_id`
+   * - Sortable fields: `id`, `created_at`, `updated_at`, `transaction_date`
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * GET /card-transactions/?filter=filter&order_by=order_by&limit=50&cursor=cursor HTTP/1.1
+   * Host: rest.ripplingapis.com
+   * Accept: application/json
+   * Rippling-Api-Version: 2024-08-01
+   *
+   * HTTP/1.1 200 OK
+   * Content-Type: application/json
+   *
+   * {
+   *   "__meta": {
+   *     "redacted_fields": [
+   *       {
+   *         "name": "date_of_birth",
+   *         "reason": "Insufficient entitlements"
+   *       }
+   *     ]
+   *   },
+   *   "results": [
+   *     {
+   *       "id": "string",
+   *       "created_at": "string",
+   *       "updated_at": "string",
+   *       "worker_id": "string",
+   *       "company_amount": {
+   *         "currency_type": "string",
+   *         "value": "string"
+   *       },
+   *       "merchant_amount": {
+   *         "currency_type": "string",
+   *         "value": "string"
+   *       },
+   *       "transaction_date": "string",
+   *       "accounting_date": "string",
+   *       "gl_sync_state": "NOT_FINALIZED",
+   *       "approval_status": "DRAFT",
+   *       "entity_id": "string",
+   *       "vendor": {
+   *         "id": "string",
+   *         "name": "string"
+   *       },
+   *       "gl_vendor": {
+   *         "id": "string",
+   *         "name": "string",
+   *         "gl_vendor_id": "string"
+   *       },
+   *       "memo": "string",
+   *       "receipt": "string",
+   *       "attachments": [
+   *         "string"
+   *       ],
+   *       "line_items": [
+   *         {}
+   *       ],
+   *       "transaction_type": "CARD_TRANSACTION",
+   *       "authorization_state": "PENDING",
+   *       "card_id": "string"
+   *     }
+   *   ],
+   *   "next_link": "string"
+   * }
+   * ```
+   */
+  list(
+    query: CardTransactionListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CardTransactionListResponsesPageCursorURL, CardTransactionListResponse> {
+    return this._client.getAPIList('/card-transactions/', PageCursorURL<CardTransactionListResponse>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Retrieve a specific card transaction
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * GET /card-transactions/{id}/ HTTP/1.1
+   * Host: rest.ripplingapis.com
+   * Accept: application/json
+   * Rippling-Api-Version: 2024-08-01
+   *
+   * HTTP/1.1 200 OK
+   * Content-Type: application/json
+   *
+   * {
+   *   "__meta": {
+   *     "redacted_fields": [
+   *       {}
+   *     ]
+   *   }
+   * }
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<CardTransactionRetrieveResponse> {
+    return this._client.get(path`/card-transactions/${id}/`, options);
+  }
+}
+
+export type CardTransactionListResponsesPageCursorURL = PageCursorURL<CardTransactionListResponse>;
+
+/**
+ * A Spend card transaction or authorization the caller can see.
+ *
+ *     An authorization is a pending hold the card network places at the time of purchase. A card transaction
+ *     is the posted charge. List returns both; retrieve returns one by ID. A transaction the
+ *     caller cannot see returns 404, the same as one that does not exist.
+ */
+export interface CardTransactionListResponse {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * Date the transaction is booked in the accounting system, as an ISO 8601 date
+   * (YYYY-MM-DD).
+   */
+  accounting_date?: string;
+
+  /**
+   * Approval status of the transaction. `DRAFT`: not submitted for approval.
+   * `PENDING`: awaiting required information or submission before approval.
+   * `REQUESTED`: submitted and awaiting approval. `APPROVED`: approved. `REJECTED`:
+   * rejected. `FINALIZED`: finalized for payment. `ACTIONED`: payment or
+   * reimbursement completed. `CANCELLED`: cancelled. `FAILED`: payment failed. Null
+   * for card authorizations.
+   */
+  approval_status?:
+    | 'DRAFT'
+    | 'PENDING'
+    | 'REQUESTED'
+    | 'APPROVED'
+    | 'REJECTED'
+    | 'FINALIZED'
+    | 'ACTIONED'
+    | 'CANCELLED'
+    | 'FAILED';
+
+  /**
+   * URLs of other attached files.
+   */
+  attachments?: Array<string>;
+
+  /**
+   * State of the card authorization. `PENDING`: an active hold awaiting completion.
+   * `CLOSED`: the authorization completed and the charge posted. `REVERSED`: the
+   * authorization was reversed and the hold released. `EXPIRED`: the hold expired
+   * without completion. Null for posted card transactions.
+   */
+  authorization_state?: 'PENDING' | 'CLOSED' | 'REVERSED' | 'EXPIRED';
+
+  /**
+   * ID of the Spend card used. No public API is currently available to retrieve this
+   * card.
+   */
+  card_id?: string;
+
+  /**
+   * Amount in the company's headquarters currency. The `value` is a decimal string.
+   */
+  company_amount?: CardTransactionListResponse.CompanyAmount;
+
+  /**
+   * ID of the legal entity the transaction belongs to. Use it with
+   * `/company-legal-entities/{id}/`.
+   */
+  entity_id?: string;
+
+  /**
+   * State of the sync to the accounting system. `NOT_FINALIZED`: not ready for
+   * accounting review. `FOR_REVIEW`: ready for accounting review. `PENDING_SYNC`:
+   * sync is in progress. `SYNCED`: synced to the accounting system. `ERROR`: sync
+   * failed. `DO_NOT_SYNC`: marked to be excluded from sync. `EXPORTED`: exported for
+   * accounting. `NOT_SYNCABLE`: this record cannot be synced. `AUTO_SYNC`: ready to
+   * be synced automatically. Null when no sync state is set.
+   */
+  gl_sync_state?:
+    | 'NOT_FINALIZED'
+    | 'FOR_REVIEW'
+    | 'PENDING_SYNC'
+    | 'SYNCED'
+    | 'ERROR'
+    | 'DO_NOT_SYNC'
+    | 'EXPORTED'
+    | 'NOT_SYNCABLE'
+    | 'AUTO_SYNC';
+
+  /**
+   * Vendor in the connected accounting system.
+   */
+  gl_vendor?: CardTransactionListResponse.GlVendor;
+
+  /**
+   * Category splits of the transaction amount.
+   */
+  line_items?: Array<CardTransactionListResponse.LineItem>;
+
+  /**
+   * Memo entered on the transaction.
+   */
+  memo?: string;
+
+  /**
+   * Amount charged by the merchant, in the merchant currency. The `value` is a
+   * decimal string.
+   */
+  merchant_amount?: CardTransactionListResponse.MerchantAmount;
+
+  /**
+   * URL of the receipt file.
+   */
+  receipt?: string;
+
+  /**
+   * When the purchase or authorization happened, as an ISO 8601 date-time in UTC.
+   */
+  transaction_date?: string;
+
+  /**
+   * `CARD_TRANSACTION`: a posted card charge. `CARD_AUTHORIZATION`: a hold placed by
+   * the card network before the charge posts.
+   */
+  transaction_type?: 'CARD_TRANSACTION' | 'CARD_AUTHORIZATION';
+
+  /**
+   * Vendor the purchase was made from.
+   */
+  vendor?: CardTransactionListResponse.Vendor;
+
+  /**
+   * ID of the worker who made the transaction. Use it with `/workers/{id}/`.
+   */
+  worker_id?: string;
+}
+
+export namespace CardTransactionListResponse {
+  /**
+   * Amount in the company's headquarters currency. The `value` is a decimal string.
+   */
+  export interface CompanyAmount {
+    /**
+     * The currency type, ex: USD, EUR, etc.
+     */
+    currency_type?: string;
+
+    /**
+     * The decimal amount for the currency.
+     */
+    value?: number;
+  }
+
+  /**
+   * Vendor in the connected accounting system.
+   */
+  export interface GlVendor {
+    /**
+     * ID of the accounting vendor in Rippling.
+     */
+    id?: string;
+
+    /**
+     * ID of the vendor in the accounting system.
+     */
+    gl_vendor_id?: string;
+
+    /**
+     * Name of the vendor in the accounting system.
+     */
+    name?: string;
+  }
+
+  export interface LineItem {
+    /**
+     * Amount of this split, in the merchant currency. The `value` is a decimal string.
+     */
+    amount?: LineItem.Amount;
+
+    /**
+     * ID of the Spend category assigned to this split. No public API is currently
+     * available to retrieve this category; its name is in `category_name`.
+     */
+    category_id?: string;
+
+    /**
+     * Name of the spend category.
+     */
+    category_name?: string;
+
+    /**
+     * Selected dimension values, keyed by dimension ID. Includes department and work
+     * location.
+     */
+    dimension_choices?: { [key: string]: LineItem.DimensionChoices };
+
+    /**
+     * Whether this split is billed to `gl_customer` in the accounting system.
+     * `BILLABLE` means it is billed, `NOT_BILLABLE` means it is not. Null when not
+     * set.
+     */
+    gl_billable?: 'BILLABLE' | 'NOT_BILLABLE';
+
+    /**
+     * ID of the customer record in the connected accounting integration. No public
+     * Rippling API is currently available to retrieve this accounting customer.
+     */
+    gl_customer?: string;
+
+    /**
+     * Memo entered on this split.
+     */
+    memo?: string;
+  }
+
+  export namespace LineItem {
+    /**
+     * Amount of this split, in the merchant currency. The `value` is a decimal string.
+     */
+    export interface Amount {
+      /**
+       * The currency type, ex: USD, EUR, etc.
+       */
+      currency_type?: string;
+
+      /**
+       * The decimal amount for the currency.
+       */
+      value?: number;
+    }
+
+    export interface DimensionChoices {
+      /**
+       * Name of the dimension, such as Department.
+       */
+      dimension_name?: string;
+
+      /**
+       * Display name of the selected dimension value.
+       */
+      label?: string;
+
+      /**
+       * ID of the selected dimension value.
+       */
+      value?: string;
+    }
+  }
+
+  /**
+   * Amount charged by the merchant, in the merchant currency. The `value` is a
+   * decimal string.
+   */
+  export interface MerchantAmount {
+    /**
+     * The currency type, ex: USD, EUR, etc.
+     */
+    currency_type?: string;
+
+    /**
+     * The decimal amount for the currency.
+     */
+    value?: number;
+  }
+
+  /**
+   * Vendor the purchase was made from.
+   */
+  export interface Vendor {
+    /**
+     * ID of the vendor.
+     */
+    id?: string;
+
+    /**
+     * Name of the vendor.
+     */
+    name?: string;
+  }
+}
+
+/**
+ * Meta information for the response.
+ */
+export interface CardTransactionRetrieveResponse extends BusinessPartnersAPI.Meta {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * Date the transaction is booked in the accounting system, as an ISO 8601 date
+   * (YYYY-MM-DD).
+   */
+  accounting_date?: string;
+
+  /**
+   * Approval status of the transaction. `DRAFT`: not submitted for approval.
+   * `PENDING`: awaiting required information or submission before approval.
+   * `REQUESTED`: submitted and awaiting approval. `APPROVED`: approved. `REJECTED`:
+   * rejected. `FINALIZED`: finalized for payment. `ACTIONED`: payment or
+   * reimbursement completed. `CANCELLED`: cancelled. `FAILED`: payment failed. Null
+   * for card authorizations.
+   */
+  approval_status?:
+    | 'DRAFT'
+    | 'PENDING'
+    | 'REQUESTED'
+    | 'APPROVED'
+    | 'REJECTED'
+    | 'FINALIZED'
+    | 'ACTIONED'
+    | 'CANCELLED'
+    | 'FAILED';
+
+  /**
+   * URLs of other attached files.
+   */
+  attachments?: Array<string>;
+
+  /**
+   * State of the card authorization. `PENDING`: an active hold awaiting completion.
+   * `CLOSED`: the authorization completed and the charge posted. `REVERSED`: the
+   * authorization was reversed and the hold released. `EXPIRED`: the hold expired
+   * without completion. Null for posted card transactions.
+   */
+  authorization_state?: 'PENDING' | 'CLOSED' | 'REVERSED' | 'EXPIRED';
+
+  /**
+   * ID of the Spend card used. No public API is currently available to retrieve this
+   * card.
+   */
+  card_id?: string;
+
+  /**
+   * Amount in the company's headquarters currency. The `value` is a decimal string.
+   */
+  company_amount?: CardTransactionRetrieveResponse.CompanyAmount;
+
+  /**
+   * ID of the legal entity the transaction belongs to. Use it with
+   * `/company-legal-entities/{id}/`.
+   */
+  entity_id?: string;
+
+  /**
+   * State of the sync to the accounting system. `NOT_FINALIZED`: not ready for
+   * accounting review. `FOR_REVIEW`: ready for accounting review. `PENDING_SYNC`:
+   * sync is in progress. `SYNCED`: synced to the accounting system. `ERROR`: sync
+   * failed. `DO_NOT_SYNC`: marked to be excluded from sync. `EXPORTED`: exported for
+   * accounting. `NOT_SYNCABLE`: this record cannot be synced. `AUTO_SYNC`: ready to
+   * be synced automatically. Null when no sync state is set.
+   */
+  gl_sync_state?:
+    | 'NOT_FINALIZED'
+    | 'FOR_REVIEW'
+    | 'PENDING_SYNC'
+    | 'SYNCED'
+    | 'ERROR'
+    | 'DO_NOT_SYNC'
+    | 'EXPORTED'
+    | 'NOT_SYNCABLE'
+    | 'AUTO_SYNC';
+
+  /**
+   * Vendor in the connected accounting system.
+   */
+  gl_vendor?: CardTransactionRetrieveResponse.GlVendor;
+
+  /**
+   * Category splits of the transaction amount.
+   */
+  line_items?: Array<CardTransactionRetrieveResponse.LineItem>;
+
+  /**
+   * Memo entered on the transaction.
+   */
+  memo?: string;
+
+  /**
+   * Amount charged by the merchant, in the merchant currency. The `value` is a
+   * decimal string.
+   */
+  merchant_amount?: CardTransactionRetrieveResponse.MerchantAmount;
+
+  /**
+   * URL of the receipt file.
+   */
+  receipt?: string;
+
+  /**
+   * When the purchase or authorization happened, as an ISO 8601 date-time in UTC.
+   */
+  transaction_date?: string;
+
+  /**
+   * `CARD_TRANSACTION`: a posted card charge. `CARD_AUTHORIZATION`: a hold placed by
+   * the card network before the charge posts.
+   */
+  transaction_type?: 'CARD_TRANSACTION' | 'CARD_AUTHORIZATION';
+
+  /**
+   * Vendor the purchase was made from.
+   */
+  vendor?: CardTransactionRetrieveResponse.Vendor;
+
+  /**
+   * ID of the worker who made the transaction. Use it with `/workers/{id}/`.
+   */
+  worker_id?: string;
+}
+
+export namespace CardTransactionRetrieveResponse {
+  /**
+   * Amount in the company's headquarters currency. The `value` is a decimal string.
+   */
+  export interface CompanyAmount {
+    /**
+     * The currency type, ex: USD, EUR, etc.
+     */
+    currency_type?: string;
+
+    /**
+     * The decimal amount for the currency.
+     */
+    value?: number;
+  }
+
+  /**
+   * Vendor in the connected accounting system.
+   */
+  export interface GlVendor {
+    /**
+     * ID of the accounting vendor in Rippling.
+     */
+    id?: string;
+
+    /**
+     * ID of the vendor in the accounting system.
+     */
+    gl_vendor_id?: string;
+
+    /**
+     * Name of the vendor in the accounting system.
+     */
+    name?: string;
+  }
+
+  export interface LineItem {
+    /**
+     * Amount of this split, in the merchant currency. The `value` is a decimal string.
+     */
+    amount?: LineItem.Amount;
+
+    /**
+     * ID of the Spend category assigned to this split. No public API is currently
+     * available to retrieve this category; its name is in `category_name`.
+     */
+    category_id?: string;
+
+    /**
+     * Name of the spend category.
+     */
+    category_name?: string;
+
+    /**
+     * Selected dimension values, keyed by dimension ID. Includes department and work
+     * location.
+     */
+    dimension_choices?: { [key: string]: LineItem.DimensionChoices };
+
+    /**
+     * Whether this split is billed to `gl_customer` in the accounting system.
+     * `BILLABLE` means it is billed, `NOT_BILLABLE` means it is not. Null when not
+     * set.
+     */
+    gl_billable?: 'BILLABLE' | 'NOT_BILLABLE';
+
+    /**
+     * ID of the customer record in the connected accounting integration. No public
+     * Rippling API is currently available to retrieve this accounting customer.
+     */
+    gl_customer?: string;
+
+    /**
+     * Memo entered on this split.
+     */
+    memo?: string;
+  }
+
+  export namespace LineItem {
+    /**
+     * Amount of this split, in the merchant currency. The `value` is a decimal string.
+     */
+    export interface Amount {
+      /**
+       * The currency type, ex: USD, EUR, etc.
+       */
+      currency_type?: string;
+
+      /**
+       * The decimal amount for the currency.
+       */
+      value?: number;
+    }
+
+    export interface DimensionChoices {
+      /**
+       * Name of the dimension, such as Department.
+       */
+      dimension_name?: string;
+
+      /**
+       * Display name of the selected dimension value.
+       */
+      label?: string;
+
+      /**
+       * ID of the selected dimension value.
+       */
+      value?: string;
+    }
+  }
+
+  /**
+   * Amount charged by the merchant, in the merchant currency. The `value` is a
+   * decimal string.
+   */
+  export interface MerchantAmount {
+    /**
+     * The currency type, ex: USD, EUR, etc.
+     */
+    currency_type?: string;
+
+    /**
+     * The decimal amount for the currency.
+     */
+    value?: number;
+  }
+
+  /**
+   * Vendor the purchase was made from.
+   */
+  export interface Vendor {
+    /**
+     * ID of the vendor.
+     */
+    id?: string;
+
+    /**
+     * Name of the vendor.
+     */
+    name?: string;
+  }
+}
+
+export interface CardTransactionListParams {
+  cursor?: string;
+
+  filter?: string;
+
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
+  order_by?: string;
+}
+
+export declare namespace CardTransactions {
+  export {
+    type CardTransactionListResponse as CardTransactionListResponse,
+    type CardTransactionRetrieveResponse as CardTransactionRetrieveResponse,
+    type CardTransactionListResponsesPageCursorURL as CardTransactionListResponsesPageCursorURL,
+    type CardTransactionListParams as CardTransactionListParams,
+  };
+}