btrz-api-client 8.33.0 → 8.34.0

package/src/endpoints/btrzpay/terminalPayments.js

@@ -5,10 +5,10 @@ const {
 /**
  * Query params for GET /terminal-payments/mit/:id (btrz-api-payments). See get-mit-by-id-handler getSpec().
  * @typedef {Object} TerminalPaymentsMitGetQuery
- * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers
- * @property {string} [branchId] - Branch id where payment started (required for GET)
- * @property {string} [companyId] - Company id where payment started (required for GET)
- * @property {string} [date] - Date when payment started; format dd/mm/yyyy (required for GET)
+ * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers; when omitted, authenticated account is used
+ * @property {string} branchId - Branch id where payment started (required). Example: 00676
+ * @property {string} companyId - Company id where payment started (required). Example: Z890
+ * @property {string} date - Date when payment started; format dd/mm/yyyy (required)
  */
 
 /**
@@ -27,15 +27,15 @@ const {
 function terminalPaymentsFactory({client, internalAuthTokenProvider}) {
   const mit = {
     /**
-     * PUT /terminal-payments/mit/:id - update MIT terminal payment.
+     * PUT /terminal-payments/mit/:terminalPaymentId - complete MIT terminal payment with result from terminal.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Terminal payment id
-     * @param {Object} opts.terminalPayment - Terminal payment payload
-     * @param {TerminalPaymentsMitPutQuery} [opts.query] - Query params (providerId)
+     * @param {string} opts.id - Terminal payment ID (UUID)
+     * @param {{ result?: Object, paymentRequest: Object, orderId: string }} opts.terminalPayment - Terminal payment data (result, paymentRequest, orderId)
+     * @param {TerminalPaymentsMitPutQuery} [opts.query] - Optional providerId
      * @param {Object} [opts.headers] - Optional headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @returns {Promise<import("axios").AxiosResponse<{ terminalPayment: Object }>>} Rejects with 400 (WRONG_DATA, INVALID_TERMINALPAYMENT_ID, INVALID_RESULT_OBJECT, MIT_*), 401, 404 (TERMINALPAYMENT_NOT_FOUND, MIT_PAYMENT_NOT_FOUND), 409 (CANT_UPDATE_ORDER), 500.
      */
     update({token, jwtToken, id, terminalPayment, query = {}, headers}) {
       return client({
@@ -47,14 +47,14 @@ function terminalPaymentsFactory({client, internalAuthTokenProvider}) {
       });
     },
     /**
-     * GET /terminal-payments/mit/:id - get MIT terminal payment.
+     * GET /terminal-payments/mit/:terminalPaymentId - get MIT terminal payment result from MIT servers.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Terminal payment id
-     * @param {TerminalPaymentsMitGetQuery} [opts.query] - Query params (providerId, branchId, companyId, date)
+     * @param {string} opts.id - Terminal payment ID (UUID)
+     * @param {TerminalPaymentsMitGetQuery} opts.query - branchId, companyId, date (required); optional providerId
      * @param {Object} [opts.headers] - Optional headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @returns {Promise<import("axios").AxiosResponse<{ terminalPayment: Object }>>} Rejects with 400 (WRONG_DATA, INVALID_TERMINALPAYMENT_ID, INVALID_DATE, MIT_*), 401, 404 (TERMINALPAYMENT_NOT_FOUND, MIT_PAYMENT_NOT_FOUND), 500.
      */
     get({token, jwtToken, id, query = {}, headers}) {
       return client.get(`/terminal-payments/mit/${id}`, {
@@ -66,14 +66,14 @@ function terminalPaymentsFactory({client, internalAuthTokenProvider}) {
 
   const webhooks = {
     /**
-     * POST /terminal-payments/webhooks/getnet/:providerId - Getnet webhook. API does not accept query params.
+     * POST /terminal-payments/webhooks/getnet/:providerId - Getnet Terminal webhook (inbound). API does not accept query params.
      * @param {Object} opts
-     * @param {Object} opts.data - Request body
-     * @param {string} opts.providerId - Provider id
+     * @param {Object} opts.data - Getnet webhook payload (e.g. TrxResult, TrxReference, userId)
+     * @param {string} opts.providerId - Provider (account) ID for getnet_terminal payment method
      * @param {Object} [opts.headers] - Optional headers
-     * @param {string} [opts.token] - API key
-     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @param {string} [opts.token] - API key (optional when no userId in payload)
+     * @param {string} [opts.jwtToken] - JWT or internal auth (required when userId is in payload)
+     * @returns {Promise<import("axios").AxiosResponse<{ status: string }>>} Rejects with 400 (INVALID_WEBHOOK_PAYLOAD), 401 (when userId present but not authenticated), 404 (PAYMENT_NOT_FOUND_FOR_WEBHOOK_EVENT, PAYMENT_METHOD_NOT_FOUND, USER_NOT_FOUND), 409 (CANT_UPDATE_ORDER), 500.
      */
     getnet({data, providerId, headers = {}, token, jwtToken}) {
       const _headers = token && jwtToken ?

package/src/endpoints/inventory/segments-information-tables.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-len */
 const {
   authorizationHeaders
 } = require("./../endpoints_helpers.js");
@@ -5,7 +6,7 @@ const {
 /**
  * Query params for GET /segments-information-tables/:routeId (btrz-api-inventory-trips). See get-by-id-handler getSpec().
  * @typedef {Object} SegmentsInformationTablesQuery
- * @property {string} [providerId] - Provider id of the route if not the same as the user making the request (ObjectId format)
+ * @property {string} [providerId] - Provider/account id of the route when different from the authenticated user (24-char hex ObjectId)
  */
 
 /**
@@ -17,18 +18,23 @@ const {
  */
 function segmentInformationTableFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /segments-information-tables/:routeId - get segments information table by route id.
+   * GET /segments-information-tables/:routeId — Returns segment information tables for the route (distances, durations, durationsHHMM between stops). Requires BETTEREZ_APP audience.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.routeId - Route id (ObjectId format)
-   * @param {SegmentsInformationTablesQuery} [opts.query] - Query params (providerId)
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {string} opts.routeId - Route id (24-char hex ObjectId)
+   * @param {SegmentsInformationTablesQuery} [opts.query] - Optional providerId
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ segmentInformationTables: { distances: Object, durations: Object, durationsHHMM: Object } }>>}
+   * @throws 400 INVALID_ROUTE_ID — routeId not 24 hex characters
+   * @throws 401 Unauthorized
+   * @throws 404 ROUTE_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function get({token, jwtToken, routeId, query = {}, headers}) {
     return client({
       url: `/segments-information-tables/${routeId}`,
+      method: "get",
       params: query,
       headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
     });

package/src/endpoints/inventory/trip-ids.js

@@ -0,0 +1,54 @@
+/* eslint-disable max-len */
+const {authorizationHeaders} = require("./../endpoints_helpers.js");
+
+/**
+ * Body for POST /direct-trip-ids (btrz-api-inventory-trips). See TripIdPostData in post-handler getSpec().
+ * @typedef {Object} TripIdPostData
+ * @property {string} providerId - Provider id (24-char hex ObjectId)
+ * @property {string} routeId - Route id (24-char hex ObjectId)
+ * @property {string} scheduleId - Schedule id
+ * @property {string} departureDate - Departure date (yyyy-mm-dd)
+ * @property {string} fareIds - Fare ids and quantities (e.g. fareId:qty)
+ * @property {string} channel - One of: backoffice, agency-backoffice, websales, agency-websales
+ * @property {string} productId - Product id (24-char hex ObjectId)
+ * @property {string} originId - Origin station id (24-char hex ObjectId)
+ * @property {string} destinationId - Destination station id (24-char hex ObjectId)
+ * @property {string} [currency] - ISO currency code (optional, for multicurrency)
+ */
+
+/**
+ * Factory for trip-ids API (btrz-api-inventory-trips).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ create: function }}
+ */
+function tripIdsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * POST /direct-trip-ids — Resolve trip parameters to a trip id. Runs trip search internally and returns the matching trip's base64 id (or null). Body can be TripIdPostData or { tripId: TripIdPostData }.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {TripIdPostData|{ tripId: TripIdPostData }} opts.data - Trip parameters (or wrapped in tripId key)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse<{ tripId: { tripId: string|null } }>>}
+   * @throws 400 WRONG_DATA — tripId required or required fields missing
+   * @throws 401 Unauthorized
+   * @throws 404 TRIP_IDS_NOT_FOUND
+   * @throws 500 Internal server error
+   */
+  function create({token, jwtToken, data, headers}) {
+    return client({
+      url: "/direct-trip-ids",
+      method: "post",
+      data,
+      headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
+    });
+  }
+
+  return {
+    create
+  };
+}
+
+module.exports = tripIdsFactory;

package/src/endpoints/inventory/trips.js

@@ -1,46 +1,84 @@
+/* eslint-disable max-len */
 const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
 /**
- * Factory for trips API (btrz-api-inventory).
+ * Factory for trips API (btrz-api-inventory-trips).
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
- * @returns {{ all: function, get: function }}
+ * @returns {{ all: function, get: function, getPricingSimulation: function }}
  */
 function tripsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /trips - list trips. API source of truth in btrz-api-inventory-trips; query not documented here.
+   * GET /trips — Search for available trips by date, origin, destination, fare, product, channel, and price. Rate limited (e.g. 8000 req/10 min). See get-trips getSpec() for full query params (productId, originId, destinationId, fareIds, departureDate, returnDate, channel, currency, etc.).
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {Object} [opts.query] - Query params (productId, originId, destinationId, fareIds, departureDate, returnDate, etc.)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ trips: { departures: Object[], returns: Object[] } }>>}
+   * @throws 400 INVALID_DATE, INVALID_DATE_FORMAT, INVALID_PRODUCTID, INVALID_ORIGIN, INVALID_DESTINATION, INVALID_CHANNEL, INVALID_FARE, INVALID_FAREID, INVALID_MANIFEST_STATUS, WRONG_DATA
+   * @throws 401 Unauthorized
+   * @throws 409 NO_HIGHER_OR_EQL_PRICE
+   * @throws 500 Internal server error
    */
   function all({token, jwtToken, query = {}, headers}) {
     return client({
       url: "/trips",
+      method: "get",
       params: query,
       headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
     });
   }
 
   /**
-   * GET /trip/:id - get trip by id. API does not accept query params.
+   * GET /trip/:id — Get up-to-date information for a trip by its ID (base64-encoded trip summary from a search). Optional query: extraCapacityImpact, ignoreCutoffs, currency, ignoreOmitByAvailability, includeMoveToTrips.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} opts.id - Trip id
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {string} opts.id - Trip id (base64-encoded)
+   * @param {Object} [opts.query] - Optional: extraCapacityImpact, ignoreCutoffs, currency, ignoreOmitByAvailability, includeMoveToTrips
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ trip: Object }>>}
+   * @throws 400 INVALID_TRIP — tripId is invalid
+   * @throws 401 Unauthorized
+   * @throws 500 Internal server error
    */
-  function get({token, id, headers}) {
-    return client.get(`/trip/${id}`, {
-      headers: authorizationHeaders({token, internalAuthTokenProvider, headers})
+  function get({token, jwtToken, id, query = {}, headers}) {
+    return client({
+      url: `/trip/${id}`,
+      method: "get",
+      params: query,
+      headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
+    });
+  }
+
+  /**
+   * GET /trips/pricing-simulation — Get pricing simulation for all purchase combinations for a schedule. Query: scheduleId, productId (required); purchaseDate, travelDate, includeReadable, includeMetadata, minimize (optional).
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {Object} [opts.query] - scheduleId, productId (required); purchaseDate, travelDate, includeReadable, includeMetadata, minimize
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse<Object>>} Response shape per PricingSimulationResult definition
+   * @throws 400 INVALID_SCHEDULE_ID, INVALID_PRODUCT_ID, INVALID_PRODUCT, ROUTE_NOT_FOUND, ONLY_JP_SUPPORTED, INVALID_DATE
+   * @throws 401 Unauthorized, PRICING_SIMULATOR_DISABLED, PROVIDER_UNAUTHORIZED
+   * @throws 404 SCHEDULE_NOT_FOUND, NO_MANIFEST
+   * @throws 500 Internal server error
+   */
+  function getPricingSimulation({token, jwtToken, query = {}, headers}) {
+    return client({
+      url: "/trips/pricing-simulation",
+      method: "get",
+      params: query,
+      headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
     });
   }
 
   return {
     all,
-    get
+    get,
+    getPricingSimulation
   };
 }
 

package/src/endpoints/invoices/emails.js

@@ -10,13 +10,23 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
  */
 function emailsFactory({client, internalAuthTokenProvider}) {
   /**
-   * POST /emails - create/send invoice email. API does not accept query params.
+   * POST /emails — Send invoice by email to the given addresses.
+   * Request body may be sent as root object or under key "email". On success the API emits webhook invoiceemail.created.
+   *
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.data - Request body
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol (Authorization: Bearer)
+   * @param {Object} opts.data - Request body (EmailPostData)
+   * @param {string} opts.data.invoiceId - Invoice ID (required, 24-char hex ObjectId)
+   * @param {string[]} opts.data.emails - Recipient email addresses (required)
+   * @param {string} [opts.data.language] - Language code for template (e.g. "en-us")
+   * @param {Object} [opts.query] - Query params (none used by this endpoint)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ status: "OK" }>>} Resolves with { status: "OK" } on success
+   * @throws 400 WRONG_DATA, ACCOUNT_CANT_SEND_EMAILS, NO_VERIFIED_OR_ACTIVE_EMAIL, INVALID_EMAIL_TO_SEND
+   * @throws 401 Unauthorized (missing/invalid X-API-KEY or Authorization)
+   * @throws 404 INVOICE_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function create({token, jwtToken, data, query = {}, headers}) {
     return client({

package/src/endpoints/invoices/invoices.js

@@ -22,13 +22,15 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
  */
 function invoicesFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /invoices - list invoices.
+   * GET /invoices — List invoices by transaction (paginated).
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {InvoicesListQuery} [opts.query] - Query params (transactionId required)
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {InvoicesListQuery} [opts.query] - Query; transactionId (required) = 24-char hex ObjectId
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ invoices: Object[], total: number, page?: number, ... }>>}
+   * @throws 401 Unauthorized
+   * @throws 500 Internal server error
    */
   function all({token, jwtToken, query = {}, headers}) {
     return client({
@@ -40,13 +42,17 @@ function invoicesFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * GET /invoices/:id - get invoice by id. API does not accept query params.
+   * GET /invoices/:id — Get a single invoice by ID.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.id - Invoice id
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {string} opts.id - Invoice ID (24-character hex ObjectId)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ invoice: Object }>>}
+   * @throws 400 WRONG_DATA, INVALID_INVOICE_ID
+   * @throws 401 Unauthorized
+   * @throws 404 INVOICE_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function get({token, jwtToken, id, query = {}, headers}) {
     return client({
@@ -58,13 +64,16 @@ function invoicesFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * GET /failures - list invoice failures.
+   * GET /failures — List invoice failures (paginated). Optional transactionId filter.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {InvoicesFailuresQuery} [opts.query] - Query params (transactionId optional)
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {InvoicesFailuresQuery} [opts.query] - Query; transactionId optional (24-char hex; if present must be valid)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ invoicesFailures: Object[], total: number, ... }>>}
+   * @throws 400 WRONG_DATA, INVALID_TRANSACTION_ID (if transactionId provided and invalid)
+   * @throws 401 Unauthorized
+   * @throws 500 Internal server error
    */
   function getInvoicesFailures({token, jwtToken, query = {}, headers}) {
     return client({
@@ -76,13 +85,19 @@ function invoicesFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /retry - retry invoicing. API does not accept query params.
+   * POST /retry — Retry invoicing from an invoice failure using saved data. Body: transactionId (required).
+   * On success may emit webhooks invoices.created or invoices.updated.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.data - Request body
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {Object} opts.data - Body: { transactionId } (transactionId = 24-char hex ObjectId)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ invoice: Object }>>}
+   * @throws 400 WRONG_DATA, INVOICE_NOT_CREATED, INVOICE_PROVIDER_TYPE_NOT_SUPPORTED, INVOICE_PROVIDER_NOT_FOUND, TRANSACTION_ALREADY_INVOICED
+   * @throws 401 Unauthorized
+   * @throws 404 TRANSACTION_NOT_FOUND, INVOICE_FAILURE_NOT_FOUND
+   * @throws 409 INFILE_SIGN_FAILED, INFILE_CERTIFICATION_FAILED
+   * @throws 500 Internal server error
    */
   function retryInvoicing({token, jwtToken, data, query = {}, headers}) {
     return client({
@@ -95,13 +110,19 @@ function invoicesFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * PUT /retry - override buyer and retry invoicing. API does not accept query params.
+   * PUT /retry — Override buyer and retry invoicing from an invoice failure. Body: retryData with transactionId and overrideBuyer.
+   * On success may emit webhooks invoices.created or invoices.updated.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.data - Request body
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {Object} opts.data - Body: { transactionId, overrideBuyer } (RetryPutData); overrideBuyer required when no certified invoice exists
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ invoice: Object }>>}
+   * @throws 400 WRONG_DATA, INVOICE_NOT_CREATED, INVOICE_PROVIDER_TYPE_NOT_SUPPORTED, INVOICE_PROVIDER_NOT_FOUND, TRANSACTION_ALREADY_INVOICED, OVERRIDE_BUYER_IS_MANDATORY
+   * @throws 401 Unauthorized
+   * @throws 404 TRANSACTION_NOT_FOUND, INVOICE_FAILURE_NOT_FOUND
+   * @throws 409 INFILE_SIGN_FAILED, INFILE_CERTIFICATION_FAILED
+   * @throws 500 Internal server error
    */
   function overrideBuyerRetryInvoicing({token, jwtToken, data, query = {}, headers}) {
     return client({

package/src/endpoints/invoices/pdfs.js

@@ -3,8 +3,8 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
 /**
  * Query params for GET /pdfs (btrz-api-invoices). See pdfs get-handler getSpec().
- * @typedef {Object} PdfsListQuery
- * @property {string} transactionId - Transaction id of the invoice (required)
+ * @typedef {Object} PdfsQuery
+ * @property {string} transactionId - Transaction ID of the invoice (required, 24-char hex ObjectId)
  */
 
 /**
@@ -16,14 +16,21 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
  */
 function pdfsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /pdfs - list invoice PDFs.
+   * GET /pdfs — Returns the invoice PDF for the invoice associated with the given transaction.
+   * Response is binary (application/pdf) with Content-Disposition attachment; filename=invoice-{invoiceId}.pdf.
+   * Use responseType "blob" or "arraybuffer" to receive binary data.
+   *
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {PdfsListQuery} [opts.query] - Query params (transactionId required)
-   * @param {string} [opts.responseType] - Response type (e.g. "json", "blob")
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {PdfsQuery} [opts.query] - Query; transactionId (required)
+   * @param {string} [opts.responseType] - Response type: "blob" or "arraybuffer" for binary PDF; "json" default
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<ArrayBuffer|Blob|*>>} PDF binary when responseType is blob/arraybuffer
+   * @throws 400 WRONG_DATA — transactionId is required
+   * @throws 401 Unauthorized
+   * @throws 404 INVOICE_NOT_FOUND — Invoice not found for the transactionId
+   * @throws 500 Internal server error (e.g. unsupported invoice provider type)
    */
   function all({token, jwtToken, query = {}, responseType = "json", headers}) {
     return client({

package/src/endpoints/invoices/providers.js

@@ -20,13 +20,15 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
  */
 function providersFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /providers - list invoice providers.
+   * GET /providers — List invoice providers (paginated). Optional filters: enabled, invoiceProviderType, channel, country, operatingCompany.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
    * @param {ProvidersListQuery} [opts.query] - Query params (all optional)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ providers: Object[], total?: number, ... }>>}
+   * @throws 401 Unauthorized
+   * @throws 500 Internal server error
    */
   function all({token, jwtToken, query = {}, headers}) {
     return client({
@@ -38,13 +40,17 @@ function providersFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * GET /providers/:id - get invoice provider by id. API does not accept query params.
+   * GET /providers/:id — Get a single invoice provider by ID.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.id - Provider id
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {string} opts.id - Provider ID (24-character hex ObjectId)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ provider: Object }>>}
+   * @throws 400 WRONG_DATA, INVALID_PROVIDER_ID
+   * @throws 401 Unauthorized
+   * @throws 404 PROVIDER_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function get({token, jwtToken, id, query = {}, headers}) {
     return client({
@@ -56,14 +62,18 @@ function providersFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * PUT /providers/:id - update invoice provider. API does not accept query params.
+   * PUT /providers/:id — Update invoice provider. Body may be provider or body.provider. Emits webhook invoice_providers.updated on success.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.id - Provider id
-   * @param {Object} opts.data - Request body
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {string} opts.id - Provider ID (24-character hex ObjectId)
+   * @param {Object} opts.data - Request body (ProviderPutData)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ provider: Object }>>}
+   * @throws 400 INVALID_PHRASES, OPERATING_COMPANY_NOT_FOUND, CANNOT_CHANGE_PROVIDER, INVALID_IVA_AFFILIATION, CANT_REMOVE_*, INVALID_PARAM_VALUE, CANT_DELETE_DOCUMENT_TYPE_*
+   * @throws 401 Unauthorized
+   * @throws 404 PROVIDER_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function update({token, jwtToken, id, data, query = {}, headers}) {
     return client({
@@ -76,13 +86,17 @@ function providersFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * DELETE /providers/:id - remove invoice provider. API does not accept query params.
+   * DELETE /providers/:id — Remove invoice provider. Emits webhook invoice_providers.deleted on success.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.id - Provider id
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {string} opts.id - Provider ID (24-character hex ObjectId)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ providerId: string }>>}
+   * @throws 400 WRONG_DATA, INVALID_PROVIDER_ID
+   * @throws 401 Unauthorized
+   * @throws 404 PROVIDER_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function remove({token, jwtToken, id, query = {}, headers}) {
     return client({
@@ -94,13 +108,16 @@ function providersFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /providers - create invoice provider. API does not accept query params.
+   * POST /providers — Create invoice provider. Body may be provider or body.provider (ProviderPostData). Emits webhook invoice_providers.created on success.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.data - Request body
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {Object} opts.data - Request body (ProviderPostData: invoiceProviderType, currencies, params required)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ provider: Object }>>}
+   * @throws 400 WRONG_DATA, INVALID_PHRASES, REQUIRED_PARAM_MISSING, INVALID_PARAM_VALUE, OPERATING_COMPANY_NOT_FOUND, INVALID_IVA_AFFILIATION
+   * @throws 401 Unauthorized
+   * @throws 500 Internal server error
    */
   function create({token, jwtToken, data, query = {}, headers}) {
     return client({

package/src/endpoints/invoices/tax-ids.js

@@ -6,8 +6,8 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
  * @typedef {Object} TaxIdsListQuery
  * @property {string} taxNumber - Tax number to look up (required)
  * @property {string} country - ISO code of the country of the tax information (required)
- * @property {string} [invoiceProviderId] - Invoice provider id (24 hex chars)
- * @property {string} [documentType] - Tax identification type to check against validation service
+ * @property {string} [invoiceProviderId] - Invoice provider id (24-char hex ObjectId); optional, for external validation
+ * @property {string} [documentType] - Tax identification type for validation (e.g. NIT, DPI for infile)
  */
 
 /**
@@ -19,13 +19,17 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
  */
 function taxIdsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /tax-ids - list tax IDs.
+   * GET /tax-ids — List tax ID information (paginated). Merges internal tax IDs with external provider validation when invoiceProviderId is provided.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {TaxIdsListQuery} opts.query - taxNumber, country; optional invoiceProviderId, documentType
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {TaxIdsListQuery} [opts.query] - taxNumber and country (required); optional invoiceProviderId, documentType
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>} 400 WRONG_DATA, INVALID_PROVIDER_ID; 404 TAXID_NOT_FOUND
+   * @returns {Promise<import("axios").AxiosResponse<{ taxIds: Object[], total?: number, ... }>>}
+   * @throws 400 WRONG_DATA, INVALID_PROVIDER_ID, INVALID_TAX_NUMBER, INVALID_PROVIDER_CREDENTIALS
+   * @throws 401 Unauthorized
+   * @throws 404 TAXID_NOT_FOUND, PROVIDER_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function all({token, jwtToken, query = {}, headers}) {
     return client({