Validación de TAP
OmniRoam valida archivos TAP contra las reglas verificables en GSMA TD.57 y GSMA TD.32. Puedes validar un archivo TAP entrante o un archivo TAP saliente a través de la API.
Tabla de Contenidos
- Cómo Validar un Archivo
- Verificaciones de Validación
- Severidad de Errores
- Categorías de Códigos de Error
- Verificar un Archivo Entrante de un Socio
- Generar un Archivo RAP
- Monitorear un Directorio Entrante
- Límites de Validación
Cómo Validar un Archivo
Utiliza la API para validar un archivo TAP.
| Endpoint | Propósito |
|---|---|
GET /api/tap_validate_in/:filename | Validar un archivo TAP entrante. |
GET /api/tap_validate_out/:filename | Validar un archivo TAP saliente. |
La respuesta informa si el archivo es válido y cuenta los hallazgos por severidad. Cada hallazgo contiene el código de error, la severidad, la ubicación y un mensaje. Consulta la Referencia de API HTTP.
Verificaciones de Validación
OmniRoam ejecuta cuatro grupos de verificaciones sobre un archivo TAP decodificado.
| Grupo | Verificaciones |
|---|---|
| Estructura | Las cinco secciones obligatorias están presentes y no están en blanco: batchControlInfo, accountingInfo, networkInfo, auditControlInfo y callEventDetails. |
| Control de lote | El sender y el recipient tienen 5 caracteres. El fileSequenceNumber tiene 5 caracteres. El specificationVersionNumber es 3. |
| Contabilidad | El localCurrency y el tapCurrency son códigos ISO 4217 de 3 letras. El tapDecimalPlaces es un entero no negativo. |
| Aritmética de auditoría | El conteo de registros es igual al número de eventos de llamada. El cargo total, el impuesto total y el descuento total son iguales a las sumas de los registros. |
Severidad de Errores
OmniRoam informa cada hallazgo con una severidad. El archivo es válido solo cuando no hay hallazgos fatales.
| Severidad | Efecto |
|---|---|
| Fatal | Se rechaza todo el archivo. |
| Severo | Se rechaza el registro individual. El resto del archivo es aceptado. |
| Advertencia | El registro es facturable. El hallazgo es informativo. |
Categorías de Códigos de Error
TD.57 agrupa los códigos de error en rangos numéricos.
| Rango | Categoría |
|---|---|
| 10 a 19 | Error de formato o sintaxis. |
| 20 a 29 | Valor fuera de rango. |
| 30 a 49 | Estructura de grupo no válida. |
| 50 a 59 | Error general de ASN.1 o de codificación. |
| 100 a 199 | Inconsistencia entre campos. |
| 200 a 249 | Error específico, como un duplicado, un error de IOT o datos antiguos. |
| 9000 a 9999 | Un error bilateral y propietario acordado entre dos socios. |
Verificar un Archivo Entrante de un Socio
POST /api/tap_inbound_check ejecuta cada verificación que un receptor realiza antes de facturar un archivo TAP de un socio. La solicitud nombra el archivo, ya sea uno que ya esté en TAP_In o una copia cargada, y lleva lo que el operador sabe sobre la relación: su propio TADIG, los TADIGs del socio, sus propios prefijos IMSI, las tarifas del acuerdo y la fecha de inicio del roaming comercial. También puede llevar los plazos BA.08 y las tasas de cambio BA.11.
La respuesta da un veredicto para el archivo, el estado de cada verificación y cada hallazgo con su código de error TD.57 y severidad.
| Veredicto | Significado |
|---|---|
accept | No hay hallazgos fatales o severos. El archivo es facturable. |
aged_records | El archivo es bueno, excepto por los registros que superan el límite de antigüedad de la llamada. Esos registros son devueltos; el resto son facturables. |
reject_records | Algunos registros tienen hallazgos severos. Esos registros son devueltos; el resto son facturables. |
reject_file | El archivo tiene un hallazgo fatal y se devuelve completo. |
ignore_copy | El archivo es una copia idéntica de uno ya recibido. TD.57 dice que se ignore. |
| Verificación | Regla | Código y severidad TD.57 |
|---|---|---|
structure | La estructura, control de lote, contabilidad y auditoría mencionadas anteriormente. | Como arriba |
parties | El remitente es el socio del acuerdo y el destinatario somos nosotros. | 100, fatal |
file_name | El tipo de nombre del archivo, remitente, destinatario y secuencia coinciden con el control de lote. | 100, fatal |
sequence | El número de secuencia tiene 5 dígitos y no se ha utilizado ya para contenido diferente. Un hueco nombra los archivos faltantes. Un archivo que devolvimos con un retorno fatal puede volver bajo la misma secuencia, y debe llevar el número de secuencia del archivo RAP de nuestro RAP. Un número de secuencia de archivo RAP en cualquier otro archivo es una advertencia. | 10, 20, 201 fatal; 37, 40, 200 advertencia |
timestamps | Las marcas de tiempo de corte y disponibilidad son válidas y están en orden, y el archivo no se hizo disponible más de una hora después de haber llegado. | 100, 104 fatal; 101 advertencia |
transmission | El archivo llegó dentro de los plazos de transmisión de archivos BA.08. | 262 advertencia; 263 fatal |
exchange_rates | La tabla de conversión de moneda está completa y no tiene duplicados, cada código que usa un registro está definido y cada tarifa coincide con BA.11. | 30 a 34, 200, 201 fatal; 101 severo |
call_window | Las marcas de tiempo de llamada más tempranas y más recientes coinciden con los registros. | 100, advertencia |
imsi | El IMSI de cada registro es uno de los nuestros. | 20, 30, 200, severo |
records | El código de desplazamiento UTC y la entidad de grabación de cada registro están definidos en el archivo, y el registro no comienza después del corte. | 100, severo; el corte es una advertencia |
commercial_start | No hay registros facturables antes de la fecha de inicio del roaming comercial. | 200, severo |
charges | Cada cargo coincide con la tarifa del acuerdo para ese servicio y fecha, dentro de 0.02 unidades de moneda TAP (sección 5.8 de TD.57). Las unidades cobradas coinciden con el redondeo. | 200, 100, severo |
duplicates | Ningún registro repite uno ya recibido del socio, o de otro en el mismo archivo. | 250, 251, 255, severo |
call_age | Ningún registro es más antiguo que el límite de antigüedad de la llamada, 30 días por defecto. Los registros más antiguos no necesitan ser aceptados, por lo que se rechazan a menos que la verificación se ejecute con accept_aged, que los mantiene como registros antiguos. | 261 severo; 260 advertencia cuando se aceptan |
Una verificación cuyos datos de referencia la solicitud no proporcionó se informa como not_run, con la razón.
Nunca cuenta como un pase.
Cada hallazgo de cargo y unidades cobradas muestra los valores esperados y reales en dinero o bytes, la diferencia y cómo se calculó el valor esperado. Cuando las unidades cobradas del socio son todos múltiplos enteros de un paso mayor que el redondeo del acuerdo, el hallazgo nombra ese paso.
Cuando el acuerdo tiene tarifas, el bloque money del informe totaliza el archivo en unidades de moneda TAP:
| Campo | Significado |
|---|---|
declared | El total que el socio cobró. |
at_agreement | Los mismos registros valorados a las tarifas del acuerdo. |
payable | El cargo sobre los registros que no son rechazados. |
rejected | El cargo sobre los registros rechazados. |
rejected_at_agreement | Lo que costaron los registros rechazados a las tarifas del acuerdo. |
overcharge | declared menos at_agreement. |
Generar un Archivo RAP
POST /api/rap_generate toma la misma solicitud, ejecuta las mismas verificaciones y construye el archivo TD.32 RAP 1.5 que devuelve el archivo TAP del socio.
| Hallazgo | Contenido RAP |
|---|---|
| Un hallazgo fatal | Un retorno fatal para todo el archivo. |
| Hallazgos severos | Un retorno severo para cada registro rechazado, con el registro original y el contexto de error de cada hallazgo. |
| Un hueco de secuencia | Un archivo RAP separado con un retorno faltante para el hueco. |
Sin commit, la solicitud es una vista previa. OmniRoam no reserva un número de secuencia RAP y no
escribe un archivo. Con commit, OmniRoam reserva el siguiente número de secuencia RAP para el socio y
escribe el archivo en rap_output_path. Los datos facturables se devuelven en un archivo RC y los datos de prueba en un archivo RT. OmniRoam no envía el archivo RAP al socio.
OmniRoam guarda cada archivo RAP que escribe. Un archivo TAP, o un rango faltante, que ya tiene un RAP recibe
ese RAP de vuelta, nunca un nuevo número de secuencia: TD.32 dice que una retransmisión mantiene su número. Comprometerlo de nuevo escribe el mismo archivo de vuelta en rap_output_path si ya no está allí, por lo que se envía
nuevamente. Cada archivo de respuesta tiene already_sent y, para uno ya escrito, written_at.
counters.yaml contiene un número de secuencia RAP para cada socio, por lo que los archivos RAP solo se envían como
config.inbound_check.home_tadig. Una solicitud para enviar uno como cualquier otra red es rechazada.
| Configuración | Ubicación | Propósito |
|---|---|---|
config.rap_output_path | config.yaml | El directorio al que se escriben los archivos RAP comprometidos, en una carpeta para cada socio. |
<partner TADIG>: RC y RT | counters.yaml | El siguiente número de secuencia RAP para el socio. Comienza cada uno en 1. |
La generación de RAP necesita el rol exporter.
Monitorear un Directorio Entrante
OmniRoam puede monitorear el directorio en el que llegan los archivos TAP de los socios, por ejemplo, una entrega FTP, y
verificar cada nuevo archivo una vez. Un archivo se verifica cuando su tamaño y hora de modificación no han cambiado
durante settle_seconds, por lo que se deja en paz una transferencia en progreso. OmniRoam guarda cada informe y solo
verifica un archivo nuevamente si cambia.
| Configuración | Propósito |
|---|---|
config.inbound_check.watch_path | El directorio a monitorear. |
config.inbound_check.home_tadig | Nuestro TADIG, que cada archivo debe nombrar. |
config.inbound_check.interval_seconds | Con qué frecuencia se escanea el directorio. |
config.inbound_check.settle_seconds | Cuánto tiempo debe permanecer sin cambios un archivo antes de ser verificado. |
config.inbound_check.max_call_age_days | Los registros más antiguos que este número de días son rechazados a menos que se acepten como registros antiguos. Generalmente 30. |
config.inbound_check.ba08 | Opcional. Los plazos de transmisión de archivos BA.08, standard_transmission_hours y exceptional_transmission_hours. |
Nuestros prefijos IMSI son config.home_plmns. Los TADIGs y tarifas de cada remitente provienen de los acuerdos de
gestión de roaming que guarda la sincronización de roaming. Un archivo de un remitente sin acuerdo falla la
verificación de partes, y sus cargos no se verifican.
| Endpoint | Propósito |
|---|---|
GET /api/tap_inbound_checks | Los archivos verificados, el más nuevo primero, con el remitente, veredicto y conteos. Filtrar con sender. |
GET /api/tap_inbound_checks/:filename | El informe completo para un archivo. |
GET /api/tap_inbound_rap/:filename | Verifica el archivo nuevamente y previsualiza su RAP. No se reserva ni se escribe nada. Agrega accept_aged=true para mantener registros más allá del límite de antigüedad de la llamada. |
PUT /api/tap_inbound_rap/:filename | Verifica el archivo nuevamente, reserva la secuencia RAP y escribe el RAP en rap_output_path. Necesita el rol exporter. |
Ambos endpoints RAP devuelven el archivo RAP en sí, para que pueda ser descargado y enviado al socio.
| Endpoint | Propósito |
|---|---|
GET /api/tap_inbound_stop_return/:partner | Previsualiza un retorno de detención para un socio cuyos archivos TAP han parado. Su último número de secuencia es el último archivo recibido en la ruta de monitoreo, o 99999 cuando no ha habido ninguno. Agrega test=true para los datos de prueba del socio. |
PUT /api/tap_inbound_stop_return/:partner | Escribe el retorno de detención. Un retorno de detención para la misma última secuencia no se numera nuevamente. Necesita el rol exporter. |
GET /api/rap_sent | Cada archivo RAP que OmniRoam escribió, el más nuevo primero: el socio, secuencia, tipo de retorno y el archivo TAP que devolvió. |
GET /api/rap_sent/:filename | Un archivo RAP que OmniRoam escribió, con el archivo en sí en file_b64. |
Las métricas se cuentan a partir de los informes almacenados, por lo que sobreviven a un reinicio.
| Métrica | Etiquetas |
|---|---|
tap3_inbound_check_files_total | sender, verdict |
tap3_inbound_check_findings_total | sender, check, severity, code |
tap3_inbound_check_records_total | sender |
tap3_inbound_check_records_rejected_total | sender |
tap3_inbound_check_last_timestamp | ninguno |
Las reglas de alerta para archivos y registros rechazados, desajustes de cargos, IMSIs que no son nuestros,
duplicados y huecos de secuencia están en packaging/prometheus/omniroam-tap-inbound-alerts.yml.
Límites de Validación
Los endpoints de validación verifican las reglas que solo necesitan el contenido del archivo. La verificación entrante agrega las reglas que necesitan el acuerdo, los archivos ya recibidos y los datos de referencia BA.08 y BA.11. Estas reglas no se verifican.
- Las listas de códigos TADIG.
- Búsquedas completas de moneda ISO 4217 y números E.164.
- Tipos de llamada y bandas de tiempo más allá de los datos de tarifas de voz y SMS del acuerdo.
- Cuando los archivos TAP de un socio han parado. Un retorno de detención se escribe a mano con
/api/tap_inbound_stop_return.
Utiliza un acuse de recibo del socio o un archivo RAP para confirmar el resultado de la liquidación. Consulta Procesamiento de RAP.