platform-types 1.10.833 → 1.10.834

package/dist/return.d.ts

@@ -64,8 +64,15 @@ declare global {
      * - `unnumbered-factura` — a live factura entry carries no valid voucher
      *   number (and is not `pending_cae`), or a live entry carries no
      *   `invoiceType` at all and is counted as a factura, failing closed.
+     * - `freight-line-unmapped` — the return gives the freight back
+     *   ({@link Return.freight}) and every factura line maps to a goods line,
+     *   none to the order's freight line: the factura carries no freight line. A
+     *   note without the freight would credit less than the return, so none is
+     *   committed. A factura whose freight line differs from the order's (sku,
+     *   name, quantity, unit or IVA) fails the whole line mapping instead, and
+     *   answers `409 RETURN_LEDGER_BASIS_UNAVAILABLE`.
      */
-    type ReturnCreditNoteUnallocatableCause = 'multiple-facturas' | 'missing-invoice-id' | 'unnumbered-factura';
+    type ReturnCreditNoteUnallocatableCause = 'multiple-facturas' | 'missing-invoice-id' | 'unnumbered-factura' | 'freight-line-unmapped';
     /**
      * `data` of `409 RETURN_CREDIT_NOTE_REQUIRED`: the request sent
      * `emitCreditNote: false` for a return whose `flow` requires the credit note
@@ -213,6 +220,18 @@ declare global {
          */
         warehouseId?: string;
         items: ReturnItem[];
+        /**
+         * The order's freight line, given back by the `purchase-withdrawal` return that exhausts the order's goods
+         * lines. Server-appended, never client-settable: a body naming the freight index is
+         * `400 RETURN_INVALID_SUBSET`. `total` is the freight line's charge (`freightLineTotal`, never discounted)
+         * in the order's currency, and it is part of {@link Return.total}. Not a {@link ReturnItem}: it restocks
+         * nothing and writes no `SALE#`, `INCOME#` or disposition. The credit note's subset is `items` plus this.
+         * Operator-only, like the rest of the row.
+         *
+         * ⚠️ OPTIONAL PERMANENTLY. Absent on every other return — every other flow, a withdrawal return that leaves
+         * goods behind, an order with no freight line or one charged at 0 — and on every row written before it existed.
+         */
+        freight?: ReturnFreight;
         /** Operator-only intake allocations. Absent on legacy returns means no recorded movement snapshot. */
         stockMovements?: ReturnStockMovement[];
         /**
@@ -254,8 +273,10 @@ declare global {
         /**
          * The commercial refund in the originating order's currency. Selected
          * units use the sale's per-unit rounding rule, capped at the remaining
-         * recorded charge; the final units refund that charge less earlier
-         * `ReturnSummary.total` amounts. Historical returns remain as recorded.
+         * recorded charge; the final units refund that charge, less its freight
+         * line, less earlier `ReturnSummary.total` amounts. Historical returns
+         * remain as recorded. The one exception keeps the freight: a return
+         * carrying {@link Return.freight} refunds it too.
          *
          * The ACCOUNT credit is a separate conversion into the customer ledger's
          * currency, and a credit note reverses its factura's fiscal economics in
@@ -639,6 +660,15 @@ declare global {
      *   for the idempotency window and claims no second number.
      */
     type ReturnCreditNoteErrorCode = 'PARTIAL_NC_AFIP_DOWN' | 'NC_MULTI_FAC_UNSUPPORTED' | 'NC_EXCEEDS_FAC_TOTAL' | 'CBTE_ASOC_NOT_FOUND' | 'CBTE_ASOC_NOT_CREDITABLE' | 'CBTE_ASOC_AMBIGUOUS' | 'INVOICE_POINT_OF_SALE_CONFLICT' | 'INVOICE_POINT_OF_SALE_RESERVED' | 'INVOICE_MIXED_CURRENCY' | 'LINE_CURRENCY_NOT_INVOICEABLE' | 'LINE_IVA_TYPE_NOT_INVOICEABLE' | 'AFIP_LINE_FX_UNSTAMPED' | 'CUSTOMER_AFIP_SHAPE_INVALID' | 'AFIP_BNA_RATE_UNAVAILABLE' | 'PARTIAL_NC_INVALID_SUBSET' | 'PARTIAL_NC_REQUIRES_CBTE' | 'INVOICE_PERSIST_AFTER_CAE_FAILED' | 'NC_EMISSION_FAILED';
+    /** The freight a `purchase-withdrawal` return gives back — see {@link Return.freight}. */
+    interface ReturnFreight {
+        /** The freight line's index in `Order.items`. */
+        orderItemIndex: number;
+        /** The freight line's whole quantity. */
+        quantity: number;
+        /** The freight line's charge in the order's currency (`freightLineTotal`). */
+        total: number;
+    }
     interface ReturnItem {
         /**
          * Index of the line in the ORIGINATING `Order.items` array. Returns are

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.833",
+	"version": "1.10.834",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",