“Cupones” Visanet

Visanet Uruguay pone a disposición de comercios e integradores (de aquí en mas llamados terceros) una nueva modalidad para compartir información adicional a la que es enviada en los documentos de liquidación y facturación. A diferencia de soluciones anteriores basadas en archivos, la información se disponibiliza por medio de API REST y herramientas de análisis de datos que permiten integración con los sistemas del tercero.

En vez de definir una API propietaria, Visanet decidió adoptar la API de Elasticsearch, una solución de código abierto con gran adopción en el mercado.

Permisos

Para poder acceder a la información el tercero deberá autenticarse en https://acceso.vnet.uy usando una cuenta existente o creando una nueva según en la documentación de acceso.uy. Luego de autenticado, el tercero se debe contactar con Visanet indicando las credenciales y solicitando permisos para el o los números de comercio de los cuales quiere obtener información; Visanet validará la solicitud y si corresponde asignará los permisos sobre indices cupones*.

El rol asignado en Elasticsearch tiene implementado Document Level Security de forma cada tercero tendrá acceso a los documentos en los cuales el campo comercio.codigo_comercio esté dentro de los comercios autorizados.

Consola para desarrolladores

Dentro de acceso.vnet.uy hay un link hacia un entorno Kibana que permite visualizar y hacer análisis con la información disponible.

En Kibana de Visanet también se tiene acceso a la consola para desarrolladores; herramienta importante durante la etapa de integración y la forma de obtener credenciales para acceder al endpoint publico (https://acceso-api.vnet.uy).

Por ejemplo, ejecutando GET _security/_authenticate (ver documentación) se obtiene información de las credenciales del usuario.

En particular el contenido del array saml_groups indica a que comercios se tiene acceso.

    "saml_groups" : [
      "02000043"
    ],

API REST

Para poder usar la API desde un sistema externo se debe solicitar una api_key a Visanet y recibirá al e-mail registrado en https://acceso.vnet.uy la siguiente información:

{
  "id" : "iiiiiiiiiiiiiiiiiiii",
  "name" : "email@dominio_YYYMMDD-HHMMSS",
  "api_key" : "kkkkkkkkkkkkkkkkkkkkkk"
}

Nota: la api_key es valida únicamente para los comercios a los que ya tiene permiso, si se agregan/quitan comercios es necesario generar otra clave.

De acuerdo a la documentación el valor de api_key retornado puede usarse luego enviando un request con un Authorization header con un valor que tiene el prefijo ApiKey seguido de credentials, donde credentials es la codificación base64 de id y api_key unidas por dos puntos (:).

credentials=$(echo -n 'idididididididididid:kkkkkkkkkkkkkkkkkkkkkk' | openssl base64)

Luego se puede invocar la API por ejempo con curl; en este caso invocando al metodo count de la API de Elasticsearch

curl -s -H "Authorization: ApiKey $credentials" https://acceso-api.vnet.uy/cupones\*/_count | jq

Con el siguiente resultado:

{
  "count": 7550,
  "_shards": {
    "total": 25,
    "successful": 25,
    "skipped": 0,
    "failed": 0
  }
}

Formato cupones

La información transaccional de cupones se almacena en documentos en indices mensuales llamados cupones-YYYY-MM y los terceros pueden consultarlos de la forma que mejor entiendan usando la API de Elasticsearch.

La siguiente consulta devuelve únicamente un cupon:

curl -s -H "Authorization: ApiKey $credentials" https://acceso-api.vnet.uy/cupones\*/_search\?size\=1| jq
{
  "took": 33,
  "timed_out": false,
  "_shards": {
    "total": 25,
    "successful": 25,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 7550,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "cupones-2019-01",
        "_type": "doc",
        "_id": "_________",
        "_score": 1,
        "_source": {
          "@timestamp": "2019-01-09T03:00:00.000Z",
          "indice": "cupones",
          "transaccion": {
            "importe_devolucion_impuesto": 5.48,
            "autorizacion": "6____2",
            "ticket": 545,
            "lote": 72,
            "propina": 0,
            "producto": "VISA DEBITO",
            "terminal": "________",
            "origen": "Local",
            "importe": 167,
            "tipo_transaccion": "Compra",
            "numero_factura": 5____1,
            "devolucion_impuesto": 6,
            "fecha_proceso": "2019-01-09T03:00:00.000Z",
            "fecha_cupon": "2019-01-09T03:00:00.000Z",
            "moneda": 858,
            "sello": "visa",
            "canal": "POS ONLINE",
            "cuotas": 1,
            "modo": "modo_51"
          },
          "comercio": {
            "tipo_documento": "RUT Uruguay",
            "numero_de_documento": 21__________,
            "razon_social": "RAZON SOCIAL",
            "codigo_comercio": "________",
            "nombre_fantasia": "NOMBRE COMERCIO"
          },
          "@version": "1",
          "datos_especiales": {
            "iva_intereses_financiacion": 0,
            "cupon": __________,
            "intereses_financiacion": 0,
            "nro_pedido": "",
            "cashback": 0
          },
          "liquidacion": {
            "retencion_leyes_equivalente_$": 0,
            "arancel": 2.51,
            "porcentaje_beneficio_leyes": 0,
            "banco_acreditacion": "",
            "retencion_leyes": 0,
            "forma_pago": "D/E Std. Loc, 1 d háb, 1,50 %",
            "propina_excedente": 0,
            "fecha_pago": "2019-01-10T03:00:00.000Z",
            "iva_arancel": 0.55,
            "fecha_liquidacion": "2019-01-09T03:00:00.000Z",
            "adquirente": "visanet",
            "id": "E0109-P-1-00-00004606004-00",
            "plan_venta": "DEBITO / ELECTRON"
          }
        }
      }
    ]
  }
}

Campos