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
- Open Imports → RPApos (or navigate to
/imports/gateway/rpapos). - 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.
- Enter subdomain (without
- Optional: timezone, currency code,
tipo_gestionmapping for order types. - 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 tenantusuario/passwordfor SAT calls. - After save: on the connection list, use Register SOAP token if the status shows the token is missing (calls
Dispositivo_Registra_2on 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 existingrpapos_id_maprows (Codigo_PLU→ product). Use after a prior PLU migration or when refreshing photos only.
- When checked, FlowPOS runs a second step after catalog entities to download images from RPApos legacy SOAP and attach them to FlowPOS products (
- 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_itemandplu_option_group_assignmentrequire at least one PLU row inrpapos_id_map(i.e., a prior PLU import). Selecting them without prior PLU data fails withPLU_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.
People / CRM
People / CRM is not part of quick start. It appears when you choose Everything or when you select it under Custom.
The choice on that card limits who this run writes. FlowPOS still reads the full customer tables every time.
| This run | What is written |
|---|---|
| Import every person | Every person in the three tables |
| Next batch of new people | Up to the batch size (default 500) of people not yet in the id map, in persona-id order. Run it again for the next page. |
| Fill people already imported | Only people already mapped. Use this once after deploying the list import, so phones, addresses, emails and billing are filled onto customers that were imported with a name only. |
A green run can still leave someone with no phone. Numbers that are not Guatemala phone numbers, and emails or billing ids the customer module refuses, are counted in the backend log and are not written. Filling a person never replaces a phone, address, email or billing profile FlowPOS already has.
Before the first fill on a business that was imported earlier, open one customer and confirm customer_code looks like RPAPOS-<id>. An older import may have stored the RPApos code instead. The fill still finds those people when the id map points at them.
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_imagesrow when image import was requested (uploaded / skipped / failed counts) - Link to Import History for the
product-imagejob 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) |
| Imported people have a name and no phone, address or email | The run wrote names only. Run People / CRM again with Fill people already imported after the list-writing deploy. A completed run can still drop a number that is not a Guatemala phone number; the log counts those drops. |
| 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.