API

Última actualización: 27/09/2021

Introducción

Con la API de FidelCity puedes integrar toda la funcionalidad que ofrece el programa en tu página web o aplicación móvil. A continuación se detallan las funcionalidades disponibles para que tu desarrollador pueda integrarlo.

Te ayudamos

Si dispones de una página web y necesitas ayuda para realizar la integración, ponte en contacto con nosotros.

Autentificación

La API está securizada mediante un token, por lo que todas las peticiones deben contener la cabecera X-API-KEY con tu token de FidelCity. Este token debes solicitarlo al soporte técnico a través del email soporte@fidelcity.es.

Comercio

Obtener datos del comercio
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo GET
Formato application/json
Url https://fidelcity.es/api_comercio/comercio
Cuerpo
Respuesta 

{
    "estado": "correcto",
    "codigo_mensaje": "obtener_comercio_correcto",
    "mensaje": "Datos comercio obtenidos correctamente",
    "comercio": {
        "Id": "1",
        "Id_Usuario": "1",
        "Id_Grupo_Asociaciones": "1",
        "Nombre": "Comercio Demo",
        "Nombre_Abreviado": "Demo",
        "Descripcion": null,
        "Persona_Contacto1": "Fernando",
        "Persona_Contacto2": null,
        "Email": "info@comerciodemo.com",
        "Web": "www.comerciodemo.com",
        "Telefono": "966300000",
        "Movil": "666666666",
        "Fax": null,
        "Direccion": "C/ Las Palomas, 35, 2º Derecha",
        "Codigo_Postal": "03690",
        "Ciudad": "San Vicente del Raspeig",
        "Provincia": "Alicante",
        "Pais": "34",
        "Latitud": "38.396420",
        "Longitud": "-0.524871",
        "Fecha_Alta": "2017-10-09 10:03:47",
        "Fecha_Ultima_Actualizacion": "2017-11-21 18:05:22",
        "Habilitado": "1",
        "Url_Logo": "assets/img/comercios/1/logo/logo.jpg"
    }
}
Observaciones
  • Los campos Id_Usuario e Id_Grupo_Asociaciones no los necesitarás para nada.
  • Url_Logo: Para utilizar la imagen, deberán poner delante la URL base: https://fidelcity.es/ y concatenarlo con la respuesta.

Porcentajes de puntos (deprecated)

Obtener lista de porcentajes de puntos del comercio
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo GET
Formato application/json
Url https://fidelcity.es/api_comercio/porcentajes_puntos
Cuerpo
Respuesta 

{
    "estado":"correcto",
    "codigo_mensaje":"obtener_porcentajes_puntos_correcto",
    "mensaje":"Porcentajes de puntos obtenidos correctamente",
    "porcentajes_puntos": [
        {
            "Id": "31",
            "Nombre": "Habitual",
            "Descripcion": "",
            "Porcentaje": "2.00",
            "Visible_Empleados": "1",
            "Por_Defecto": "1"
        },
        {
            "Id": "32",
            "Nombre": "Vip",
            "Descripcion": "",
            "Porcentaje": "10.00",
            "Visible_Empleados": "1",
            "Por_Defecto": "0"
        }
    ]
}
Observaciones
  • Los porcentajes de puntos deben estar definidos en cada comercio.
  • Ignorar el campo Visible_Empleados

Perfiles de fidelización

Obtener lista de perfiles de fidelización del comercio
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo GET
Formato application/json
Url https://fidelcity.es/api_comercio/perfil_fidelizacion
Cuerpo
Respuesta 

{
    "estado":"correcto",
    "codigo_mensaje":"obtener_datos_configuracion_perfiles",
    "mensaje":"Configuración perfil fidelización obtenido correctamente",
    "datos_perfil_fidelizacion": {
        "Modo_Generacion": "porcentajes_clientes",
        "Generacion_Valores": [
            {
                "Id": "8",
                "Nombre": "Habitual",
                "Descripcion": "",
                "Porcentaje": "2.00",
                "Visible_Empleados": "1",
                "Por_Defecto": "1"
            },
            {
                "Id": "9",
                "Nombre": "Vip",
                "Descripcion": "",
                "Porcentaje": "10.00",
                "Visible_Empleados": "1",
                "Por_Defecto": "0"
            },
            {
                "Id": "17",
                "Nombre": "Empleados",
                "Descripcion": "",
                "Porcentaje": "20.00",
                "Visible_Empleados": "1",
                "Por_Defecto": "0"
            }
        ],
        "Modo_Consumo": "descuento_monetario",
        "Consumo_Valores": null
    }
}
Observaciones
  • El Modo_Generación puede ser "porcentajes_clientes", "puntos_directos" o "porcentajes_familias". Dependiendo del modo de funcionamiento, el campo "Generacion_Valores" devolverá unos valores u otros.
  • El campo Modo_Consumo puede ser "descuento_monetario" o "premios". En caso de que se use el modo "premios", el campo "Consumo_Valores" devolverá una lista con los premios disponibles.

Clientes

Obtener cliente por Id
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo GET
Formato application/json
Url https://fidelcity.es/api_comercio/cliente/id/<id>
Cuerpo
Respuesta 

{
    "estado": "correcto",
    "codigo_mensaje": "obtener_cliente_correcto",
    "mensaje": "Datos cliente obtenidos correctamente",
    "cliente": {
        "Id": "268",
        "Id_Asociacion": "1",
        "Tipo_Documento": "dni",
        "Identificador_Documento": "45678763G",
        "Nombre": "Luis López",
        "Apellidos": "García",
        "Fecha_Nacimiento": "1976-04-03",
        "Sexo": "Hombre",
        "Email": "pruebacorreo@gmail.com",
        "Telefono": "96630774",
        "Movil": "634568342",
        "Direccion": "C/ La Huerta, 35, 2º Derecha",
        "Codigo_Postal": "03895",
        "Poblacion": "Benimantell",
        "Id_Provincia": "3",
        "Id_Pais": "34",
        "Latitud": "0.000000",
        "Longitud": "0.000000",
        "Numero_Contrato": "000002",
        "Fecha_Alta": "2017-11-10 13:41:00",
        "Id_Comercio_Alta": "1",
        "Fecha_Ultima_Actualizacion": "2017-12-05 16:01:21",
        "Id_Cliente": "22",
        "Modo": "Codigo_Barras",
        "Credencial": "0007777777777111",
        "Habilitado": "1"
    }
}
Observaciones
Obtener cliente por Credencial
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo GET
Formato application/json
Url https://fidelcity.es/api_comercio/cliente/credencial/<credencial>
Cuerpo
Respuesta 

{
    "estado": "correcto",
    "codigo_mensaje": "obtener_cliente_correcto",
    "mensaje": "Datos cliente obtenidos correctamente",
    "cliente": {
        "Id": "268",
        "Id_Asociacion": "1",
        "Tipo_Documento": "dni",
        "Identificador_Documento": "45678763G",
        "Nombre": "Luis López",
        "Apellidos": "García",
        "Fecha_Nacimiento": "1976-04-03",
        "Sexo": "Hombre",
        "Email": "pruebacorreo@gmail.com",
        "Telefono": "96630774",
        "Movil": "634568342",
        "Direccion": "C/ La Huerta, 35, 2º Derecha",
        "Codigo_Postal": "03895",
        "Poblacion": "Benimantell",
        "Id_Provincia": "3",
        "Id_Pais": "34",
        "Latitud": "0.000000",
        "Longitud": "0.000000",
        "Numero_Contrato": "000002",
        "Fecha_Alta": "2017-11-10 13:41:00",
        "Id_Comercio_Alta": "1",
        "Fecha_Ultima_Actualizacion": "2017-12-05 16:01:21",
        "Id_Cliente": "22",
        "Modo": "Codigo_Barras",
        "Credencial": "0007777777777111",
        "Habilitado": "1"
    }
}
Observaciones
Crear cliente
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo POST
Formato application/json
Url https://fidelcity.es/api_comercio/crear_cliente
Cuerpo 

{
    "tipo_documento":"dni",
    "identificador_documento":"48531667B",
    "nombre":"Rubén",
    "apellidos":"González",
    "sexo":"Hombre",
    "fecha_nacimiento”:”1987/02/12",
    "id_pais":"34",
    "id_provincia":"3",
    "codigo_provincia":"A",
    "poblacion ":"San Vicente del Raspeig",
    "direccion":"C/ Labradores, 6",
    "codigo_postal":"03690",
    "telefono":"966300000",
    "movil ":"666666666"
    "email":"info@fidelcity.es",
    "tipo_credencial":"Codigo_Barras"
    "credencial":"0000000000112",
    "numero_contrato":"0001"
}
Respuesta 

{
    "estado":"correcto",
    "codigo_mensaje":"crear_cliente_correcto",
    "mensaje":"Cliente creado correctamente",
    "cliente": {
        "Id":"12978",
        "Id_Asociacion":"1",
        "Tipo_Documento":"dni",
        "Identificador_Documento":"48531667B",
        "Nombre":"Rubén",
        "Apellidos":"González",
        "Fecha_Nacimiento":"1987-02-12",
        "Sexo":"Hombre",
        "Email":"info@fidelcity.es",
        "Telefono":"966300000",
        "Movil ":"666666666"
        "Direccion":"C/ Labradores, 6",
        "Codigo_Postal":"03690",
        "Poblacion ":"San Vicente del Raspeig",
        "Id_Provincia":"3",
        "Codigo_Provincia":"A",
        "Id_Pais":"34",
        "Latitud":"null",
        "Longitud":"null",
        "Numero_Contrato":"0001",
        "Fecha_Alta":"2018-01-04 17:42:24",
        "Id_Comercio_Alta":"1",
        "Fecha_Ultima_Actualizacion":"null",
        "Verificado":"1",
        "Fecha_Verificado":"2018-01-04 17:42:24",
        "Nombre_Provincia":"Alicante",
        "Nombre_Pais":"España",
    }
}
Observaciones
  • El campo tipo_documento puede ser "dni", "nie", "pasaporte", "dpi", "auto". La opción "auto" generará un código de aleatorio de 13 caracteres.
  • El campo identificador_documento no es necesario en caso de que el "tipo_documento" sea "auto".
  • El campo sexo puede ser "Hombre", "Mujer", o "No_Definido".
  • El campo fecha_nacimiento es obligatorio. Si no se sabe, especificar "1900/01/01".
  • La provincia puede ser enviada con el campo id_provincia o con el campo codigo_provincia. Se debe elegir uno de los dos, pero no enviar ambos.
  • El campo tipo_credencial puede ser "Tarjeta_Inteligente_Contacto", "Tarjeta_Inteligente_Proximidad", "Codigo_Barras", "Manual", o "auto". Si se especifica "auto", se insertará como "Codigo_Barras" y se generará una credencial automáticamente de forma aleatoria.
  • Si se establece el campo tipo_credencial en "auto", no es necesario rellenar el campo credencial.
  • El campo numero_contrato es opcional. Si no se indica, se rellenará con un código autogenerado de 13 caracteres.

Gestión de puntos

Obtener datos para generar puntos a un cliente
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo GET
Formato application/json
Url https://fidelcity.es/api_comercio/gestion_puntos_generar/id_cliente/<id>
Cuerpo
Respuesta 

{
    "estado":"correcto",
    "codigo_mensaje":"obtener_datos_generacion_puntos_correcto",
    "mensaje":"Datos generación de puntos obtenidos correctamente",
    "datos_generacion_puntos": {
        "Id": "22",
        "Nombre": "Luis López",
        "Apellidos": "García",
        "Puntos": "6.22"
    }
}
Observaciones
Obtener datos para consumir puntos a un cliente
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo GET
Formato application/json
Url https://fidelcity.es/api_comercio/gestion_puntos_consumir/id_cliente/<id>
Cuerpo
Respuesta 

{
    "estado":"correcto",
    "codigo_mensaje":"obtener_datos_consumo_puntos_correcto",
    "mensaje":"Datos consumo de puntos obtenidos correctamente",
    "datos_consumo_puntos": {
        "Id":"22",
        "Nombre":"Luis López",
        "Apellidos":"García",
        "Puntos":"6.22"
    }
}
Observaciones
Generar puntos a un cliente
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo POST
Formato application/json
Url https://fidelcity.es/api_comercio/gestion_puntos_generar
Cuerpo 

{
    "id_cliente":"1",
    "importe_compra":"50.00",
    "concepto": "ticket 001"
}
Respuesta 

{"mensaje":"puntos_generados_correctamente"}
Observaciones
  • Por el momento, no validamos el formato decimal de los números. Se deberá hacer la validación en la parte cliente y enviarlo tal y como se muestra en el ejemplo, con el "." como signo decimal.
  • El campo concepto es opcional.
Consumir puntos a un cliente
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo POST
Formato application/json
Url https://fidelcity.es/api_comercio/gestion_puntos_consumir
Cuerpo 

{
    "id_cliente":"1",
    "puntos_consumidos":"10.00",
    "concepto":"ticket 002"
}
Respuesta 

{"mensaje":"puntos_consumidos_correctamente"}
Observaciones
  • Por el momento, no validamos el formato decimal de los números. Se deberá hacer la validación en la parte cliente y enviarlo tal y como se muestra en el ejemplo, con el "." como signo decimal.
  • El campo concepto es opcional.

Tarjetas regalo comercio

Crear tarjeta regalo comercio
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo POST
Formato application/json
Url https://fidelcity.es/api_comercio/anadir_tarjeta_regalo_comercio
Cuerpo 

{
    "credencial":"auto",
    "importe":"50.00",
    "descripcion":"Tarjeta regalo pruebas",
    "habilitada":"1",
    "fecha_caducidad":"2021-03-30"
}
Respuesta 

{
    "estado":"correcto",
    "codigo_mensaje":"anadir_tarjeta_regalo_correcto",
    "mensaje":"Tarjeta regalo creada correctamente",
    "tarjeta_regalo": {
        "Id":"5787",
        "Importe":"50.00",
        "Credencial":"2021977860079",
        "Habilitada":"1",
        "Descripcion":"Tarjeta regalo pruebas",
        "Fecha_Creacion":"2021-03-08 17:03:39",
        "Fecha_Fin":"2021-03-30",
        "Fecha_Ultima_Actualizacion":null
    }
}
Observaciones
  • El campo credencial puede ser un código manual o "auto". La opción "auto" generará un código aleatorio de 13 caracteres.
  • El campo descripción es opcional. Se aconseja poner alguna referencia al sistema externo desde el que se está llamando. Por ejemplo, si es una tienda online, poner el número de pedido.
  • El campo habilitada es opcional. En caso de no enviarlo en la petición, por defecto estará "habilitada=1"
  • El campo fecha_caducidad es opcional.
Obtener tarjeta regalo comercio
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo GET
Formato application/json
Url https://fidelcity.es/api_comercio/tarjeta_regalo/credencial/<credencial>
Cuerpo
Respuesta 

{
    "estado": "correcto",
    "codigo_mensaje": "obtener_tarjeta_regalo_comercio_correcto",
    "mensaje": "Datos tarjeta regalo comercio obtenidos correctamente",
    "tarjeta_regalo": {
        "Id": "5787",
        "Importe": "50.00",
        "Credencial": "2021977860079",
        "Habilitada": "1",
        "Descripcion": "Tarjeta regalo pruebas",
        "Fecha_Creacion":"2021-03-08 17:03:39",
        "Fecha_Fin":"2021-03-30",
        "Fecha_Ultima_Actualizacion":null
    }
}
Observaciones Se comprobará en la petición distintas opciones que pueden devolver error, como puede ser:
  • Tarjeta regalo no encontrada.
  • Tarjeta regalo deshabilitada.
  • Tarjeta regalo caducada.
  • Tarjeta regalo sin saldo.
Consumir tarjeta regalo comercio
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo POST
Formato application/json
Url https://fidelcity.es/api_comercio/consumir_tarjeta_regalo_comercio
Cuerpo 

{
    "id":"5787",
    "saldo_consumido":"5.00",
    "concepto":"ticket 001"
}
Respuesta 

{
    "estado":"correcto",
    "codigo_mensaje":"tarjeta_regalo_comercio_consumida_correctamente",
    "mensaje":"Tarjeta regalo comercio consumida correctamente",
    "cliente": {
        "Id":"5787",
        "Importe":"45.00",
        "Credencial":"2021977860079",
        "Habilitada":"1",
        "Descripcion": "Tarjeta regalo pruebas",
        "Fecha_Creacion":"2021-03-08 17:03:39",
        "Fecha_Fin":"2021-03-30",
        "Fecha_Ultima_Actualizacion": "2021-03-10 11:25:30"
    }
}
Observaciones
  • El campo concepto es opcional.

Tarjetas regalo asociación

Crear tarjeta regalo asociación
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo POST
Formato application/json
Url https://fidelcity.es/api_comercio/anadir_tarjeta_regalo_asociacion
Cuerpo 

{
    "credencial":"auto",
    "importe":"50.00",
    "descripcion":"Tarjeta regalo pruebas",
    "habilitada":"1",
    "fecha_caducidad":"2021-03-30"
}
Respuesta 

{
    "estado":"correcto",
    "codigo_mensaje":"anadir_tarjeta_regalo_correcto",
    "mensaje":"Tarjeta regalo asociación creada correctamente",
    "tarjeta_regalo": {
        "Id":"5787",
        "Importe":"50.00",
        "Credencial":"2021977860079",
        "Habilitada":"1",
        "Descripcion":"Tarjeta regalo pruebas",
        "Fecha_Creacion":"2021-03-08 17:03:39",
        "Fecha_Fin":"2021-03-30",
        "Fecha_Ultima_Actualizacion":null
    }
}
Observaciones
  • El campo credencial puede ser un código manual o "auto". La opción "auto" generará un código aleatorio de 13 caracteres.
  • El campo descripción es opcional. Se aconseja poner alguna referencia al sistema externo desde el que se está llamando. Por ejemplo, si es una tienda online, poner el número de pedido.
  • El campo habilitada es opcional. En caso de no enviarlo en la petición, por defecto estará "habilitada=1"
  • El campo fecha_caducidad es opcional.
Obtener tarjeta regalo asociación
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo GET
Formato application/json
Url https://fidelcity.es/api_comercio/tarjeta_regalo_asociacion/credencial/<credencial>
Cuerpo
Respuesta 

{
    "estado": "correcto",
    "codigo_mensaje": "obtener_tarjeta_regalo_comercio_correcto",
    "mensaje": "Datos tarjeta regalo asociacion obtenidos correctamente",
    "tarjeta_regalo": {
        "Id": "5787",
        "Importe": "50.00",
        "Credencial": "2021977860079",
        "Habilitada": "1",
        "Descripcion": "Tarjeta regalo pruebas",
        "Fecha_Creacion":"2021-03-08 17:03:39",
        "Fecha_Fin":"2021-03-30",
        "Fecha_Ultima_Actualizacion":null
    }
}
Observaciones Se comprobará en la petición distintas opciones que pueden devolver error, como puede ser:
  • Tarjeta regalo no encontrada.
  • Tarjeta regalo deshabilitada.
  • Tarjeta regalo caducada.
  • Tarjeta regalo sin saldo.
Consumir tarjeta regalo asociación
Cabecera X-API-KEY (API KEY proporcionado por FidelCity)
Verbo POST
Formato application/json
Url https://fidelcity.es/api_comercio/consumir_tarjeta_regalo_asociacion
Cuerpo 

{
    "id":"5787",
    "saldo_consumido":"5.00",
    "concepto":"ticket 001"
}
Respuesta 

{
    "estado":"correcto",
    "codigo_mensaje":"tarjeta_regalo_asociacion_consumida_correctamente",
    "mensaje":"Tarjeta regalo asociación consumida correctamente",
    "cliente": {
        "Id":"5787",
        "Importe":"45.00",
        "Credencial":"2021977860079",
        "Habilitada":"1",
        "Descripcion": "Tarjeta regalo pruebas",
        "Fecha_Creacion":"2021-03-08 17:03:39",
        "Fecha_Fin":"2021-03-30",
        "Fecha_Ultima_Actualizacion": "2021-03-10 11:25:30"
    }
}
Observaciones
  • El campo concepto es opcional.

¡FidelCity integrado con tu web!