platform-types 1.10.832 → 1.10.834

package/dist/cjs/refundObligation.js

@@ -3,14 +3,17 @@
  * Refund obligations — money the store owes a customer back, tracked until it is
  * proven returned.
  *
- * An obligation is created inside the transaction of whatever made the money owed
- * (a purchase withdrawal's cancellation, a return, a late capture on a withdrawn
- * order) and closes on its own when Mercado Pago reports the refund, when an
+ * An obligation is created inside the transaction of whatever made the money owed —
+ * a purchase withdrawal's hand-off (`awaiting-goods`, at a provisional amount), a
+ * `Return` paid by `provider` (which opens it, or re-amounts the hand-off's), a late
+ * capture on a withdrawn order — and closes on its own when Mercado Pago reports the refund, when an
  * operator closes a payment attempt's resolution as `refunded`, or when a
  * chargeback settled the money back. An open dispute holds it; a lifted dispute
  * reopens it. Closure moves no money and writes no ledger row: it records a fact.
- * The one ledger write is the creator's in-transit debit of a linked payment's
- * credit ({@link RefundObligationLedgerCredit}), at creation.
+ * The one ledger write is the in-transit debit of a linked payment's credit
+ * ({@link RefundObligationLedgerCredit}), written by the `Return` that settles the
+ * obligation's parent (a `provider` one, or any withdrawal-bound one) — the only writer —
+ * for every obligation of that parent that carries one, closed included.
  *
  * ⚠️ The stored row carries none of the main table's index-key attributes
  * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
@@ -55,6 +58,9 @@ exports.REFUND_OBLIGATION_HOLD_REASONS = ['dispute-open', 'reimbursed'];
  * - `operator` — an operator closed it by hand.
  * - `chargeback` — a settled chargeback took the money back.
  * - `api-refund` — a refund the api itself made (reserved; no writer yet).
+ * - `account-credit` — settled by the `Return`'s `DEVOLUCION` account credit: an `offline` obligation of a seña
+ *   order's withdrawal, closed in that `Return`'s own transaction (the delivery netted the seña out of its
+ *   debit, so the credit IS the seña's refund). No drawer event, no `ACCOUNT#` row of its own.
  */
 exports.REFUND_OBLIGATION_CLOSED_BY = [
     'detected-refund',
@@ -62,6 +68,7 @@ exports.REFUND_OBLIGATION_CLOSED_BY = [
     'operator',
     'chargeback',
     'api-refund',
+    'account-credit',
 ];
 /** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
 exports.REFUND_OBLIGATION_DUE_SOURCE = 'global:refundObligationDueDays';

package/dist/refundObligation.d.ts

@@ -2,14 +2,17 @@
  * Refund obligations — money the store owes a customer back, tracked until it is
  * proven returned.
  *
- * An obligation is created inside the transaction of whatever made the money owed
- * (a purchase withdrawal's cancellation, a return, a late capture on a withdrawn
- * order) and closes on its own when Mercado Pago reports the refund, when an
+ * An obligation is created inside the transaction of whatever made the money owed —
+ * a purchase withdrawal's hand-off (`awaiting-goods`, at a provisional amount), a
+ * `Return` paid by `provider` (which opens it, or re-amounts the hand-off's), a late
+ * capture on a withdrawn order — and closes on its own when Mercado Pago reports the refund, when an
  * operator closes a payment attempt's resolution as `refunded`, or when a
  * chargeback settled the money back. An open dispute holds it; a lifted dispute
  * reopens it. Closure moves no money and writes no ledger row: it records a fact.
- * The one ledger write is the creator's in-transit debit of a linked payment's
- * credit ({@link RefundObligationLedgerCredit}), at creation.
+ * The one ledger write is the in-transit debit of a linked payment's credit
+ * ({@link RefundObligationLedgerCredit}), written by the `Return` that settles the
+ * obligation's parent (a `provider` one, or any withdrawal-bound one) — the only writer —
+ * for every obligation of that parent that carries one, closed included.
  *
  * ⚠️ The stored row carries none of the main table's index-key attributes
  * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
@@ -52,8 +55,11 @@ export declare const REFUND_OBLIGATION_HOLD_REASONS: readonly ["dispute-open", "
  * - `operator` — an operator closed it by hand.
  * - `chargeback` — a settled chargeback took the money back.
  * - `api-refund` — a refund the api itself made (reserved; no writer yet).
+ * - `account-credit` — settled by the `Return`'s `DEVOLUCION` account credit: an `offline` obligation of a seña
+ *   order's withdrawal, closed in that `Return`'s own transaction (the delivery netted the seña out of its
+ *   debit, so the credit IS the seña's refund). No drawer event, no `ACCOUNT#` row of its own.
  */
-export declare const REFUND_OBLIGATION_CLOSED_BY: readonly ["detected-refund", "resolution-refunded", "operator", "chargeback", "api-refund"];
+export declare const REFUND_OBLIGATION_CLOSED_BY: readonly ["detected-refund", "resolution-refunded", "operator", "chargeback", "api-refund", "account-credit"];
 /** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
 export declare const REFUND_OBLIGATION_DUE_SOURCE = "global:refundObligationDueDays";
 /** The longest operator `reason` `POST /refund-obligations` accepts, in characters after trimming. */
@@ -81,8 +87,8 @@ declare global {
     }
     /**
      * The payment-link credit an obligation's money was booked to, when there is one: the customer's ledger
-     * still holds it as a credit, so the creator debits the share being refunded ("in transit") in its own
-     * transaction, one `ACCOUNT#` row per obligation.
+     * still holds it as a credit, so the `Return` that settles the obligation's parent debits the share being
+     * refunded ("in transit") in its own transaction, one `ACCOUNT#` row per obligation (`RIT#{obligationId}`).
      */
     interface RefundObligationLedgerCredit {
         /** The `ACCOUNT#{storeId}` credit row's SK — the per-source payment row's `accountId`. */
@@ -115,6 +121,12 @@ declare global {
         actor?: string;
         /** The operator's own words, for `operator`. */
         reason?: string;
+        /**
+         * For `operator`: the money went back from the operator's till (`payout: 'drawer'`) in the closure's own
+         * transaction. A seña's `Return` excludes that amount from its `DEVOLUCION` credit. Absent on a closure that
+         * recorded no payout, and on one written before the payout was recorded on the closure.
+         */
+        payout?: (typeof REFUND_OBLIGATION_PAYOUTS)[number];
         /** For `detected-refund`: the ids of the payment's `refunds[]` dated at or after `createdAt`. */
         providerRefundIds?: string[];
     }
@@ -122,7 +134,10 @@ declare global {
         /** The row's sort key: `{orderId}#{parentId}#{kind}#{paymentId | 'till'}`. */
         obligationId: string;
         orderId: string;
-        /** The withdrawal or RMA that made the money owed. */
+        /**
+         * What made the money owed: the purchase withdrawal (`ARR…`) — the hand-off's and its `Return`'s — else the
+         * RMA (`RMA…`) a `provider` `Return` settles, else that `Return` itself (`RET…`).
+         */
         parentId: string;
         kind: RefundObligationKind;
         /** The Mercado Pago payment the money came in on. Absent for `offline`. */

package/dist/refundObligation.js

@@ -2,14 +2,17 @@
  * Refund obligations — money the store owes a customer back, tracked until it is
  * proven returned.
  *
- * An obligation is created inside the transaction of whatever made the money owed
- * (a purchase withdrawal's cancellation, a return, a late capture on a withdrawn
- * order) and closes on its own when Mercado Pago reports the refund, when an
+ * An obligation is created inside the transaction of whatever made the money owed —
+ * a purchase withdrawal's hand-off (`awaiting-goods`, at a provisional amount), a
+ * `Return` paid by `provider` (which opens it, or re-amounts the hand-off's), a late
+ * capture on a withdrawn order — and closes on its own when Mercado Pago reports the refund, when an
  * operator closes a payment attempt's resolution as `refunded`, or when a
  * chargeback settled the money back. An open dispute holds it; a lifted dispute
  * reopens it. Closure moves no money and writes no ledger row: it records a fact.
- * The one ledger write is the creator's in-transit debit of a linked payment's
- * credit ({@link RefundObligationLedgerCredit}), at creation.
+ * The one ledger write is the in-transit debit of a linked payment's credit
+ * ({@link RefundObligationLedgerCredit}), written by the `Return` that settles the
+ * obligation's parent (a `provider` one, or any withdrawal-bound one) — the only writer —
+ * for every obligation of that parent that carries one, closed included.
  *
  * ⚠️ The stored row carries none of the main table's index-key attributes
  * (`status`, `customerId`, `dated`, `updatedAt`, `terminalId`, `inboxKey`), so it
@@ -52,6 +55,9 @@ export const REFUND_OBLIGATION_HOLD_REASONS = ['dispute-open', 'reimbursed'];
  * - `operator` — an operator closed it by hand.
  * - `chargeback` — a settled chargeback took the money back.
  * - `api-refund` — a refund the api itself made (reserved; no writer yet).
+ * - `account-credit` — settled by the `Return`'s `DEVOLUCION` account credit: an `offline` obligation of a seña
+ *   order's withdrawal, closed in that `Return`'s own transaction (the delivery netted the seña out of its
+ *   debit, so the credit IS the seña's refund). No drawer event, no `ACCOUNT#` row of its own.
  */
 export const REFUND_OBLIGATION_CLOSED_BY = [
     'detected-refund',
@@ -59,6 +65,7 @@ export const REFUND_OBLIGATION_CLOSED_BY = [
     'operator',
     'chargeback',
     'api-refund',
+    'account-credit',
 ];
 /** Where a {@link StatutoryInstant} came from: the platform global it was computed with. */
 export const REFUND_OBLIGATION_DUE_SOURCE = 'global:refundObligationDueDays';

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
@@ -98,8 +105,28 @@ declare global {
     interface ReturnLedgerBasisUnavailableData {
         flow: ReturnFlow;
     }
-    /** Where a customer return's value is paid. Omission on a request or legacy row means account. */
-    type ReturnRefundMethod = 'account' | 'cash';
+    /**
+     * Where a customer return's value is paid. Omission on a request or legacy row means account.
+     *
+     * - `account` — a `DEVOLUCION` credit on the customer's account.
+     * - `cash` — paid out of the till.
+     * - `provider` — the money goes back through the payments it came in on: the same `DEVOLUCION` credit as
+     *   `account`, plus one refund obligation per payment bucket (`RefundObligation`, parent the withdrawal the
+     *   return settles, else its RMA, else the return itself), opened at the amount the server re-derives. An
+     *   `applyCredit`-linked payment's link credit is debited in transit (`RIT#{obligationId}`) in the same
+     *   transaction, so the account credit is never spendable — as on any withdrawal-bound return, whatever its
+     *   method, for every obligation of the withdrawal carrying one. Needs no `acknowledgeNoProviderRefund`.
+     */
+    type ReturnRefundMethod = 'account' | 'cash' | 'provider';
+    /**
+     * `data` of `409 RETURN_WITHDRAWAL_HOLDS_LINE`: a return with no `rmaId` named a quantity a live purchase
+     * withdrawal holds — its `requested`/`accepted` lines, or the approved lines of its open
+     * `purchase-withdrawal` RMA (`rmaId`). Settle that withdrawal through its own RMA instead.
+     */
+    interface ReturnWithdrawalHoldsLineData {
+        withdrawalId: string;
+        rmaId?: string;
+    }
     /** Return planning refusals: invalid selected lines, too many return summaries, or more than 100 transaction items. */
     type ReturnPlanFailureCode = 'RETURN_INVALID_SUBSET' | 'RETURN_LIMIT_REACHED' | 'RETURN_TRANSACTION_TOO_LARGE' | 'UNIT_QUANTITY_NOT_WHOLE' | 'UNIT_QUANTITY_UNREPRESENTABLE';
     /**
@@ -193,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[];
         /**
@@ -234,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
@@ -275,6 +316,11 @@ declare global {
          * nothing backfills it and no reader derives it from `reason`.
          */
         flow?: ReturnFlow;
+        /**
+         * The RMA this return settled (`CreateReturnRequest.rmaId`), moved `received → settled` in the return's own
+         * transaction. Operator-only. Absent on a return that bound none, and on every return written before it existed.
+         */
+        rmaId?: string;
         notes?: string;
         userId: string;
         /**
@@ -614,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
@@ -722,6 +777,8 @@ declare global {
          * stripped from every customer surface. Absent on legacy summaries.
          */
         flow?: ReturnFlow;
+        /** Mirrors `Return.rmaId`. Operator-only: stripped from every customer surface. */
+        rmaId?: string;
         ncStatus?: ReturnCreditNoteStatus;
         creditNoteId?: string;
         /**
@@ -843,8 +900,37 @@ declare global {
      */
     interface CreateReturnRequest {
         mode: 'return';
-        /** Omission credits the customer account. Cash pays the full server-calculated return total; no provider refund. A walk-in order (the system customer) is always refunded in cash, whatever is sent, but only up to what the order was paid; the unpaid rest lowers what the order still owes. */
+        /**
+         * Omission credits the customer account. Cash pays the full server-calculated return total; no provider
+         * refund. A walk-in order (the system customer) is always refunded in cash, whatever is sent, but only up to
+         * what the order was paid; the unpaid rest lowers what the order still owes.
+         *
+         * `provider` opens the refund obligations (see {@link ReturnRefundMethod}). A return bound to a
+         * purchase-withdrawal RMA defaults to `provider` while the re-derived amount owed is above 0, and any other
+         * method is then `409 RETURN_REFUND_METHOD_PROVIDER_REQUIRED`; with nothing owed (an unpaid order) it
+         * defaults to `account`. `provider` on an order with no linked payment, no approved attempt payment and no
+         * till leg is `409 RETURN_PROVIDER_NO_PAYMENT`; one whose payments owe nothing is
+         * `409 RETURN_PROVIDER_NOTHING_OWED`. A payment in a currency the order cannot convert at its frozen rate is
+         * `409 RETURN_PROVIDER_CURRENCY_MISMATCH`; a link credit the in-transit debit cannot vet is
+         * `409 RETURN_LEDGER_BASIS_UNAVAILABLE`; an obligation still owed that the re-derived amount gives nothing
+         * is `409 RETURN_OBLIGATION_RECONCILE_REQUIRED`. Each writes nothing and one ERROR row.
+         */
         refundMethod?: ReturnRefundMethod;
+        /**
+         * The RMA this return settles. Read strongly; it must be this order's and `received`, else `404
+         * RMA_NOT_FOUND`, `409 RETURN_RMA_ORDER_MISMATCH` or `409 RETURN_RMA_NOT_RECEIVED`. The return's lines must
+         * EQUAL a `purchase-withdrawal` RMA's approved lines (index and quantity), and stay within any other RMA's
+         * approved quantity on the lines it names, else `409 RETURN_RMA_LINES_MISMATCH`. The return then takes its
+         * flow from the RMA (`purchase-withdrawal` for that source, else `Rma.flow`, else the reason's), stores
+         * `rmaId`, and settles the RMA (`received → settled`, `settledReturnId`) in its own transaction; a
+         * withdrawal-bound return also moves the withdrawal (`refund-pending` while an obligation is owed, else
+         * `completed`).
+         *
+         * Absent: a return that names a quantity a live purchase withdrawal holds is
+         * `409 RETURN_WITHDRAWAL_HOLDS_LINE` (`ReturnWithdrawalHoldsLineData`); a truncated read of the order's open
+         * RMAs is `503 RETURN_REQUESTS_UNAVAILABLE`.
+         */
+        rmaId?: string;
         /** Client-minted UUID; the idempotency key. A replay returns the original outcome. */
         requestId: string;
         orderId: string;
@@ -889,9 +975,10 @@ declare global {
         emitCreditNote?: boolean;
         sendEmail?: boolean;
         /**
-         * Required when the order has a non-empty `linkedPayments` map: the
-         * operator acknowledges SINFACTURA does NOT refund or unlink the provider
-         * payment. The return pays by refundMethod (account by default; always cash on a walk-in order).
+         * Required when the order has a non-empty `linkedPayments` map and the
+         * return pays by `account` or `cash`: the operator acknowledges SINFACTURA
+         * does NOT refund or unlink the provider payment. `provider` needs none.
+         * The return pays by refundMethod (account by default; always cash on a walk-in order).
          */
         acknowledgeNoProviderRefund?: boolean;
         /**

package/dist/rma.d.ts

@@ -301,8 +301,9 @@ declare global {
             refundAs: ChangeOfMindRefundAs;
         };
         /**
-         * The refunds owed on this request, as on a withdrawal. No writer links a
-         * refund to a shopper request yet, so it is absent today.
+         * The refunds owed on this request, as on a withdrawal: one per refund
+         * obligation whose `parentId` is this RMA, which the `provider` `Return`
+         * settling it opens. Absent while there is none.
          */
         refunds?: OrderPurchaseWithdrawalRefundView[];
     }

package/package.json

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