RPApos Gateway — Overview

Migrate master catalog data from an RPApos tenant ({subdomain}.2rpa.com) into FlowPOS without CSV files. The gateway lives in the PWA Import Center and is backed by the NestJS /rpapos API module.

Document version: 1.0 · Last updated: 2026-05

---

What it does

1. Connect — Store encrypted RPApos tenant credentials per business + subdomain. Optionally store SAT credentials and register a SOAP device token for legacy catalog/image APIs.
2. Plan — Choose scope (quick start, full catalog, or custom entities), preview samples, optional record estimates, and optionally import product images after PLU.
3. Run — Backend logs into RPApos REST, extracts catalog entities in dependency order, transforms rows, and loads FlowPOS tables. When enabled, a second step downloads images via SOAP (db4.2rpa.com) and uploads them to GCS (product.imageUrl).
4. Monitor — Track per-entity progress (including a synthetic product_images step); pause, resume, or cancel a sync run.
5. Images (optional) — Backfill only (importProductImagesOnly) reuses existing PLU rpapos_id_map rows without re-importing catalog data.

Re-runs are idempotent via rpapos_id_map (RPApos external ID → FlowPOS entity ID).

---

How it relates to CSV data import

	CSV / Excel import	RPApos gateway
Entry	Data Import → upload file	Import Center → RPApos → connection → planner
Source	User file	Live RPApos REST API (+ optional SOAP for images)
Processing	BullMQ import-processing queue	In-process async sync (RpaposSyncService)
Shared path	HandlerSink → same import handlers	Same handlers + dedicated RestSink for some entities

See Data Import Module for the file-based pipeline.

---

PWA routes

Route	Screen
/imports/gateway/rpapos	Connection list + wizard
/imports/gateway/rpapos/:connectionId/plan	Migration planner (scope → review → run)
/imports/gateway/rpapos/runs/:runId	Live sync monitor
/imports/gateway/rpapos/runs/:runId/summary	Post-run summary + manual checklist

Code: apps/frontend-pwa/src/components/forms/data-import/gateway/rpapos/

---

Backend module layout

apps/backend/src/rpapos/
├── interfaces/rpapos.controller.ts      HTTP /rpapos/*
├── application/
│   ├── rpapos-connection.service.ts     Credentials, probe, SOAP token refresh
│   ├── rpapos-sync.service.ts           Trigger sync, preview samples, run lifecycle
│   ├── rpapos-orchestrator.service.ts   Per-entity extract → transform → sink
│   ├── rpapos-product-image-import.service.ts  SOAP → GCS → product.imageUrl
│   ├── rpapos-product-image-probe.service.ts   Exploratory image availability probe
│   ├── rpapos-catalog-reset.service.ts  Dev/staging catalog wipe
│   ├── sinks/handler-sink.ts            → DataImportService (import handlers)
│   ├── sinks/rest-sink.ts               → Direct Kysely upserts
│   └── transformers/                    RPApos JSON → import row shape
└── infrastructure/
    ├── rpapos-http.adapter.ts           Tenant REST + WebForms login
    ├── rpapos-soap.adapter.ts           db4 SOAP (Objeto_Archivo_1, Catalogo_4)
    ├── rpapos-sat.adapter.ts            SAT Dispositivo_Registra_2
    ├── rpapos-connection.repository.ts
    ├── sync-run.repository.ts
    ├── id-map.repository.ts
    └── extraction-archive.repository.ts

Shared enums: packages/global/enums/rpapos.enums.ts

---

Catalog entities (planner scope)

These 14 catalog types are exposed in the migration planner (canonical load order):

Order	Entity key	UI label (EN)
1	moneda	Currencies
2	unidad_medida	Units of measure
3	plu_grupo	PLU categories
4	sku_grupo	SKU categories
5	produccion_grupo	Production groups
6	bodega	Locations / warehouses
7	proveedor	Suppliers
8	area	Dining areas
9	persona	People / CRM
10	sku	Raw materials (SKU)
11	plu	Products (PLU)
12	usuario	Employees
13	mesa	Tables
14	batch_maestro	Production batches

The PostgreSQL enum rpapos_entity_type also includes future types (compra, traslado, merma, etc.) that are not yet wired in the planner UI.

---

Documentation map

Page	Audience	Contents
Operator guide	Merchants / support	Wizard, planner, product images, SOAP token, troubleshooting
Architecture	Developers	Sync pipeline, sinks, dependencies, pause/cancel
FlowPOS API reference	Developers	/rpapos REST endpoints
External RPApos API	Developers	Tenant URLs, login, entity endpoints
Entity mapping	Developers	RPApos entity → FlowPOS tables / import types
Database schema	Developers	Integration tables + migrations

---

Environment variables

Variable	Where	Purpose
RPAPOS_LOGO_API_ORIGIN	Backend	Logo preview proxy (default https://ys.2rpa.com)
VITE_RPAPOS_LOGO_API_ORIGIN	PWA	Public <img> logo URL for tenant header
ENCRYPTION_KEY	Backend	Encrypts stored RPApos passwords in rpapos_connection
RPAPOS_DB4_SOAP_URL	Backend	Override db4 SOAP endpoint (default https://db4.2rpa.com/service.asmx)
RPAPOS_SAT_SOAP_URL	Backend	Override SAT SOAP endpoint (default https://sat.2rpa.com/service.asmx)
RPAPOS_SAT_REST_URL	Backend	Override SAT REST base for Cuenta_Validar_1 probe

---

Related docs

• Data Import Module — CSV/Excel bulk import
• Adding New Import Types — Extending HandlerSink import types
• FEL / RPAfelApi — Different integration (fel.rpapos.com electronic invoicing)