NC-IED E S T Á N D A R G E N E R A L P A R A I N T E R C A M B I O E L E C T R Ó N I C O D E D A T O S N O R M A C O M P L E M E N T A R I A

(1)

N O R M A C O M P L E M E N T A R I A

E S T Á N D A R G E N E R A L P A R A I N T E R C A M B I O

E L E C T R Ó N I C O D E D A T O S

SERIE DE NORMAS Y PROCEDIMIENTOS

NC-IED

(2)

N O R M A C O M P L E M E N T A R I A

E S T Á N D A R G E N E R A L

P A R A I N T E R C A M B I O

E L E C T R Ó N I C O D E D A T O S

SERIE DE NORMAS Y PROCEDIMIENTOS

(3)

Edición: 3

Público Vigencia: 26-12-2006

Tabla de contenido

1. Introducción ... 1

2. Alcance ... 1

3. Términos empleados ... 2

4. Documentos aplicables y anexos ... 2

5. Archivos con lotes de operaciones ... 2

5.1. Consideraciones generales... 2

5.1.1. Estructura del archivo ...2

5.1.2. Comentarios ...4

5.1.3. Generación de errores ...4

5.1.3.1. Formato del archivo de errores ...5

5.2. Validación de estructura del archivo... 5

5.3. Validación de contenido ... 7

5.3.1. Validaciones generales ...7

5.3.2. Encabezado ...9

5.3.2.1. CICLO ...9

5.3.2.2. ENTIDAD ...9

5.3.3. Bloque de Datos ... 10

5.3.3.1. Nodo de Datos ... 10

5.3.3.2. RESUMEN ... 10

6. Validaciones adicionales para archivos SCL ... 10

7. Procesamiento de operaciones en Tiempo Real ... 11

(4)

Sistema Nacional de Pagos Electrónicos

Sistemas de Pago - BCCR Año 2006

1. Introducción

Este documento es un material de apoyo para los participantes en los servicios electrónicos del Sistema Nacional de Pagos Electrónicos (SINPE) que utilizan archivos para la importación de operaciones o tienen un funcionamiento en tiempo real mediante el uso de WebServices - Servicios de Liquidación Bruta (SLB), o cuya operativa se basa en la compensación y liquidación de lotes de operaciones - Servicios de Compensación y Liquidación (SCL).

Para los servicios SCL y la importación en SLB se describen las generalidades del estándar electrónico para un archivo de intercambio electrónico de datos, y en combinación con los estándares particulares de cada servicio, sirve como referencia para que los departamentos de informática de las entidades verifiquen el estado de sus sistemas internos e identifiquen los ajustes necesarios para facilitar la generación y recepción de archivos estandarizados para el Sistema de Pagos.

Es importante destacar que la validación de archivos se lleva a cabo en forma distribuida, prácticamente en un 100%, en los nodos ubicados en las instalaciones de los diferentes participantes. Debido a esta particularidad, un proceso vital para cada usuario será la ejecución del proceso de validación desde un nodo del SINPE, ya que si el mismo no es exitoso no existe posibilidad de realizar el envío del archivo o la importación de las operaciones.

Este procesamiento distribuido constituye una gran ventaja operativa, ya que el éxito en la validación del archivo prácticamente garantiza que el mismo será procesado sin mayores dificultades. Sin embargo, para los servicios SCL es posible que después de la validación existan errores menores que, en todo caso, serán detectados en el momento de la transmisión. Este tipo de errores de describen en la sección 6 de este documento.

Adicionalmente, para los servicios que procesan las operaciones en tiempo real mediante la comunicación de los sistemas de las entidades y el SINPE, se describen los aspectos comunes para dicha comunicación, como por ejemplo el manejo de las excepciones.

2. Alcance

Este documento debe ser utilizado por cada uno de los participantes en el Sistema Nacional de Pagos de Costa Rica y que necesiten hacer uso de alguno de los servicios del SINPE.

(5)

Edición: 3 Público Vigencia: 26-12-2006

2

3. Términos empleados

Para los fines del presente documento, se entenderá por:

 BCCR: Banco Central de Costa Rica.

 SCL: Servicios de Compensación y Liquidación.

 SINPE: Sistema Nacional de Pagos Electrónicos.

 SLB: Servicios de Liquidación Bruta.

 XML: eXtensible Markup Language, el cual es un formato universal para documentos estructurados.

Para consultar algún otro término que se utilice en este documento, remítase a la Norma complementaria - Glosario general.

4. Documentos aplicables y anexos

Siglas Nombre del documento

NC-CC Norma complementaria - Cuenta Cliente (CC) e IBAN.

NC-GG Norma complementaria - Glosario general.

5. Archivos con lotes de operaciones

5.1. Consideraciones generales

5.1.1. Estructura del archivo

Los archivos para el intercambio electrónico de datos del SINPE tienen un formato conocido como XML que constituye un formato universal para documentos estructurados.

Su estructura puede ser diferente dependiendo del tipo de información que se quiere almacenar, pero siempre deben estar “bien formados” según los estándares del W3C (www.w3c.org/) y ser válidos según las normas de validación del SINPE para cada uno de los servicios electrónicos.

De manera muy general, un archivo XML está compuesto por una estructura jerárquica de nodos, donde cada nodo está identificado por una etiqueta (Tag) de inicio que tiene la siguiente forma “<Etiqueta>”.

Cada nodo con una etiqueta de inicio, debe contar con una etiqueta de cierre, de la siguiente forma “</Etiqueta>”. El contenido del nodo está representado por los datos entre la etiqueta de inicio y de cierre, y puede estar compuesto por otros nodos anidados y / o por atributos, estos últimos están ubicados luego de la etiqueta del nodo, y deben seguir el siguiente formato NombreAtributo=”Valor”.

(6)

Las etiquetas de los nodos deben estar en mayúsculas y los nombres de los atributos deben seguir el estándar de PascalCasing, definiendo cada letra de inicio de palabra con mayúscula y el resto con minúscula. Además, el nodo principal del archivo debe ser <SINPEDOCUMENTOXML>.

A continuación se presenta un ejemplo de un archivo bien formado siguiendo los estándares propuestos.

<NODO1 PrimerAtributo="Valor 1"

SegundoAtributo="Valor 2"/>

<NODO2>

</NODO2>

</SINPEDOCUMENTOXML>

Los archivos de intercambio electrónico de datos se componen de dos estructuras principales conocidas como encabezado y bloque de datos.

El encabezado identifica los datos generales del archivo, como el servicio al que pertenece el archivo, la entidad que utiliza el servicio, y cuál es su propósito (si contiene datos que son enviados al SINPE para su procesamiento o como resultado de devoluciones). Si algún servicio contiene información específica en el encabezado del archivo, esto se indicará en su estándar particular.

El archivo puede contener uno o varios bloques de datos, según se indique en el estándar electrónico de cada servicio. Dentro de cada bloque de datos, hay un nodo por cada documento que es enviado para cobro o devolución, o que es importado en el SINPE. La etiqueta del nodo que representa una operación dependerá del estándar específico del servicio implementado. Además, como último nodo del bloque de datos debe existir un nodo de resumen que contiene información de verificación de la cantidad de registros y el monto total sin distinción de moneda del bloque.

A continuación se presentan los nodos en un archivo válido para intercambio electrónico de datos. Para efectos de este ejemplo, se utiliza como etiqueta REGISTROS como bloque de datos y para cada nodo de documento la etiqueta REGISTRO, aunque las mismas dependerán de los estándares particulares de cada servicio.

(7)

Edición: 3 Público Vigencia: 26-12-2006

4

<CICLO... />

<ENTIDAD... />

</ENCABEZADO>

<REGISTRO... />

...

<RESUMEN... />

</REGISTROS>

</SINPEDOCUMENTOXML>

Nodo de Encabezado

Final del nodo de Encabezado Nodo de Bloque de Datos

Final Nodo de Bloque de Datos Nodo Principal para los

archivos del SINPE

Nodo de Datos

Resumen de Nodos de Datos

Final del Nodo Principal

Las generalidades de la estructura de un archivo de intercambio electrónico de datos se describen en los puntos siguientes.

5.1.2. Comentarios

Cuando se elabora un archivo de intercambio electrónico de datos, se permite que la entidad que lo genera incluya comentarios, los cuales deben colocarse entre “<! --“ y “-- >”, caracteres que indican que su contenido debe ser ignorado por la validación del archivo. Esta facilidad permite contar con una documentación interna del archivo para la entidad, sin embargo, es importante recordar que durante el proceso de validación estos comentarios son eliminados.

El uso de estos comentarios depende de cada entidad, sin embargo, debe ser restringido ya que su utilización puede afectar el rendimiento en el proceso de validación.

5.1.3. Generación de errores

Existe una rutina que se encarga de validar cada línea del archivo y emitir un listado detallado de cada error encontrado en un archivo de salida. Este archivo puede ser examinado posteriormente por el personal indicado y ser usado como fuente primaria para la corrección respectiva. Es importante rescatar que cualquier error de una severidad distinta a advertencia dentro del archivo, es motivo suficiente para considerarlo no apto para ser enviado al SINPE para su procesamiento.

(8)

5.1.3.1. Formato del archivo de errores

El archivo de errores que se genera también se encuentra en formato XML y se compone de un nodo principal “SINPEERRORESXML” que contendrá un nodo por cada error que se haya encontrado en el archivo.

Un ejemplo de la estructura del archivo de errores es el siguiente:

<ERROR NumNodo="9" NumAtributo="2" Descripcion="El Código ...." Tipo="2"

Severidad="2">

<DATOS>

<REGISTRO... />

</DATOS>

</ERROR>

<DATOS>

<REGISTRO... "/>

</DATOS>

</ERROR>

</SINPEERRORESXML>

Cada registro de error, contiene los siguientes atributos:

 NumNodo: Indica el Nodo del archivo XML donde se detectó el error.

Este número se determina en un recorrido Preorden de los nodos del archivo.

 NumAtributo: Número de Atributo que no pasó la validación.

 Descripcion: Descripción del Error.

 Tipo: Indica si el error es de estructura (1) o de datos (2).

 Severidad: Indica si el error es una advertencia (un dato no se pudo validar porque otro relacionado no pasó la validación), un error normal (error de datos) o un error fatal (generalmente un error de estructura que no permite la validación del resto del archivo).

 Nodo DATOS: Contiene el nodo del archivo (REGISTRO) que provocó el error cuando el error permita identificar y obtener dicho nodo.

5.2. Validación de estructura del archivo

Este proceso verifica que la estructura del archivo sea válida. Las validaciones de estructura no toman en cuenta los datos que viajan en el archivo, sin embargo existe un proceso de validación de contenido que sí lo hace. Las generalidades de este proceso de validación de contenido, se explican en el punto 5.3 de este documento, y sus particularidades en el estándar electrónico de cada servicio.

Nombre del archivo:

El nombre del archivo debe ajustarse a la siguiente estructura aaaammdd-

(9)

Edición: 3 Público Vigencia: 26-12-2006

6 pero, adicionalmente, podrán estar presentes archivos con las extensiones

“.Resumen” y “.Resultado”, los cuales contienen un resumen del archivo de datos (bilateral) y un multilateral neto respectivamente. El valor de los componentes del nombre del archivo corresponden a:

aaaa Año del ciclo de compensación.

mm Mes del ciclo de compensación.

dd Día del ciclo de compensación.

EEE Código de entidad origen.

SS Código de servicio según corresponda.

ss Sesión del ciclo (Envío o devoluciones). Para los servicios en línea está sesión debe ser siempre 01.

cc Consecutivo de sesión, en caso de que este consecutivo sea menor a 10, debe colocarse un 0 a la izquierda para rellenar, es decir, un archivo con consecutivo 5, debe tener 05 en el nombre.

Cantidad mínima de datos:

Todo archivo debe contener el nodo <SINPEDOCUMENTOXML> como nodo principal. Adicionalmente, el archivo debe tener un nodo Encabezado creado de la siguiente manera:

</ENCABEZADO>

Un encabezado válido debe contener dos nodos de información identificados con las etiquetas CICLO y ENTIDAD, como se muestra en el ejemplo anterior.

El nodo CICLO debe contener los datos Fecha, CodServicio y NumSesion y el nodo ENTIDAD debe contener los datos CodEntidad y Consecutivo.

Seguido al encabezado debe existir al menos un nodo para bloque de datos identificado con la etiqueta que se indique en el estándar de cada servicio particular, con un nodo para cada documento que es importado, o enviado a cobro / devolución. (Para efectos del ejemplo se utilizarán las etiquetas REGISTROS y REGISTRO, para el bloque de datos y los documentos).

<REGISTRO.../>

< REGISTRO.../>

...

<RESUMEN.../>

</REGISTROS>

Al final de todos los registros de datos y como último nodo del bloque de datos, debe existir un nodo de Resumen con dos atributos: CantidadDatos y SumatoriaMontos, que sirven para un chequeo general de la cantidad de registros y el monto total sin distinción de moneda.

(10)

Si el archivo no contiene datos suficientes como para ser una estructura válida (Encabezado + Bloque de Datos) se generará un error general de estructura.

5.3. Validación de contenido

5.3.1. Validaciones generales Tipos de datos:

Para todos los registros y atributos que se definen en el área de datos del archivo, se aplicará una validación contra el tipo de datos correspondiente.

De no pasar la validación de datos se generará un error.

Cantidad de caracteres:

También se valida que la cantidad de caracteres esté entre el rango definido, es decir, que aparezcan al menos el mínimo definido y que no se supere el máximo.

Etiquetas de cada registro:

Las etiquetas de cada registro y atributo se validan contra los nombres apropiados. En caso de que alguna tenga un nombre incorrecto se genera el error correspondiente. Es importante mencionar que en el caso de los XML si se hace distinción entre las mayúsculas y minúsculas, es decir un nodo “NOMBRE” es distinto de un nodo “Nombre”.

Campos alfanuméricos:

Los atributos cuyo tipo de datos se definan como un alfanumérico o string no deben contener espacios en blanco al inicio ni al final.

Fechas:

Cada fecha que se encuentre dentro del archivo deberá cumplir con el siguiente formato: “aaaa-MM-dd” donde “aaaa” el año, “MM” es el mes, “dd”

el día, y a su vez cada uno de los componentes debe encontrarse dentro de los rangos permitidos y estar separados por el signo “-“. La longitud en caracteres de la fecha debe ser de 10, es decir para días y meses menores a 10 se deben expresar con un 0 delante (ej: “1” debe expresarse como

“01”).

Fechas con Horas:

Las fechas con horas deben cumplir con el siguiente formato “aaaa-MM-dd HH:mm:ss”. Adicionalmente, a la parte de año, mes, día en el formato

“aaaa-MM-dd” que sigue las validaciones de fechas sin horas que se detallan en el apartado anterior, estas fechas contienen la hora en el formato “HH:mm:ss”, donde “HH” representa la hora (24 horas), “mm”

representa los minutos y “ss” los segundos. La longitud en caracteres de estas fechas debe ser de 19, es decir, las horas, minutos o segundos menores a 10 deben expresarse con un 0 delante (ej: “1” debe expresarse

(11)

Edición: 3 Público Vigencia: 26-12-2006

8 Códigos de Entidad:

Es el código de cualquier entidad asociada o representada en el SINPE.

Deben ser tres campos numéricos entre comillas (ej: “100”), lo cual se valida y que además correspondan a una entidad válida dentro del servicio.

Montos en cualquier moneda:

Todos los montos deben ser como mínimo cuatro campos de tipo alfanumérico y veinte como máximo, estos tamaños incluyen los caracteres especiales utilizados para dar formato a este tipo de dato. El monto siempre debe tener dos campos decimales cuyo separador es el punto “.” y los miles deben ser separados por comas siempre.

Porcentajes:

Todos los porcentajes deben ser como mínimo cuatro campos de tipo alfanumérico y seis como máximo, estos tamaños incluyen los caracteres especiales utilizados para dar formato a este tipo de dato. El porcentaje siempre debe tener dos campos decimales cuyo separador es el punto “.”.

El valor numérico de un porcentaje siempre estará entre cero y cien.

Código de referencia de las operaciones:

Cada operación o documento en un archivo para intercambio electrónico de datos debe contener un código de referencia que la identifique unívocamente en el Sistema de Pagos. Esta referencia está identificada por el atributo “CodReferencia” de cada registro de datos, con una longitud de 25 caracteres numéricos respetando el siguiente formato AAAAMMDDEEESSCCRRRRRRRRRS, donde:

AAAAMMDD Contiene la misma fecha a la que pertenece el archivo y que se indica en el encabezado del mismo.

EEE Código de entidad asociada tal y como se indicó en el encabezado.

SS Servicio al cual pertenece el archivo.

CC Consecutivo del archivo en el cual se envía la operación.

RRRRRRRRR Referencia interna de la entidad, este número debe ser único por operación.

S Dígito verificador o Self. Se valida según se establece en el libro 01-7 denominado " Norma complementaria - Cuenta Cliente (CC) e IBAN".

Cada parte que conforma este código de referencia es validada de manera que tenga los valores permitidos en cada caso.

Adicionalmente, los registros dentro de un bloque de datos deben estar ordenados por este código de referencia.

(12)

Códigos de Cuenta:

Todos los números de cuenta representados por Cuentas Clientes se validan como se establece en la Norma Complementaria Cuenta Cliente (CC) e IBAN.

5.3.2. Encabezado

Como se menciona en el punto anterior, el encabezado debe tener una etiqueta ENCABEZADO y se compone de dos nodos de datos con las etiquetas CICLO y ENTIDAD respectivamente.

5.3.2.1. CICLO Fecha:

Es la fecha del ciclo al cual pertenece el archivo que se está enviando. Se valida según se establece en el apartado 5.3.1 de este documento para la validación de fechas.

CodServicio:

Este campo indica el código de servicio particular al que pertenece el archivo, según el estándar correspondiente.

NumSesion:

Indica la sesión en la que se está enviando el archivo. “1” para Envío, “2”

para Devoluciones. En el caso de los archivos de importación para los servicios SLB el NumSesion es siempre “1”.

5.3.2.2. ENTIDAD CodEntidad:

Es el código de la entidad asociada al SINPE y que realiza el envío del archivo. Se valida que cumpla con las reglas de validación de un código de entidad y que corresponda con la entidad que envía el archivo y que la misma esté autorizada a participar en el servicio.

Consecutivo:

Cada asociado puede particionar sus archivos, en tantos envíos parciales como lo requiera hasta un máximo de 99, por cada sesión (cobro o devoluciones), los cuales puede enviar en forma independiente. Este mecanismo requiere que se especifique cual de los archivos está siendo enviado en un momento dado mediante un consecutivo de sesión, el cual es validado para garantizar que se encuentra dentro del rango aún no enviado. Es importante señalar que no es necesario que los números de consecutivo sigan una estricta secuencia, esto significa que es posible enviar el archivo con consecutivo “3” antes que el correspondiente al consecutivo “2”. Este atributo tiene una longitud mínima de 1 para los consecutivos menores a 10 y máximo de 2 para los valores entre 10 y 99.

(13)

Edición: 3 Público Vigencia: 26-12-2006

10 5.3.3. Bloque de Datos

Cada archivo contiene, al menos, un bloque de datos, con la etiqueta que se indique en el estándar específico. Dentro de este bloque de datos pueden existir tantos registros como sea necesario, y al final de los mismos, un único nodo de resumen.

5.3.3.1. Nodo de Datos

Los atributos de los nodos de datos se especifican detalladamente en el estándar electrónico particular de cada servicio.

5.3.3.2. RESUMEN

El resumen debe constar de dos atributos “CantidadDatos” y

“SumatoriaMontos”, y debe estar inmediatamente después del último registro de datos en el bloque. Si esto no se cumple se genera un error.

CantidadDatos:

De uno a siete campos que indican la cantidad de registros que se envían en el archivo. Se valida que efectivamente la cantidad de registros de datos contenidos en el archivo corresponda con el valor que se indica. Los miles deben separarse con coma, la cual está incluida en la longitud del campo, es decir se tienen 6 campos para números y uno para la coma, con lo que se puede tener hasta un máximo de 999,999 registros en cada bloque de datos.

SumatoriaMontos:

Indican la sumatoria de los montos de todos los registros que se envían en el archivo (sin distingo de moneda). Se valida que cumpla con las reglas de validación de montos y además que efectivamente la sumatoria de los montos de los registros de datos contenidos en el archivo corresponda con el valor que se indica.

6. Validaciones adicionales para archivos SCL

En las secciones anteriores se encuentran varias definiciones correspondientes a validaciones que se deben realizar en las Entidades Financieras que desean participar en un servicio que utilice archivos de intercambio electrónico de datos. Estas validaciones generales corresponden a revisiones de formato y tipo de datos.

Existe otro proceso de validación y se aplica en forma centralizada en el SINPE y es de suma importancia para los servicios SCL. Este proceso se lleva a cabo sobre los archivos de devoluciones y consisten en asegurar la veracidad de la información que contiene el archivo. Para esta etapa de la validación, se toman los registros del archivo de devoluciones y se revisan contra la base de datos a fin de asegurarse que la fecha y los demás datos que se indican correspondan efectivamente a los datos enviados a cobro por la entidad origen de la operación. En caso de existir un error en la información, el archivo del procesamiento y se devuelve a la Entidad Financiera que lo originó, junto con un archivo indicando los errores encontrados. Si un archivo pasa este proceso de validación se incluirá

(14)

dentro del cálculo del multilateral que se realiza previo a la aplicación de los movimientos de las cuentas corrientes de reserva de las Entidades Financieras, en caso contrario no será tomado en cuenta para dicho proceso.

7. Procesamiento de operaciones en Tiempo Real

Para los servicios cuyo procesamiento se realiza en tiempo real mediante el uso de webServices, se utilizará el mecanismo de excepciones para comunicar al origen sobre alguna inconsistencia encontrada en los datos o algún funcionamiento anómalo durante la invocación a uno de los métodos.

Para estos casos, el WebService del servicio lanzará una excepción de tipo SoapException. Esta excepción tiene propiedades que muestran mayor detalle del error ocurrido en el WebService. Entre otras se pueden listar:

 Message: Mensaje de la excepción original.

 Actor: URL del método del webservice invocado.

 Detail: XML personalizado con información adicional de la excepción ocurrida.

La propiedad SoapException.Detail contiene un XML por el siguiente esquema:

(15)

Edición: 3 Público Vigencia: 26-12-2006

12 Dado el esquema anterior, se detallan sus elementos:

 Número = Es el número asociado a la excepción ocurrida en el WebService (el HRESULT). En los estándares electrónicos particulares se listan los códigos de error particulares para cada servicio.

 Descripción = Mensaje anotado por el WebService que indica la presencia de un error. Éste mensaje es más amigable que el SoapException.Message y podría mostrársele al usuario. En la propiedad SoapException.Message se encuentra una descripción de la excepción ocurrida.

 Ubicación = Información acerca del nombre del assembly en el que ocurrió la excepción.

 Fecha = Fecha del evento.

 Argumentos = Éste elemento contiene información adicional de la excepción ocurrida. Este nodo funciona como una colección de 0 o más nodos Argumento. Este nodo posee un atributo ‘Cantidad’ que indica el número de argumentos presentes.

 Argumento = Puede que una excepción no tenga argumentos, por lo que este nodo no aparecería. En caso de existir, contendría información aun más detallada acerca del error.

A continuación se presenta un ejemplo de este XML, simulando una excepción de insuficiencia de fondos: