Especificación de API - Registro Masivo de Comercios

Este servicio permite realizar el registro masivo de comercios patrocinados por un Facilitador de Pagos mediante el procesamiento de archivos Excel.

Importante: Este flujo está diseñado para grandes volúmenes de datos. Cada comercio puede ser procesado en modo INSERT o UPDATE, dependiendo del campo operation.

Ambientes

Ambiente	Bucket S3 (entrada)	Bucket S3 (salida)	Observaciones
Desarrollo	`adq-massive-onboarding/payment-facilitator/LUMIO_SAC/IN/`	`adq-massive-onboarding/payment-facilitator/LUMIO_SAC/OUT/`	Nombre de archivo: `OMasivo_*.xlsx`
Producción	`adq-massive-onboarding/payment-facilitator/LUMIO_SAC/IN/`	`adq-massive-onboarding/payment-facilitator/LUMIO_SAC/OUT/`

Estructura del archivo de entrada (E)

Columna	Tipo	Longitud	Descripción	Requerido
operation	String	-	`INSERT` o `UPDATE` para definir acción por fila	Sí
merchant_code	String	UUID	Código único del comercio (solo en UPDATE)	Sí (solo UPDATE)
merchant_name	String	1 - 25	Nombre del comercio	Sí
merchant_category_code	String	4	MCC del comercio	Sí
company_name	String	Hasta 75	Nombre comercial	Sí
tax_identification_number	String	11 - 14	RUC o documento fiscal	Sí
tax_identification_type	String	Hasta 15	Tipo de documento fiscal (`RUC`, etc.)	Sí
tax_identification_country	String	2 caracteres	País (código ISO)	Sí
tax_identification_country_number	String	3 dígitos	Código numérico de país	Sí
tax_category	String	Hasta 50	Categoría tributaria	Sí
phone	String	9 - 30	Teléfono del comercio	No
website	String	Hasta 100	Página web	No
country	String	Hasta 10	Nombre del país	Sí
country_gov	String	2 caracteres	Código país ISO	Sí
city	String	1 - 29	Ciudad	Sí
state	String	1 - 200	Departamento o estado	Sí
postal_code	String	1 - 10	Código postal	Sí
address	String	1 - 60	Dirección	Sí
representative_name	String	1 - 140	Nombre del contacto legal	Sí
representative_lastname	String	1 - 140	Apellido del contacto legal	Sí
representative_document_type	String	-	Tipo de documento	Sí
representative_document_value	String	1 - 12	Número de documento	Sí
representative_work_position	String	1 - 80	Cargo del contacto legal	Sí
representative_email	String	-	Email del contacto legal	Sí
representative_phone	String	9 - 30	Teléfono del contacto legal	Sí
operational_name	String	1 - 140	Nombre del contacto operativo	Sí
operational_lastname	String	1 - 140	Apellido del contacto operativo	Sí
operational_document_type	String	-	Tipo de documento	Sí
operational_document_value	String	1 - 12	Número de documento	Sí
operational_work_position	String	1 - 80	Cargo del contacto operativo	Sí
operational_email	String	-	Email del contacto operativo	Sí
operational_phone	String	9 - 30	Teléfono del contacto operativo	Sí
services	String	-	JSON como string de servicios opcionales (tokenization, etc)	No
capture	String	-	JSON como string con configuración de captura	No
payment_methods	String	-	JSON como string con configuración de marcas, canales, etc.	Sí
payment-facilitator-code	String	UUID	Código del facilitador de pagos responsable	Sí

Estructura del archivo de salida (S)

Incluye las mismas columnas de entrada, más los siguientes campos adicionales:

Campo	Descripción
payment_methods_enabled	JSON con los métodos procesados exitosamente
payment_methods_failed	JSON con los métodos fallidos (si los hubo)
merchant_code	UUID asignado al comercio
merchant_alias	Alias generado según lógica del PF
brand_merchant_identifier	Identificador interno
merchant_credentials	JSON con `client_id` y `client_secret` generados (solo INSERT)
status	Estado del procesamiento: `success` / `error`
message	Mensaje descriptivo del resultado

En operaciones UPDATE, no se regeneran credenciales, se conservan las existentes.

Ejemplo de fila en archivo de entrada (INSERT/UPDATE)

Campo	Valor
operation	INSERT
merchant_name	COMERCIO LUMIO MSV 5
merchant_category_code	5001
company_name	COMERCIO LUMIO TEST
tax_identification_number	20110892999

Ejemplo	Archivo de Ejemplo
Archivo de entrada	OMasivo_07_072025_20613601000_E.xlsx

Ejemplo de fila en archivo de salida

Campo	Valor
status	success
message	Procesado correctamente.
merchant_code	53b49178-6d75-4150-a3dd-814308c87b41
merchant_credentials	{"client_id": ..., "client_secret": ...}
payment_methods_enabled	[{"method_name": "CARD", ...}]
payment_methods_failed	[]

Ejemplo	Archivo de Ejemplo
Archivo de salida	OMasivo_07_072025_20613601000_S.xlsx

Para errores de validación o procesamiento, el campo status será error y message detallará el motivo (por ejemplo: "RUC inválido", "marca no permitida", etc).