RPApos Gateway — Operator Guide

End-user flow for migrating catalog data from RPApos into FlowPOS.

Document version: 1.0 · Last updated: 2026-05

---

Prerequisites

• A FlowPOS business with at least one location (required when migrating dining areas or tables).
• RPApos tenant subdomain (e.g. lafabrica → lafabrica.2rpa.com).
• RPApos username and password with API access (same credentials used for RPApos web login).

---

Step 1 — Create a connection

1. Open Imports → RPApos (or navigate to /imports/gateway/rpapos).
2. Run the connection wizard:
   • Enter subdomain (without .2rpa.com).
   • Confirm subdomain is reachable (backend pings GET https://{subdomain}.2rpa.com/Login).
   • Enter RPApos usuario and password; credentials are validated and stored encrypted on the FlowPOS backend.
3. Optional: timezone, currency code, tipo_gestion mapping for order types.
4. Optional: SAT credentials (satUsuario / satPassword) — often different from the tenant web login. Used for SOAP device registration and reliable product image import. If omitted, FlowPOS falls back to the tenant usuario / password for SAT calls.
5. After save: on the connection list, use Register SOAP token if the status shows the token is missing (calls Dispositivo_Registra_2 on SAT and stores an encrypted device token on the connection).

Each business may have one connection per RPApos subdomain.

---

Step 2 — Migration planner

Open Plan migration for the connection (/imports/gateway/rpapos/{connectionId}/plan).

The planner has three scroll sections (step nav on the left):

1. Scope

Choose how much catalog to migrate:

Option	What is imported
Quick start	Core restaurant retail set: currencies, UoM, PLU/SKU categories, suppliers, dining areas, PLUs, employees, tables (no bodega, personas, SKUs, production groups, or batch recipes)
Everything	All 14 catalog entity types in dependency order
Custom	Checkboxes per entity; missing prerequisites are auto-included (shown with an “auto included” badge)

Target location (shown when Area or Table is in scope): pick which FlowPOS location dining areas and tables should attach to. When set, the sync may skip auto-importing Bodega (warehouse/location) if you did not explicitly select it.

2. Review

• Quick start / Everything (configure phase): summary list of entities in scope.
• Custom: enter RPApos password and click Load estimates to fetch approximate record counts per entity (live probe; not cached in current implementation).
• Preview phase (after Continue to preview): review table of entities, optional sample rows per entity (first 10 records), refresh samples.
• Import product images (checkbox at the bottom of the entity summary card):
  • When checked, FlowPOS runs a second step after catalog entities to download images from RPApos legacy SOAP and attach them to FlowPOS products (product.imageUrl).
  • If Products (PLU) are not already in scope, enabling this option auto-includes PLU in the run.
  • Custom scope only — images only: leave all entity checkboxes unchecked, enable Import product images, and run. This sends importProductImagesOnly — no catalog re-import; images are matched via existing rpapos_id_map rows (Codigo_PLU → product). Use after a prior PLU migration or when refreshing photos only.
• Modifier groups, items, and product–modifier links (Custom scope):
  • These three entities require a registered SOAP token. If the connection has no token, the checkboxes are disabled with a "Requires SOAP token" badge — register one from the connection card first.
  • plu_option_item and plu_option_group_assignment require at least one PLU row in rpapos_id_map (i.e., a prior PLU import). Selecting them without prior PLU data fails with PLU_IDMAP_EMPTY.
  • Each modifier entity is a single SOAP round trip. Pause/cancel are checked between entities, not mid-call.

Estimates use a one-time password field on the planner; the actual migration run uses stored connection credentials.

3. Run

• Continue to preview — moves to preview phase and loads samples.
• Run migration — starts sync and redirects to the monitor page.

---

Step 3 — Monitor the run

On /imports/gateway/rpapos/runs/{runId}:

• Per-entity status: pending, running, completed, failed, skipped
• Counts: extracted, loaded, failed
• A synthetic product_images row when image import was requested (uploaded / skipped / failed counts)
• Link to Import History for the product-image job when the image step created rows
• Actions: Pause, Resume, Cancel (while running)

When complete, open Summary for results and optional manual setup checklist items.

Note: Pause/cancel apply between catalog entities. The product image step runs after the entity loop; a failure in the image step does not fail the whole sync run (the run still completes; check product_images stats and Import History).

---

Dependency rules (custom scope)

If you select an entity, prerequisites are added automatically:

You select	Also runs
PLU	PLU categories, units of measure
SKU	SKU categories, units of measure
Area	Bodega (unless target location is set and Bodega was not selected)
Table	Area (+ transitive deps)
Production batch	PLU, SKU, units of measure
Modifier items	Modifier groups, PLU (+ transitive deps)
Product–modifier links	Modifier groups, PLU (+ transitive deps)

Entities always run in catalog order (currencies first, modifier links last).

---

Troubleshooting

Symptom	Likely cause
Login / probe fails	Wrong subdomain, usuario, or password
Tables fail	Areas not migrated, or no target location / dining area
Production batches fail	PLU or SKU not in id map yet — run product entities first
Connection status error	Last sync failed; check lastError on connection; use Clear error after fixing
Estimates missing for some entities	Probe only counts a subset (see API reference); use preview samples for others
Product images skipped / 0 uploaded	No SOAP token — register via connection list; or tenant has no Objeto_Archivo_1 / Catalogo_4 data; or PLU not in rpapos_id_map (run PLU first)
Images show “SOAP token missing” on connection	Run Register SOAP token on the gateway connection card
rest_only_unsupported in probe	Tenant exposes images on REST only; gateway requires SOAP catalog linkage today

---

Dev-only: reset imported catalog

On localhost / development / staging only, use Admin → Catalog reset (or Start fresh on the migration planner) to run Reset RPApos catalog. This deletes RPApos-mapped products, categories, dining areas/tables, suppliers, customers, employees, locations, recipes, modifier groups, modifier items, product–modifier assignments, and all rpapos_id_map rows for the current business (all connections). Does not remove connection credentials or SOAP tokens. Use before a clean re-migration in test environments.

A full catalog reset (native FlowPOS products/categories, not only RPApos imports) is planned but not available yet.

---

What is not migrated (today)

Historical transactional data (compra, traslado, merma, etc.) exists in the schema enum but is not available in the planner. Use CSV import or future gateway phases for those.