RPApos Gateway — FlowPOS API

REST API exposed by FlowPOS backend (RpaposController). Base path: /rpapos. All routes require Firebase Bearer auth unless noted.

Swagger tag: RPApos Gateway (when backend is running).

Document version: 1.0 · Last updated: 2026-05

---

Connections

Method	Path	Description
POST	/rpapos/connections	Create connection (encrypts password)
GET	/rpapos/connections?businessId={uuid}	List connections for business
GET	/rpapos/connections/:id	Get connection (masked credentials)
PATCH	/rpapos/connections/:id	Update connection
DELETE	/rpapos/connections/:id	Delete connection (204)
POST	/rpapos/connections/:id/clear-error?businessId={uuid}	Clear last_error, set status active

Create connection body

{
  "businessId": "uuid",
  "subdomain": "lafabrica",
  "usuario": "admin",
  "password": "secret",
  "apiKey": "optional",
  "satUsuario": "optional-sat-user",
  "satPassword": "optional-sat-password",
  "timezone": "America/Guatemala",
  "currencyCode": "GTQ",
  "tipoGestionMap": { "LOCAL": "dineIn" },
  "syncIntervalMinutes": null
}

Connection response (masked)

Passwords are never returned. Response includes hasApiKey, hasSoapToken, status (active | disconnected | error), lastSyncedAt, lastError, etc. SAT passwords are never returned.

Method	Path	Description
POST	/rpapos/connections/:id/refresh-soap-token?businessId={uuid}	Register SAT device via Dispositivo_Registra_2; store encrypted SOAP token + connection metadata

---

Probe & preview (no persistence)

Method	Path	Description
POST	/rpapos/connections/probe-subdomain	Ping tenant login page; no credentials
POST	/rpapos/connections/probe	Test tenant web credentials + record counts
POST	/rpapos/connections/probe-sat	Test SAT credentials (Cuenta_Validar_1)
GET	/rpapos/connections/logo-preview?subdomain={sub}	Tenant logo PNG (base64) + custom vs fallback
POST	/rpapos/connections/preview-samples	Sample rows per entity (stored credentials)

Probe subdomain

{ "subdomain": "lafabrica" }

Response: { "ok": boolean, "displayName": string | null }

Probe connection

{
  "subdomain": "lafabrica",
  "usuario": "admin",
  "password": "secret"
}

Response:

{
  "ok": true,
  "tenantDisplayName": "lafabrica",
  "recordCounts": {
    "plu": 120,
    "sku": 45,
    "proveedor": 12
  }
}

Note: Swagger mentions Redis caching for probe counts; the current implementation performs a live login and count on each request. Counts are returned only for this subset: plu, sku, proveedor, unidad_medida, moneda, plu_grupo, sku_grupo, bodega, area, usuario — not mesa, persona, produccion_grupo, batch_maestro, etc.

Probe SAT credentials

{
  "subdomain": "lafabrica",
  "usuario": "sat-user-or-tenant-user",
  "password": "secret"
}

Validates via SAT Cuenta_Validar_1 (REST). Use before saving SAT fields on a connection or when troubleshooting image import.

Preview product images (exploratory)

{
  "businessId": "uuid",
  "connectionId": "uuid",
  "sampleLimit": 5,
  "imgGrabProbeLimit": 3
}

Probes SOAP Objeto_Archivo_1, Catalogo_4, optional REST image endpoints, and returns availability classification (for support / dev — not used by the planner wizard today).

Preview samples

Uses stored connection credentials (not the planner password field).

{
  "businessId": "uuid",
  "connectionId": "uuid",
  "entities": ["plu", "plu_grupo"],
  "limit": 10
}

• limit capped at 25 server-side.
• Fetches full entity payloads from RPApos; returns first N rows + meta.total / meta.shown per entity.

Reset catalog (dev/staging only)

{ "businessId": "uuid" }

Deletes RPApos-imported catalog rows and all rpapos_id_map entries for the business. Forbidden when DEPLOY_ENV is production. Exposed in the planner on localhost / development / staging.

---

Sync

Method	Path	Description
POST	/rpapos/sync	Start async sync run

Trigger sync body

{
  "businessId": "uuid",
  "connectionId": "uuid",
  "mode": "catalog",
  "entities": ["plu", "plu_grupo"],
  "dateFrom": "2026-01-01T00:00:00.000Z",
  "dateTo": "2026-12-31T23:59:59.999Z",
  "targetLocationId": "uuid",
  "importProductImages": true,
  "importProductImagesOnly": false
}

Field	Notes
mode	catalog | custom | historical | incremental
entities	Optional; omitted + catalog = full catalog. Empty array + importProductImagesOnly = images-only run
dateFrom / dateTo	Reserved for historical modes (catalog sync ignores today)
targetLocationId	FlowPOS location.id for dining area/table mapping
importProductImages	After catalog entities, run SOAP image import (auto-includes plu in entity list when needed)
importProductImagesOnly	Requires importProductImages: true; skips catalog entities; backfills images from existing PLU id map

Response: { "syncRunId": "uuid" } — poll status via sync-runs endpoints.

Planner mapping:

UI option	mode	entities
Everything	catalog	omitted
Quick start	custom	fixed 10-entity list
Custom	custom	user selection
Custom (images only)	custom	[] + importProductImagesOnly: true

---

Sync runs

Method	Path	Description
GET	/rpapos/sync-runs?connectionId={uuid}	List runs for connection
GET	/rpapos/sync-runs/:id	Run status + perEntityStats
GET	/rpapos/sync-runs/:id/product-image-import-job?businessId={uuid}	Resolve import_job for this run's product-image step (options.syncRunId)
POST	/rpapos/sync-runs/:id/pause	Set paused=true
POST	/rpapos/sync-runs/:id/resume	Set paused=false
POST	/rpapos/sync-runs/:id/cancel	Set status cancelled

Per-entity stats shape

{
  "plu": {
    "extracted": 100,
    "loaded": 98,
    "failed": 2,
    "status": "completed"
  }
}

status: pending | running | completed | failed | skipped

Synthetic key product_images (not an rpapos_entity_type enum value) is added when image import is requested:

{
  "product_images": {
    "extracted": 120,
    "loaded": 95,
    "failed": 3,
    "status": "completed"
  }
}

---

PWA client

apps/frontend-pwa/src/services/rpaposService.ts wraps the above via the shared api() helper (authenticated).

Public logo URL helper (no auth):

rpaposTenantLogoUrl("lafabrica")
// → https://ys.2rpa.com/api/logo?subDominio=lafabrica

Override with VITE_RPAPOS_LOGO_API_ORIGIN.