CrediCoop

La API de CrediCoop  (en adelante el proveedor del servicio) es un servicio de este banco que permite realizar por programación las tareas equivalentes al homebanking como consultar saldo de cuentas, información de cuentas, movimientos de cuenta, autorizar transferencias  y e-cheque y que la interfaz WSAFIPFE.misdatos replica íntegramente

Para empezar a implementar este servicio es imprescindible la introducción a la interfaz e instalador WSAFIPFE tal como figuran en estas 3 guías básicas. Teniendo en cuenta que el instalador WSAFIPFE contiene varias clases (u OCX) una de las cuales es WSAFIFPE.misdatos que en este caso vamos  usar para conectar al proveedor y para hacerlo debe tener en cuenta.

• Como empezar WSAFIFPE

• Como empezar técnicmanete WSAFIPFE

• Como empezar con finanzas embebidas.

Teniendo en cuenta las 2 secciones anteriores para comenzar a implementar la conexión a los servicios de este proveedores debe tener disponibles:

• La interfaz WSAFIPFE  instalada en un equipo con windows.

• La herramienta mdutil.exe copiada en alguna carpeta en el mismo equipo y su codigo de hash.

• La interfaz WSAFIPFE.misdatos referenciada en un proyecto en su compilador o lenguaje. Ya sea como control activeX OCX o COM. o bien con sentencias que no requieran referencia a la interfaz (como CreateObject que es usada en  la planilla excel de test y en visual basic)

• El titular a nombre de quien se hará la conexión (ya sea en modo prueba o real) con su identificador de cliente y numero de adherente proporcionado por el proveedor.

• El archivo  con a firma o clave privada tramitado para ese cliente y proporcionada por el proveedor ya sea una para el modo  prueba y otra para el modo real y que se tramita para un ID de cliente y número de adherente.

• El archivo de licencia provisorio o definitivo  (incluso si se está conectando al servidor de prueba) generado para el ID de cliente del punto anterior y que incluya el servicio "fintech credicoop" como se explica en este tutorial de como generar un archivo de licencia provisorio antes de comprar el servicio.

• Las URL o direcciones (ya sea para el servidor de prueba como para el real) y dentro de esos servicios las URL o direcciones para cada método a implementar (consultar cuenta, autorizar transferencia, etc.).

• La documentación del proveedor ya que contiene los datos de entrada y salida de cada método y su funcionamiento general,  ya que la interfaz WSAFIPFE.misdatos solo replica todos esos métodos con su campos de entrada y salida y por lo tanto es necesaria la documentación original del servicio

Como toda API este proveedor requiere antes de conectar para utilizar alguno de sus métodos previamente conectar para obtener un "token" o "ticket" que es un codigo o clave (que generalmente vence luego de algunos minutos u horas) que luego puede usar para conectar a cualquier de los otros métodos del servicio (por ejemplo consultar cuentas). Por lo que primero debe implementar el código para obtener esta clave y token para guardarla en un archivo y asi poder usarla cuenta sea necesario. Un ejemplo en visual basic  6 de como obtener ese token y guardarlo figura en este párrafo (y también están implementado en la planilla de test) para otros lenguajes puede usar la tabla de equivalencias de sintaxis.

 Dim bresultado As Boolean

  bresultado = True

   Dim cid As String

  Rem es el identificador del cliente proporcionada por el proveedor

  cid = "1234"

  Dim crutaclave As String

  Rem es la firma y clave privada tramitada con el proveedor y para el servidor de prueba o para el real

  crutaclave = "d:\archivo.pem"

    Dim crutalicencia As String

  Rem es el archivo de licencia para el id del cliente y que incluya el servicio fintech CrediCoop.

  Rem tramitar en la plataforma https://sites.google.com/site/facturaelectronicax/inicio/misdatos/misdatos-servicios/misdatoslicenciarapida

  crutalicencia = "d:\1234.lic"

  Dim crutamdutil As String

  Rem es la ruta a la herramienta mdutil necesaria para algunas funciones criptográficas

  Rem descargala desde la plataforma https://sites.google.com/site/facturaelectronicax/inicio/mdutil

  crutamdutil = "d:\mdutil.exe"

    Dim chashmdutil As String

  Rem es el hash del archivo mdutil.exe figura en la misma página donde se lo descarga.

  chashmdutil = "0d39e0ad2ddbecd6fa6ded0f647cf81272218ed61c04f818ae1aac8617c8b28d"

  Dim curltoken As String

  Rem es la url o dirección del servidor para pedir el token o ticket, es proporcinado por el proveedor.

  curltoken = "https://homoapibccl.bancocredicoop.coop/auth/realms/homologacion/protocol/openid-connect/token"

    Dim curlalcance As String

  Rem es el dominio o alcance para el que se pide el token, es proporcinao por el proveedor

  curlalcance = "https://homoapibccl.bancocredicoop.coop/auth/realms/homologacion"

  Dim crutaticket As String

  Rem es donde se va a guardar el token obtenido para luego ser usado

  crutaticket = "d:\ticket.txt"

    Dim carchivoxmlenviado As String

  Dim carchivoxmlrecibido As String

  Rem son las rutas donde se guardan arvhiso con todo el tráfico de datos enviados y recibidos del servidor.

  carchivoxmlenviado = "d:\credicoopet.txt"

  carchivoxmlrecibido = "d:\credicooprt.txt"

  Set mio = CreateObject("WSAFIPFE.misdatos")

 If mio.iniciar(cid, crutaclave) Then

    mio.tls = -1

    mio.archivolicencia = crutalicencia

    mio.ArchivoXMLEnviado = carchivoxmlenviado

    mio.ArchivoXMLRecibido = carchivoxmlrecibido

    bresultado = mio.apiCargarPropiedad("LIMPIAR", "", 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.CONFIGURACION.mdutil", crutamdutil, 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.CONFIGURACION.mdutilhash", chashmdutil, 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.CONFIGURACION.segundos", "900", 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.CONFIGURACION.url", curlalcance, 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.URLMETODO", curltoken, 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.TIPOMETODO", "POST", 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.DATOS.grant_type", "client_credentials", 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.DATOS.scope", "transferencias cuentas echeq", 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.DATOS.client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.DATOS.client_assertion", "auto", 0, 0)

    If bresultado Then

        If mio.apiEjecutar("CREDICOOP.OBTENERTICKET") Then

            Dim ccadena As String

            Dim ctoken As String

            Dim numeroArchivo As Integer

            numeroArchivo = 1

            ccadena = mio.apiLeerPropiedad("CREDICOOP", "obtenerticket", "", 0, 0)

            If mio.UltimoMensajeError = "" Then

                 Open crutaticket For Output As #numeroArchivo

                 Print #numeroArchivo, ccadena

                 Close #numeroArchivo

                 MsgBox "token guardado: " + mio.apiLeerPropiedad("CREDICOOP", "obtenerticket.access_token", "", 0, 0)

            Else

                 MessageBox.Show ("error resultado " + mio.UltimoMensajeError)

            End If

        Else

            MsgBox ("eror obtener ticket " + mio.UltimoMensajeError)

        End If

    Else

        MsgBox ("error cargar propiedad " + mio.UltimoMensajeError)

    End If

Else

    MsgBox ("error iniciar " + mio.UltimoMensajeError)

End If

Si ya obtuvo token de acuerdo a los párrafos anterior pude consumir cualquier método del servicio teniendo en cuenta las 3 acciones básicas con las que la interfaz replica cualquier servicio:

• Cargar el valor de una propiedad.

• Ejecutar un método con o sin argumentos:

• Leer el valor de una propieddad.

Y sobre el segundo punto hay 3 métodos básicos:

• apiCargarPropiedad: que permite cargar los datos a usar tal como la documentación del proveedor lo pide.

• apiEjecutar: ejecutar el método y los datos cargados.

• apiLeerPropiedad: leer el resultado del método.

Aquí se muestra un ejemplo básico de como consultar la lista de cuentas del titular. En visual basic 6 ( para otros lenguajes puede usar la tabla de equivalencias de sintaxis).

Dim bresultado As Boolean

  bresultado = True

  Dim cid As String

  Rem es el identificador del cliente proporcionado por el proveedor

  cid = "1234"

     Dim crutalicencia As String

  Rem es el archivo de licencia para el id del cliente y que incluya el servicio fintech CrediCoop.

  Rem tramitar en la plataforma https://sites.google.com/site/facturaelectronicax/inicio/misdatos/misdatos-servicios/misdatoslicenciarapida

  crutalicencia = "d:\archivo.lic"

   Dim curl As String

  Rem es la url o dirección del servidor con el método a ejecutar proporcionado por el banco

  curl = "https://homoapibccl.bancocredicoop.coop/api/cuentas/v1/listaCuentas"

  Dim crutaticket As String

  Rem es donde se va a guardó el token obtenido en paso anterior.

  crutaticket = "d:\ticket.txt"

  Dim carchivoxmlenviado As String

  Dim carchivoxmlrecibido As String

  Rem son las rutas donde se guardan arvhiso con todo el tráfico de datos enviados y recibidos del servidor.

  carchivoxmlenviado = "d:\credicoopet.txt"

  carchivoxmlrecibido = "d:\credicooprt.txt"

 dim ccadena as string

  Dim ctoken As String

  Dim numeroArchivo

  numeroArchivo = 1

REM resaturamos ticket obtenido en ejemplos anterior

  Open crutaticket For Input As #numeroArchivo

  ccadena = Input(LOF(numeroArchivo), #numeroArchivo)

  Close #numeroArchivo 

  Set mio = CreateObject("WSAFIPFE.misdatos")

 If mio.iniciar(cid, crutaclave) Then

    mio.tls = -1

    mio.archivolicencia = crutalicencia

    bresultado = mio.apiCargarPropiedad("LIMPIAR", "", 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.ticket", ccadena, 0, 0)

    ctoken = mio.apiLeerPropiedad("CREDICOOP", "obtenerticket.access_token", "", 0, 0)

    If mio.ultimomensajeerror = "" Then

       Rem   MsgBox ("token " + ctoken)

    Else

        MsgBox ((mio.ultimomensajeerror)

       bresultado = False

    End If

    mio.ArchivoXMLEnviado = carchivoxmlenviado

    mio.ArchivoXMLRecibido = carchivoxmlrecibido

   bresultado = mio.apiCargarPropiedad("LIMPIAR", "", 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.URLMETODO", curl, 0, 0)

    bresultado = bresultado And mio.apiCargarPropiedad("CREDICOOP.TIPOMETODO", "GET", 0, 0)

    If bresultado Then

        If mio.apiEjecutar("CREDICOOP") Then

            Dim ncuentas As Integer

            Dim cnro As String

            Dim ccbu As String

            Dim csaldo As String

            ncuentas = Val(mio.apiLeerPropiedad("CREDICOOP", "diccionario.clarifCuentas.lista.itemcantidad", "", 0, 0))

            If ncuentas = 0 Then

               MsgBox ("sin cuentas : " + mio.ultimomensajeerror)

               bresultado = False

            Else

               Dim ncontador As Integer

               For ncontador = 1 To 1

                   cnro = mio.apiLeerPropiedad("CREDICOOP", "diccionario.clarifCuentas.lista.nroCuenta", "", ncontador - 1, 0)

                   If mio.ultimomensajeerror = "" Then

                        ccbu = mio.apiLeerPropiedad("CREDICOOP", "diccionario.clarifCuentas.lista.CBU", "", ncontador - 1, 0)

                        csaldo = mio.apiLeerPropiedad("CREDICOOP", "diccionario.clarifCuentas.lista.saldo", "", ncontador - 1, 0)

                        MsgBox "cuenta " + Str(ncontador) + ": " + cnro + Chr(10) + Chr(13) + "cbu " + ": " + ccbu + Chr(10) + Chr(13) + "saldo " + ": " + csaldo

                   Else

                        MsgBox "error cuenta " + mio.ultimomensajeerror

                        bresultado = False

                   End If

               Next

             End If

        Else

            MsgBox ("eror obtener ticket " + mio.ultimomensajeerror)

        End If

    Else

        MsgBox ("error cargar propiedad " + mio.ultimomensajeerror)

    End If

Else

    MsgBox ("error iniciar " + mio.ultimomensajeerror)

End If

La planilla de test CrediCoopMisDatos (al pie de página, debe descargarla para abrir  la planilla localmente en excel) contiene hojas y macro que replica todos y cada uno de la api del servidor por lo que es imprescindible para ver como cada métodos, con sus campos de entrada y salida, es implementada desde la interfaz WSAFIPFE.midatos. La planilla puede ser ejecutada en un excel de 32 bits con las macros habilitadas (puede usar un motor de IA para que lo guie en lo pasos necesarios para habilitar las macro en su versión de excel) y en caso que no pudiera ejecutarlas aun puede usar el código de la macros para ver como todos los métodos son implementados en visual basic.

En toda conexión a una API o servidor externo el reproceso es un punto fundamental a tener en cuenta es especial si está intentando autorizar una operación (por ejemplo una transferencia o cualquier p roceso que solo debe ejecutarse una vez).

Para el caso de la API CrediCoop tener en cuenta estas consideraciones:

Si se está ejeuctando un método autorizador (por ejemplo enviar una transferencia) ANTES de ejecutar el método (apiEjecutar) esta debe ser grabada localmente con su identificador único (en este caso el campo "idOrigen")

luego de ejecutar el método el código debe estar preparado para los siguientes resultados posibles:

• el código se ejecutó sin errores y el servidor ejecutó la autorización devolviendo el idOperacion.

• el código se ejecutó con errores y este error es una descripción  o motivo que indica claramente que la operación no se completó (por ejemplo "saldo insuficiente")

• el código se ejecutó con un error que no permite determinar si la operación fue o no autorizada (por ejemplo "timeout" o "error 500" .

En este último caso es fundamental que el código tenga un proceso bien definido para determinar si el método devolvió un error ANTES de recibir la respuesta pero DESPÚES que el servidor la procesara. En esté ulitmo escenario antes de repetir el método se debe consultar en que estado quedó la primera llamada y asi no correr el riesto de autoirzar 2 veces la misma operación.