nexvia / module-shipping

v1.1.0 2026-11-02 00:35 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
• magento/framework: ^103.0.7
• magento/module-backend: ^102.0.7
• magento/module-catalog: ^104.0.7
• magento/module-checkout: ^100.4.7
• magento/module-config: ^101.2.7
• magento/module-cron: ^100.4.7
• magento/module-eav: ^102.1.7
• magento/module-payment: ^100.4.7
• magento/module-quote: ^101.2.7
• magento/module-sales: ^103.0.7
• magento/module-shipping: ^100.4.7
• magento/module-store: ^101.1.7
• magento/module-webapi: ^100.4.6

OSL-3.0, AFL-3.0

• magento
• shipping
• magento2
• Uruguay
• nexvia

Published on Packagist.org on 2026-11-06 18:51 UTC

README

«Envío con Nexvia» for Magento Open Source and Adobe Commerce 2.4.7, 2.4.8 and 2.4.9 (PHP 8.1 to 8.5). The buyer chooses the delivery day and time slot at checkout; when the order is paid, the module sends the purchase to Nexvia in the background, and from then on the buyer manages the shipment in Nexvia. The module never follows the shipment afterwards (ADR-0014). Missing product data is completed by the buyer in Nexvia, never by store defaults (ADR-0015).

Uruguay only. Licensed OSL-3.0 and AFL-3.0, like Magento's own modules.

Install

composer require nexvia/module-shipping
bin/magento module:enable Nexvia_Shipping
bin/magento setup:upgrade
bin/magento setup:di:compile        # production mode
bin/magento setup:static-content:deploy
bin/magento cache:flush

setup:upgrade creates the module's tables and the product attributes, and is also what makes the site proof (/rest/V1/nexvia/connect-proof) exist: the connection fails with «Nexvia no encontró la verificación» until it runs.

Magento's cron must run. Orders are sent to Nexvia by the nexvia_publish_orders job, every minute, in the default group. Without cron nothing reaches Nexvia, and the admin shows «Nexvia: hay N pedidos pagos esperando…» after 15 minutes.

Nexvia's address (app/etc/env.php)

Production needs nothing. To point a test installation at another Nexvia, like the wp-config.php constants of the WooCommerce plugin (not editable from the admin, so http is accepted):

'nexvia' => [
    'middleware_url' => 'https://ecommerce.nexvia.io',          // server to server; the default
    'panel_url' => 'https://ecommerce.nexvia.io/merchant',      // what the browser opens; default: middleware_url + /merchant
],

Connect a website

Each website is one Nexvia connection, with its own key and its own pickup. In Stores › Configuration › Sales › Delivery Methods › Nexvia, choose the website in «Scope» (with a single website the Default scope acts on it), accept the data consent and click «Conectar con Nexvia». Nexvia opens; sign in (or create the account) and approve; you come back to the same page connected. No keys are copied: the module exchanges a one-use code for the website's key with PKCE, and Nexvia checks that the code belongs to this installation by calling POST {website secure base URL}/rest/V1/nexvia/connect-proof (anonymous; it must not be cached or blocked by a WAF).

• The website's identity is its secure web base URL (https, port 443), normalized. A copy of the database on another domain pauses Nexvia there («Esta instalación no es …») until it is connected again or forgotten.
• The key is stored encrypted with Magento's crypt/key, at the websites scope. If crypt/key changes, Nexvia pauses until the website is connected again.
• bin/magento app:config:dump writes the website's connection (the five carriers/nexvia/* paths, the key encrypted) to app/etc/env.php, never to config.php. While it is there it wins over the database and the module cannot change it: the block says so instead of offering «Conectar», «Desconectar» or «Olvidar». To change the connection again, remove the carriers/nexvia lines under system › websites › <code> in app/etc/env.php, run bin/magento cache:flush and reload the page; the connection kept in the database is still there.
• Connecting does not enable the carrier: set «Habilitado» to «Sí» for the website and save.
• Delivery slots, preparation and pickup are configured only in the Nexvia panel.
• «Desconectar» revokes the key in Nexvia; disconnecting from the Nexvia panel also stops the website (the module just stops offering Nexvia). bin/magento module:uninstall --remove-data Nexvia_Shipping disconnects every connected website and deletes carriers/nexvia/* and the module's tables; without --remove-data (or answering «no» to Magento's question) it tells nobody. Orders keep their delivery choice and products keep their Nexvia attributes. The queue goes with the tables: paid orders not yet sent are no longer retried, so wait for them to be sent (or coordinate them with the buyer) before uninstalling. module:disable tells nobody: disconnect the store from the Nexvia panel as well.

Checkout (Luma)

With «Envío con Nexvia» chosen, the shipping step shows «Entrega con Nexvia»: one day or a range of days and a time slot, bounded by the dates and slots Nexvia offers for the cart (cached per website for the time Nexvia sets). The choice is saved through the module's REST endpoints, kept in its own table and validated again when the order is placed:

Route	Who
POST /rest/V1/nexvia/carts/mine/delivery-selection	the logged-in customer
POST /rest/V1/nexvia/guest-carts/:cartId/delivery-selection	a guest, with the masked cart id

Body: { "startDate": "2026-11-03", "timeSlot": "14:00-18:00" }, or with "endDate" for a range. Answer: true, or 400 { "message": … } with the reason. A headless storefront can call it before placing the order.

The order is refused, with a message for the buyer, when Nexvia is chosen and: the order is created from the admin; the payment method collects on delivery (cashondelivery always, plus the methods listed in «Medios de pago que cobran al entregar»); the website is not connected; or there is no choice, or Nexvia no longer accepts it. Cash on delivery is also hidden from the payment methods while Nexvia is chosen. When Nexvia cannot be offered because the service did not answer or sent an invalid envelope, the module logs a warning (Nexvia delivery options unavailable, with the website, the purchase and the reason; never the key), at most once a minute per website and purchase.

Not covered: Hyvä Checkout and headless/PWA storefronts have no selector (the server does not let them pay with Nexvia without a choice, so the buyer picks another rate); stores with the free Hyvä Theme use the Luma checkout through Hyvä's compatibility. Nexvia is not offered with «Check Out with Multiple Addresses», and an order created through POST /V1/orders has no choice: it fails in the queue with a message to coordinate with the buyer.

Product data

The patch adds «Largo para Nexvia (cm)», «Ancho para Nexvia (cm)», «Alto para Nexvia (cm)» and «Frágil para Nexvia» («Sin dato», «Sí», «No», without a default) in a «Nexvia» group, for simple, configurable and bundle products. Weight is Magento's own, converted from general/locale/weight_unit (kgs, or lbs × 0.45359237; another unit is unknown). A configurable line takes the chosen variant's data and falls back to the parent's for what the variant lacks; a bundle is one package with the bundle's own data. Nothing missing is invented: the buyer completes it.

When an order is sent

An order with Nexvia is sent when its paid invoices cover the total less what was canceled, with something paid and every invoice paid (a total of 0 counts as paid), it is not canceled, closed, on hold or in payment review, and it was not paid on delivery. An order invoiced in part with the rest canceled is sent with what was not canceled, a dynamic-price bundle counted by its parts. Offline methods (bank transfer, check) are sent when the merchant invoices them, even late: if the chosen delivery already ended, the order gets a note and the buyer picks another date in Nexvia.

The sales_order_save_commit_after observer only queues; the cron sends 25 orders per minute at most, retrying after 1, 5 and 15 minutes, 1, 3, 6 and 12 hours, for up to 3 days. Each step leaves an order comment («Nexvia: pendiente», «enviado», «falló: …») and the order view shows the state. Pickup problems (PICKUP_*, MERCHANT_SETUP_REQUIRED) are retried and noted once: the order enters as soon as the pickup is fixed in the panel. Validation errors and local data errors fail at once and can be resent with «Reenviar a Nexvia» after fixing the order; the reason names the field Nexvia rejected. An order lost after three days of a connection error (HTTP 401 or 403, or the website not connected) can be resent after connecting the store again. A queued order that stops being publishable (refunded, canceled, on hold, in review) waits and is looked at again every hour, and in its last hour before the three days a minute before they end; the order view says why. Failed orders are listed in an admin system message until «Entendido».

Layout

• Api/ — the REST service contracts (site proof, delivery choice).
• Model/Connection/ — website identity, PKCE and site proof, encrypted key and states, the connect flow.
• Model/Delivery/ — delivery options from Nexvia, the choice's validation and table.
• Model/Order/, Model/Catalog/ — the purchase sent to Nexvia and the product data of each line.
• Model/Payment/, Model/Queue/, Cron/ — when an order counts as paid, the ledger, the retry policy and the cron.
• Observer/ — order placement rule, cash on delivery, queueing after payment.
• Controller/Adminhtml/, Block/Adminhtml/, Model/System/Message/ — connection, «Reenviar a Nexvia», notices.
• view/frontend/ — the Luma component and its mixin; view/base/web/css/nexvia-tokens.css mirrors the Nexvia design-system tokens used by the checkout and admin styles.

Tests

scripts/magento/*.test.php run the module's classes in plain PHP with framework doubles, in the style of the WooCommerce plugin's tests, and scripts/publication-boundary.test.php checks the retired code and the registered routes, jobs and observers (pnpm test:php). What depends on Magento itself (events, areas, REST, layout, cron, schema) is verified in a real Magento in the stage laboratory, not with doubles.