Diccionario de datos

Esta guía es para el equipo de desarrollo que va a construir su propio backoffice o integración sobre los datos de la plataforma. Lista todos los campos que existen hoy para los 3 dominios principales — transacción, comercio y terminal — más allá de lo que ya reciben por webhook.

No es un contrato de API — para el detalle exacto de endpoints, tipos y autenticación de cada servicio, consulta la documentación de integración correspondiente o contacta al equipo de plataforma.

Cómo se obtienen estos datos

Canal	Qué entrega	Cuándo usarlo
Webhooks en tiempo real	El subconjunto de campos relevante a cada evento (ver catálogo de eventos) — no la fila completa.	Reaccionar a cambios al momento (una venta nueva, un cambio de estado).
Partner Integration API (VPN)	Los campos completos de los 3 dominios listados en esta página. Requiere conexión por VPN dedicada.	Sincronización, reportería o backfill del lado de tu backoffice.

info

El acceso a la Partner Integration API se coordina por separado con el equipo de plataforma — no se autoprovisiona.

Campos que nunca se comparten

Un campo marcado No compartir en esta página existe en la plataforma pero se excluye de toda integración externa, incluida la Partner Integration API, por ser una credencial operativa y no un dato de negocio.

1. Transacción

Cada transacción procesada (venta, devolución, cancelación, etc.) se proyecta a un único registro con todos los campos siguientes: identificación, resultado del procesador, datos enmascarados de la tarjeta, y la telemetría del dispositivo que la originó.

Identificación

Campo	Tipo	Descripción
transaction_id	text	Identificador único de la transacción.
tenant_id	text	Tenant (instancia/marca) al que pertenece.
merchant_id	text	Comercio que originó la transacción.
terminal_id	text	Terminal física que la originó (= su número de serie).
reference_transaction_id	text	Transacción original a la que hace referencia (devoluciones/cancelaciones).
aggregator_id	text	Identificador asignado por el agregador/procesador.
processor_reference_id	text	Referencia devuelta por el procesador de pagos.
authorization_code	text	Código de autorización bancaria de la operación aprobada.

Clasificación y estado

Campo	Tipo	Descripción
operation_type	text	Tipo de operación (venta, devolución, cancelación).
channel	text	tpv, ecommerce, link o moto.
status	text	Estado de la transacción (aprobada, declinada, pendiente, etc.).
last_event_type	text	Último evento de negocio que actualizó este registro.

Montos y financiamiento

Campo	Tipo	Descripción
amount_minor	bigint	Monto en unidad menor (centavos).
currency	text	Moneda (p. ej. MXN).
tip_minor	bigint	Propina, en centavos, cuando aplica.
msi_installments	int	Meses sin intereses aplicados, si la venta usó una promoción.

Resultado del procesador

Campo	Tipo	Descripción
decline_reason	text	Motivo de rechazo, cuando no fue aprobada.
response_code	text	Código de respuesta crudo del procesador/red.
response_description	text	Descripción legible del código de respuesta.
tvr	text	Terminal Verification Result (diagnóstico EMV).

Tarjeta y procesador

Campo	Tipo	Descripción
masked_pan	text	Número de tarjeta enmascarado (nunca el PAN completo).
card_brand	text	Marca de la tarjeta (Visa, Mastercard, etc.).
card_type	text	Crédito/débito.
card_product	text	Producto específico de la tarjeta, si el procesador lo informa.
bank	text	Banco emisor, cuando el procesador lo informa.
processor	text	Procesador que liquidó la operación.

Ubicación

Campo	Tipo	Descripción
latitude / longitude	numeric	Coordenadas reportadas por la terminal al momento de la venta.

Disputas y voucher

Campo	Tipo	Descripción
dispute_status	text	open, won, lost, o vacío si no ha sido disputada.
voucher_access_token	text	Token que da acceso público al PDF del voucher de esta venta.

Telemetría del dispositivo (al momento de la venta)

Campo	Tipo	Descripción
device_iccid	text	ICCID de la SIM instalada.
device_imei	text	IMEI del dispositivo.
device_app_version	text	Versión de la app/firmware en el momento de la venta.
device_network_type	text	Tipo de red de datos (p. ej. 4G, WiFi).
device_network_operator	text	Operador de red celular.
device_connection_type	text	Tipo de conexión usada.
device_signal_level	int (0–100)	Nivel de señal.
device_is_roaming	bool	Si estaba en roaming.
device_wifi_ssid	text	Red WiFi conectada, si aplica.
device_battery_level	int (0–100)	Nivel de batería.
device_is_charging	bool	Si estaba cargando.
device_trace_id	text	Identificador de traza interno para esta operación.
device_integrator_reference	text	Referencia libre del integrador/APK que originó la venta.
device_software_version	text	Versión de software reportada.
device_sim_slot1 / device_sim_slot2	text	Identificador de SIM por ranura (dual-SIM).

Trazabilidad

Campo	Tipo	Descripción
created_at	timestamptz	Creación del registro.
updated_at	timestamptz	Última actualización (p. ej. cambio de estado o disputa).

info

Algunos datos que la terminal envía en el momento de la venta (p. ej. modo de entrada de tarjeta / CVM) todavía no se persisten en este registro. Si tu integración los necesita, es un ajuste puntual que el equipo de plataforma puede priorizar.

2. Comercio

El registro core del comercio es deliberadamente mínimo (identidad y estado); toda la información de negocio vive en un perfil extendido y en entidades relacionadas (afiliaciones, rutas de procesador, cuentas de depósito).

Identidad y estado (registro core)

Campo	Tipo	Descripción
id	text	Identificador único del comercio.
tenant_id	text	Tenant al que pertenece.
name	text	Nombre del comercio.
status	text	active / inactive — gate de seguridad principal: un comercio inactivo no puede transaccionar ni usar links de pago.
franchise_id	text	Franquicia/grupo al que pertenece, si aplica.
created_at / updated_at	timestamptz	Alta y última actualización del registro core.

Perfil general y persona de contacto

Campo	Tipo	Descripción
merchant_internal_id	text	Identificador interno/legado.
environment	text	Ambiente del perfil (producción, pruebas).
account_type	int	Tipo de cuenta del comercio.
first_last_name / second_last_name	text	Apellidos del responsable.
phone / email / support_email	text	Contacto y soporte.
commerce_responsible.first_name	text	Nombre(s) del responsable.
commerce_responsible.birth_date	date	Fecha de nacimiento del responsable.
commerce_responsible.document_type / .document_number	text	Identificación oficial del responsable.

Datos comerciales y fiscales

Campo	Tipo	Descripción
business_line	text	Giro comercial (catálogo MCC).
mcc	text	Merchant Category Code asignado.
financial.rfc	text	RFC del comercio.
financial.tax_name	text	Razón social / nombre fiscal.
commercial.tax_regime	text	Régimen fiscal.
commercial.address.{street, exterior_number, interior_number, zip_code, suburb, state, municipality}	text	Domicilio fiscal completo.
commercial.notification_recipients[]	array<{email, type}>	Correos adicionales que reciben notificaciones del comercio, cada uno con un tipo.

Configuración operativa

Campo	Tipo	Descripción
processing_config.dispersion_mode	enum	tef, 6am, 7am, 8am, 4pm, 11pm o manual.
processing_config.tpv_passcode	text	No compartir — código de acceso operativo para funciones sensibles en la TPV. Es una credencial, no un dato de negocio.
processing_config.payment_links_enabled	bool	Si el comercio puede generar links de pago.
processing_config.payment_links_min_amount_minor / .max_amount_minor / .max_active	bigint / bigint / int	Límites de monto y cantidad de links activos simultáneos.

Promociones (meses sin intereses / pagos fijos / skip payment)

Campo	Tipo	Descripción
processing_config.promotions.tpv.{plazo}.enabled	bool	Activa la promoción a ese plazo en TPV. Plazos: 3, 6, 9, 12, 18 meses.
processing_config.promotions.tpv.{plazo}.rate / .min_amount	numeric / bigint	Tasa y monto mínimo para ese plazo en TPV.
processing_config.promotions.ecommerce.{msi|pf|skp}.{plazo}.enabled	bool	Igual, para e-commerce y por tipo: msi (meses sin intereses, plazos 3/6/9), pf (pagos fijos) o skp (skip payment).
processing_config.promotions.ecommerce.{tipo}.{plazo}.rate / .min_amount	numeric / bigint	Tasa y monto mínimo por tipo y plazo en e-commerce.

Afiliaciones y ruteo por procesador

Campo	Tipo	Descripción
affiliation.channel / .processor_code / .affiliation_id / .status	text	Número de afiliación del comercio, específico por canal y procesador.
route.channel / .processor_code / .status	text	Procesador por defecto para cada canal, cuando ninguna regla de BIN aplica.
routing_rule.channel / .match_type / .bin_start,.bin_end / .bin_values / .processor_code / .priority / .status	mixto	Regla de ruteo a un procesador específico según rango o lista de BIN, evaluada en orden de prioridad.

Cuenta(s) de depósito

Campo	Tipo	Descripción
bank_name	text	Banco de la cuenta.
account_holder	text	Titular.
account_number_masked	text	Número de cuenta, enmascarado.
clabe_masked	text	CLABE interbancaria, enmascarada.
currency	text	Moneda de la cuenta.
notification_email	text	Correo que recibe notificaciones de depósito/dispersión.
status	text	Estado de la cuenta de depósito.
updated_by	text	Usuario que hizo el último cambio.

info

El perfil extendido también reserva dos bloques — webhook y element — que existen en el modelo de datos pero hoy ninguna pantalla del backoffice interno los usa; no se documentan sub-campos porque no tienen contenido real todavía.

3. Terminal

Cada terminal física registrada reúne su configuración de negocio, su telemetría de salud más reciente, y su historial de asignación a números de serie. El identificador de la terminal (terminal_id) es, en la práctica, su número de serie.

Identidad y configuración

Campo	Tipo	Descripción
id	text	Identificador de la terminal (= número de serie físico).
tenant_id / merchant_id	text	Tenant y comercio al que pertenece.
processor_code	text	Procesador asignado.
status	text	active / inactive.
brand / model	text	Marca y modelo (catalogados — ver catálogo abajo).
operating_mode	text	Modo de operación.
emv_enabled / contactless_enabled	bool	Si EMV/contactless están habilitados.
created_at / updated_at	timestamptz	Alta y última actualización.

Conectividad reportada

Campo	Tipo	Descripción
connectivity_status	enum	Calculado: connected, disconnected o never_reported, según la última señal de salud.
sim_slot_1 / sim_slot_2	text	Identificador de SIM por ranura.
imei	text	IMEI reportado más recientemente.
software_version	text	Versión de software/firmware reportada más recientemente.

Señal de salud (telemetría, último reporte)

Campo	Tipo	Descripción
acked	bool	Si la señal ya fue revisada por operación.
signal_level / battery_level	int (0–100)	Nivel de señal celular / batería.
connection_type / network_type / network_operator	text	Tipo de conexión, tipo de red y operador celular.
wifi_ssid	text	Red WiFi conectada, si aplica.
is_roaming / is_charging	bool	Roaming / cargando.
imei / iccid	text	IMEI e ICCID reportados en esta señal.
app_version	text	Versión de la app/firmware reportada.
trace_id / integrator_reference	text	Identificadores internos de traza y del integrador/APK.
observed_at	timestamptz	Momento en que se observó la señal (puede diferir de cuándo llegó al servidor).

Asignación de dispositivo físico

Campo	Tipo	Descripción
serial_number	text	Número de serie físico asignado a esta terminal lógica.
terminal_id / merchant_id / tenant_id	text	A qué terminal, comercio y tenant está asignado el equipo.
status	text	Estado de la asignación (permite reasignar el equipo físico si se retira).

Catálogo de marca / modelo

Campo	Tipo	Descripción
brand.code / .name / .active	text / text / bool	Catálogo de marcas disponibles para asignar.
model.code / .brand_code / .name / .active	text / text / text / bool	Catálogo de modelos, cada uno ligado a su marca.

info

Existen además tablas puramente internas de seguridad de la terminal (llave encriptada de sesión, hash de API key, tokens de sesión de la app TPV). No se listan aquí porque son de uso exclusivo de la plataforma para autenticar a la terminal — no aportan información de negocio.

Qué sigue

• Integrar webhooks — catálogo de eventos y forma del payload en tiempo real.
• Para acceso a la Partner Integration API (VPN), contacta al equipo de plataforma.