Guía de configuración del cliente para el envío del reporte FATCA v1.7.0 Proyecto FATCA 2015
Tabla de contenido 1. Introducción... 3 2. Definición del Servicio para Pruebas... 3 2.1 Consideraciones Generales... 3 2.2 Configuración del Servicio... 4 2.2.1. Binding... 4 2.2.2. EndpointBehaviors... 4 2.2.3. Client... 5 2.3 Instalación de la Jerarquía del Certificado... 5 2.4 Instalación de certificados para la autentificación... 13 3. Definición del Servicio para Producción... 28 3.1 Consideraciones Generales... 28 3.2 Configuración del Servicio... 28 2.2.4. Binding... 28 2.2.5. EndpointBehaviors... 29 2.2.6. Client... 29 3.3 Instalación de la Jerarquía del Certificado... 30 3.4 Instalación de certificados para la autentificación... 36 4. Clases... 52 5. Mensajes de validación... 53 6. Versiones... 54 2
1. Introducción El contenido de esta guía tiene como objetivo explicar la forma en la que las Instituciones Financieras pueden realizar tanto la prueba inicial así como el envío oficial del archivo XML a través de los servicio FATCA expuestos por el BCCR. 2. Definición del Servicio para Pruebas 2.1 Consideraciones Generales El objetivo de esta guía es lograr una prueba de envío del reporte FATCA entre el BCCR y la Institución Financiera usuaria del servicio. Se exponen dos opciones para el envío del XML Fatca: o Servicio Web: https://spe.bccr.fi.cr:2446/fatca/fatcaxml.svc o Sitio web: Para iniciar la fase de prueba es un requisito que la Institución Financiara comunique al BCCR las direcciones IP públicas de los equipos que utilizarán para hacer las pruebas. La función del servicio consiste en mostrar al usuario el estado de la comunicación entre el BCCR y la Institución Financiera. La respuesta del servicio se envía en formato XML. Esta configuración aplica para el archivo web.config del cliente que consume el WCF FACTA. 3
2.2 Configuración del Servicio Se debe establecer una referencia al servicio publicado por el BCCR en la ruta https://spe.bccr.fi.cr:2446/fatca/fatcaxml.svc El archivo de configuración (web.config) del cliente debe contener las siguientes secciones para las cuales se sugiere esta recomendación: 2.2.1. Binding <bindings> <wshttpbinding> <binding name="wsfatcahttpsbinding" closetimeout="10:30:00" opentimeout="10:30:00" receivetimeout="10:30:00" sendtimeout="00:30:00" maxbufferpoolsize="2147483646" maxreceivedmessagesize="2147483646"> <readerquotas maxdepth="64" maxstringcontentlength="2147483647" maxarraylength="2147483647" maxbytesperread="2147483647" maxnametablecharcount="2147483647" /> <security mode="transportwithmessagecredential"> <transport clientcredentialtype="certificate" proxycredentialtype="none" realm="" /> <message clientcredentialtype="certificate" negotiateservicecredential="true" algorithmsuite="default" /> </security> </binding> </wshttpbinding> </bindings> 2.2.2. EndpointBehaviors <endpointbehaviors> <behavior name="bccrservidor_behavior"> <clientcredentials> <clientcertificate findvalue="cn=bccr-fc-xxxxxx-100, OU=FATCA, O=BCCR, L=SJ, C=CR" storelocation="localmachine" storename="my" x509findtype="findbysubjectdistinguishedname"/> <servicecertificate> <authentication certificatevalidationmode="peerorchaintrust" revocationmode="nocheck" trustedstorelocation="localmachine" /> </servicecertificate> </clientcredentials> </behavior> </endpointbehaviors> 4
2.2.3. Client <client> <endpoint address="https://spe.bccr.fi.cr:2446/fatca/fatcaxml.svc" behaviorconfiguration="bccrservidor_behavior" binding="wshttpbinding" bindingconfiguration="wsfatcahttpsbinding" contract="bs.fatca.ifatcaxml" name="wshttpbinding_ifatcaxml"> <identity> <dns value="spe.bccr.fi.cr"/> </identity> </endpoint> </client> 2.3 Instalación de la Jerarquía del Certificado Se debe instalar la siguiente jerarquía de certificados para que el cliente pueda crear el canal SSL y establecer la relación de confianza con el servidor. a. Descargar el archivo certnew.p7b del sitio www.bccr.fi.cr b. Clic derecho sobre el archivo y seleccionar Instalar certificado c. Presionar siguiente 5
6
d. Seleccionar Colocar todos los certificados en el siguiente almacén 7
e. Presionar Examinar y seleccionar Entidades de certificación raíz de confianza 8
f. Presionar Siguiente 9
g. Presionar Finalizar 10
h. En la advertencia de seguridad indicar que Sí desea instalar el certificado Equidma 11
i. En la advertencia de seguridad indicar que Sí desea instalar el certificado Dite 12
j. En la advertencia de seguridad indicar que Sí desea instalar el certificado Aqueronte k. Finaliza la instalación correcta de certificados 2.4 Instalación de certificados para la autentificación 13
Pasos para la instalación de certificados con llave privada con usuario administrador. 1. Descargar el archivo con extensión.vbs_ que se enviará vía correo electrónico. 2. Borrar el guion bajo de la extensión.vbs. 14
3. Ejecutar el archivo con extensión.vbs, con doble clic o presionando enter sobre el archivo. IMPORTANTE: La ejecución del archivo con extensión.vbs, debe realizarse desde una maquina con dirección IP, previamente registrada. Se generará un archivo con extensión.req, en la carpeta o ubicación donde se ejecutó el archivo con extensión.vbs. Nota: para efectos de documentación y pruebas, en la estructura del nombre del archivo con extensión.req (PRUEBA.00001.FC.999); esta parte será el IdFATCA de cada una de las instituciones financieras, el cual se genera automáticamente y no debe modificarse. 15
4. Enviar el archivo generado con la extensión.req a la siguiente dirección electrónica ley-fatca@bccr.fi.cr,con el subject para el correo a enviar CertificadoFATCA. 5. Descargar el archivo con extensión.cer_ que se enviará a la institución financiera vía correo electrónico. 6. Borrar el guion bajo de la extensión.cer. 16
7. Instalación del certificado digital en la maquina con IP registrada previamente IMPORTANTE: la instalación del certificado se debe realizar en la maquina o equipo en el que se ejecutó el archivo anterior con la extensión.vbs. 7.1 En el ejecutar de Windows, que aparece presionando las teclas (Windows + r) escribir la siguiente instrucción mmc o en el buscador de Windows escribir la instrucción mmc y abrir el ejecutable mmc.exe. Ejecutar de Windows Buscador de Windows 17
7.2 Dentro del mmc, ir a la pestaña de Archivo y dar clic en la opción de Agregar o quitar complemento. 18
7.3 Aparecerá la ventana de Agregar o quitar complementos, elegir de los complementos disponibles la opción de certificados, dar clic en Agregar. 7.4 A continuación en la ventana de Complemento Certificados elegir la opción de Cuenta de equipo y dar clic en Siguiente. 19
7.5 En la ventana de Seleccionar equipo, dejar seleccionada la opción de Equipo local elegida predeterminadamente y dar clic en Finalizar. 20
7.6 En la ventana de Agregar o quitar complementos dar clic en Aceptar. 7.7 En la vista principal del mmc (Raíz de consola), se generó un registro de certificado. 7.8 Expandir Certificados (equipo local) en Raíz de consola y elegir la opción Personal, dentro de esta dar doble clic en Certificados. 21
7.9 En la opción de Certificados dar clic derecho y elegir la opción Todas las tareas, Importar. 7.10 A continuación se muestra el asistente para importación de certificados, dar clic en Siguiente. 22
7.11 En la ventana Archivo para importar, dar clic en Examinar y buscar la ubicación del certificado o archivo con extensión.cer, descargado previamente, una vez ubicado y seleccionado dar clic en Abrir. Para finalizar dar clic en Siguiente. 23
24
7.12 En la ventana Almacén de certificados dejar la opción Colocar todos los certificados en el siguiente almacén, seleccionada predeterminadamente por el asistente y dar clic en Siguiente. 25
7.13 Finalizar el asistente, dar clic en Finalizar. Mensaje de confirmación exitosa. 26
8. Verificar que el certificado recién generado tenga llave privada. Llave privada. 27
3. Definición del Servicio para Producción 3.1 Consideraciones Generales El objetivo de la sección de esta guía es lograr el envío oficial del reporte FATCA entre el BCCR y la Institución Financiera usuaria del servicio. El servicio expuesto es un Windows Communication Foundation (WCF). NO es necesario indicar las direcciones IP públicas de los equipos que utilizarán para hacer los envíos. La función del servicio consiste en mostrar al usuario el estado de la comunicación entre el BCCR y la Institución Financiera. La respuesta del servicio se envía en formato XML. Esta configuración aplica para el archivo web.config del cliente que consume el WCF FACTA. El servicio está publicado en la ruta: https://servicioleyfatca.go.cr/servicesftc/fatcaxml.svc 3.2 Configuración del Servicio Se debe establecer una referencia al servicio publicado por el BCCR en la ruta https://servicioleyfatca.go.cr/servicesftc/fatcaxml.svc El archivo de configuración (web.config) del cliente debe contener las siguientes secciones para las cuales se sugiere esta recomendación: 2.2.4. Binding 28
<bindings> <wshttpbinding> <binding name="wsfatcahttpsbinding" closetimeout="10:30:00" opentimeout="10:30:00" receivetimeout="10:30:00" sendtimeout="00:30:00" maxbufferpoolsize="2147483646" maxreceivedmessagesize="2147483646"> <readerquotas maxdepth="64" maxstringcontentlength="2147483647" maxarraylength="2147483647" maxbytesperread="2147483647" maxnametablecharcount="2147483647" /> <security mode="transportwithmessagecredential"> <transport clientcredentialtype="certificate" proxycredentialtype="none" realm="" /> <message clientcredentialtype="certificate" negotiateservicecredential="true" algorithmsuite="default" /> </security> </binding> </wshttpbinding> </bindings> 2.2.5. EndpointBehaviors <endpointbehaviors> <behavior name="bccrservidor_behavior"> <clientcredentials> <clientcertificate findvalue="cn=bccr-fc-xxxxxx-100, OU=FATCA, O=BCCR, L=SJ, C=CR" storelocation="localmachine" storename="my" x509findtype="findbysubjectdistinguishedname"/> <servicecertificate> <authentication certificatevalidationmode="peerorchaintrust" revocationmode="nocheck" trustedstorelocation="localmachine" /> </servicecertificate> </clientcredentials> </behavior> </endpointbehaviors> 2.2.6. Client <client> <endpoint address="https://servicioleyfatca.go.cr/servicesftc/fatcaxml.svc" behaviorconfiguration="bccrservidor_behavior" binding="wshttpbinding" bindingconfiguration="wsfatcahttpsbinding" contract="bs.fatca.ifatcaxml" name="wshttpbinding_ifatcaxml"> <identity> <dns value="spe.bccr.fi.cr"/> </identity> </endpoint> </client> 29
3.3 Instalación de la Jerarquía del Certificado Se debe instalar la siguiente jerarquía de certificados para que el cliente pueda crear el canal SSL y establecer la relación de confianza con el servidor. a. Descargar el archivo Cadena_Confianza_CAExternaBCCR.zip del sitio www.bccr.fi.cr/fatca b. Clic derecho sobre el archivo y seleccionar Instalar certificado c. Presionar siguiente 30
Seleccionar Colocar todos los certificados en el siguiente almacén 31
d. Presionar Examinar y seleccionar Entidades de certificación raíz de confianza 32
e. Presionar Siguiente 33
f. Presionar Finalizar 34
g. En la advertencia de seguridad indicar que Sí desea instalar el certificado Autoridad Certificadora Externa BCCR. 35
h. Aplicar los mismos pasos anteriores para el otro certificado CARaizBCCR. i. Finaliza la instalación correcta de certificados 3.4 Instalación de certificados para la autentificación De acuerdo con la guía de servicios de Ley FATCA, sección 3.4 Sección Gestión de certificados de equipo. Una vez en la opción del Sistema Seguridad, servicio Seguridad y opción Certificados. 36
a. Presionar la acción: b. Completar los datos de la solicitud Numero de Nodo: consecutivo para identificar el equipo en el que se instalará el certificado. Descripción: Texto libre para indicar la razón de la solicitud del certificado. c. Presionar el botón finalizar para completar la solicitud 37
d. Seleccionar la solicitud del certificado y presionar la acción: 38
e. Renombrar el archivo *.vbs_ y eliminar el caracter _. Este archivo se debe ejecutar en la máquina para la que se está solicitando el certificado. Al ejecutar el archivo se creará en la misma ubicación un archivo con extensión.req f. Enviar el archivo.reg obtenido: 39
g. Descargar el certificado: 9. Instalación del certificado digital en la maquina con IP registrada previamente IMPORTANTE: la instalación del certificado se debe realizar en la maquina o equipo en el que se ejecutó el archivo anterior con la extensión.vbs. Adicionalmente para estos pasos de instalación de certificados con llave privada es necesario hacerlo bajo un usuario administrador. 40
9.1 En el ejecutar de Windows, que aparece presionando las teclas (Windows + r) escribir la siguiente instrucción mmc o en el buscador de Windows escribir la instrucción mmc y abrir el ejecutable mmc.exe. Ejecutar de Windows Buscador de Windows 41
9.2 Dentro del mmc, ir a la pestaña de Archivo y dar clic en la opción de Agregar o quitar complemento. 9.3 Aparecerá la ventana de Agregar o quitar complementos, elegir de los complementos disponibles la opción de certificados, dar clic en Agregar. 42
9.4 A continuación en la ventana de Complemento Certificados elegir la opción de Cuenta de equipo y dar clic en Siguiente. 43
9.5 En la ventana de Seleccionar equipo, dejar seleccionada la opción de Equipo local elegida predeterminadamente y dar clic en Finalizar. 44
9.6 En la ventana de Agregar o quitar complementos dar clic en Aceptar. 9.7 En la vista principal del mmc (Raíz de consola), se generó un registro de certificado. 9.8 Expandir Certificados (equipo local) en Raíz de consola y elegir la opción Personal, dentro de esta dar doble clic en Certificados. 45
9.9 En la opción de Certificados dar clic derecho y elegir la opción Todas las tareas, Importar. 9.10 A continuación se muestra el asistente para importación de certificados, dar clic en Siguiente. 46
9.11 En la ventana Archivo para importar, dar clic en Examinar y buscar la ubicación del certificado o archivo con extensión.cer, descargado previamente, una vez ubicado y seleccionado dar clic en Abrir. Para finalizar dar clic en Siguiente. 47
48
9.12 En la ventana Almacén de certificados dejar la opción Colocar todos los certificados en el siguiente almacén, seleccionada predeterminadamente por el asistente y dar clic en Siguiente. 49
9.13 Finalizar el asistente, dar clic en Finalizar. Mensaje de confirmación exitosa. 50
10. Verificar que el certificado recién generado tenga llave privada. Llave privada. 51
4. Clases Importante: Para consumir el servicio el usuario debe tener permisos de administrador sobre el equipo en el que ejecuta la aplicación. El Servicio WCF expone la función Enviar 1 la cual permite la transferencia de archivos (reportes FATCA) solicitados por el Ministerio de Hacienda para su posterior envío al IRS. Método Public Function Enviar(ByVal archivo() As Byte, _ ByVal periodo As Integer, _ ByVal anyo As Integer) As String Archivo byte array con el contenido del archivo. Periodo Periodo al que pertenece la información. En este caso archivo XML se envía de forma anual y el valor esperado en este parámetro siempre es 1. Año Año al que pertenece la información. Este dato debe ser consistente con el elemento ReportingPeriod 2. Respuesta Retorna el estado y la descripción del procesamiento del reporte FATCA. <Fatca> <Codigo/> <Detalle/> </Fatca> --Resultado del procesamiento --Resultado de las validaciones 1 Asegurarse de actualizar la referencia al servicio para obtener la última versión publicada. 2 http://www.bccr.fi.cr/fatca/documentos/estandar_electronico_fatca.pdf 52
5. Mensajes de validación La siguiente tabla muestra los mensajes retornamos al usuario por parte del servicio WCF. Código Descripción Datos Adicionales 0 El archivo ha sido recibido exitosamente. No 1 Ocurrió un error interno. No 2 La entidad con Id fatca [{0}] no se encuentra registrada. Sí 3 La entidad [{0}] con el Id Fatca [{1}] no ha firmado el acuerdo de Sí uso. 4 El archivo suministrado se encuentra vacío. No 5 El archivo no corresponde a un archivo xml. No 6 El archivo suministrado no corresponde a un archivo esperado Sí [{0}]. 7 El archivo suministrado no es válido según el esquema. Contiene Sí los siguientes errores: {0}. 8 El Id Fatca suministrado en el archivo no coincide con el Id Fatca No de la entidad. 9 Ya existe una carga para ese mismo archivo. Código de verificación: Sí [{0}]. 10 La fecha del período del archivo no coincide con la suministrada. No 11 La fecha plazo para hacer envíos correspondientes al año [{0}] es Sí [{1}] y su carga se intentó tramitar el [{2}]. Posterior a la fecha de cierre sólo se aceptan archivos de tipo "FATCA2". 12 El archivo con código de verificación [{0}] corresponde a un archivo Sí Fatca 2, y esté sólo será permitido después de la fecha de cierre. 13 El archivo con código de verificación [{0}] corresponde a un archivo Sí FATCA2, pero no se han suministrado datos previos. 14 Error en el procesamiento del consolidado parcial o recarga de un Sí archivo FATCA con errores. Por ejemplo: Error, el elemento <sfa:messagerefid> del archivo base debe coincidir con el elemento <sfa:corrmessagerefid> del archivo actual. 15 El año proporcionado [{0}] no es el esperado. No se puede verificar contra la fecha de cierre. Sí 53
6. Versiones Versión Descripción 1.7.0 Se actualiza la sección 5(Mensajes de validación). 1.6.0 Se agrega la sección de la configuración del servicio para producción. 1.5.2 Se actualiza la sección 3 (Clases) se definen los parámetros que recibe la función Enviar. Se agregan nuevos mensajes de validación (4, 5, 6, 7, 8, 9, 10,11) a la sección 4. 1.4.1 Se actualiza la sección 2.4 (Instalación de certificados para la autentificación) Se agrega una especificación al paso 3. 1.3.4 Se actualiza la sección 2.2 (Configuración del servicio) para la comunicación con el uso de certificados digitales. Se agrega el punto 2.4 (Instalación de certificados para la autentificación). Esta sección describe la configuración del cliente, para la autentificación mediante el uso de un certificado digital. Se actualiza la sección 3 (Clases). Se agrega una nota importante sobre la ejecución de la aplicación. Se actualiza la sección 4 (Mensajes de validación). Se agrega nuevos mensajes de validación. 54
1.2.2 Se elimina el punto 2.2.4 y se reemplaza por la sección 2.3 Instalación de la Jerarquía del Certificado. Con esta actualización se resuelven los problemas de la relación de confianza entre el cliente y el servidor. 1.1.1 Se actualiza la sección 2.2 (Configuración del servicio). Se agrega especificación del elemento <system.net> para el archivo de configuración del cliente para la fase de pruebas con el servicio. 1.0 Guía de configuración para validar la prueba inicial de comunicación entre el BCCR y las Instituciones Financieras que utilizan el servicio FATCA. 55