Desarrolladores
Documentación API Clientes
Para las comunicaciones con la aplicación Web de MNProgram se utilizará un servicio SOAP.
Control de acceso
A continuación los campos necesarios en todas las llamadas contra la API para verificar que se tiene
acceso a los datos contenidos en MnProgram:
MN program web
- numEmpresa: Número de empresa contra el que se registrarán los datos (normalmente será la
empresa 2) - operador: Operador contra el que se validará el acceso y modificación de la base de datos.
Debe ser un usuario de la aplicación, con un nivel de permisos alto (Supervisor). - passMD5: Contraseña del operador encriptada en MD5
Escritorio Cloud
- instancia: Campo interno. Indica qué cliente de Escritorio Cloud está realizando la llamada (a
qué base de datos estamos accediendo). - numEmpresa: Número de empresa contra el que se registrarán los datos (normalmente será la
empresa 2) - operador: Operador contra el que se validará el acceso y modificación de la base de datos. Debe ser un usuario de la aplicación, con un nivel de permisos alto (Supervisor).
- token: Campo interno. Para usar la API en escritorio cloud se debe solicitar un token a MNProgram que limitará su uso frente a operaciones maliciosas de terceros.
MN program cloud
- instancia: Campo interno. Indica qué cliente de MNProgram Cloud está realizando la llamada (a
qué base de datos estamos accediendo). - numEmpresa: Número de empresa contra el que se registrarán los datos (normalmente será la
empresa 2) - operador: Operador contra el que se validará el acceso y modificación de la base de datos. Debe ser un usuario de la aplicación, con un nivel de permisos alto (Supervisor).
Peticiones
A continuación se describen las diferentes peticiones SOAP existentes a disposición de los clientes
Crear oportunidad
Ruta dentro de la aplicación de MnProgram Web:
http://<URL_raíz_ MnProgram_Web>/API/ClientesService.asmx?op=CrearOportunidad
Permite crear una oportunidad dentro del programa asociada a un determinado cliente. Si el cliente no
existe en nuestra base de datos se crea un nuevo cliente potencial y se le asocia la oportunidad.
Además de los campos comunes citados en el primer punto del documento se enviarán los siguientes
datos:
- datosCliente: Texto en formato JSON que contiene los datos principales del cliente al que
queremos asociar la oportunidad. - nombreCli: Nombre del cliente
- telfCli: Teléfono de contacto
- mailCli: Correo electrónico de contacto
- poblacionCli: Población
- nifCli: Documento de identificación
- codPostalCli: Código postal
- nivelEstudios: Formación académica
- situacionLaboral: Situación laboral
- notasOportunidad: Notas u observaciones que se guardarán en la oportunidad una vez creada.
- descripcionOportunidad: Texto que será la descripción de la oportunidad.
- fuenteOportunidad: Texto que indica la entidad que está efectuando la petición (el nombre de la empresa). Se guardará en el campo ‘fuente’ de la oportunidad.
A continuación se muestra un ejemplo del objeto con los datos del cliente en formato JSON y una captura de una prueba válida del servicio:
{ 'nombreCli' : 'Cliente 1', 'nifCli' : '345345363M', 'telfCli' : '643123456', 'mailCli': 'nuevom@il.com', 'poblacionCli' : 'A Coruña', 'codPostalCli' : '15003', 'provinciaCli' : 'A Coruña', 'nivelEstudios' : 'Bachillerato', 'situacionLaboral' : 'Desempleado' }
Búsqueda de Clientes
El orden y criterio de búsqueda del cliente según los campos enviados sigue el siguiente orden:
- NIF
- Nombre
- Teléfono
Además si se recupera al cliente tras la búsqueda y alguno de los campos que se envían cubiertos son vacíos en nuestra Base de Datos se rellenarán dichos campos con el valor recibido.
Getexpedientes
Ruta dentro de la aplicación de MnProgram Web:
http://<URL_raíz_ MnProgram_Web>/API/ClientesService.asmx?op=GetExpedientes
Petición que devuelve la información principal de los diferentes expedientes/cursos que existen en la
base de datos de MnProgram. Esta petición únicamente hace uso de los parámetros comunes citados en
el primer punto. Por simplicidad a partir de ahora hablaremos de expedientes para referirnos tanto a
cursos como a expedientes.
La respuesta generada contendrá la siguiente información de cada uno de los expedientes/cursos:
- numero: Número del expediente. Campo interno de gestión de la base de datos.
- anho: Año del expediente
- codigo: Código identificativo del expediente a nivel de usuario
- descripción: Título/Descripción del expediente
- tipo: Tipo de expediente
- estado: Generalmente “Abierto” o “Cerrado”
Contratoscliente
Ruta dentro de la aplicación de MnProgram Web:
http://<URL_raíz_ MnProgram_Web>/API/ContratosService.asmx?op=ContratosCliente
Permite suministrar información sobre un contrato. La llamada creará una actuación en el historial del
expediente del cliente/sociedad seleccionado, con los datos enviados. Además de los campos comunes
contendrá los siguientes parámetros:
- datosContrato: Contiene la información principal (en formato JSON) que se necesita para documentar la inserción del contrato en base de datos.
- nombreCliente: Nombre del cliente/sociedad que firma el contrato.
- cifCliente: NIF/CIF del cliente del contrato. Se utilizará este campo para buscar al cliente en base de datos.
- naturaleza: Descripción de la naturaleza del contrato.
- Importe: Importe total del contrato
- tituloExpediente: Título del expediente al que irá asociado el contrato. Si no se envía este dato cubierto en la petición por defecto será “Contratos del Cliente”.
- tipoExpediente: Tipo del expediente al que asociaremos el contrato. Si no se envía
este dato cubierto en la petición por defecto será “Contrato”. - datosPerso: Contiene la información que irá en las pestañas personalizadas de la actuación asociada al expediente y creada con la llamada. Se trata de un array de objetos en formato JSON, donde cada objeto sería una pestaña personalizada.
- entidad: Por defecto 2. Campo interno que indica el tipo de pestaña personalizada a la que insertaremos los datos (2 = actuación expediente).
- nombrePestana: Nombre de la pestaña en la que queremos insertar los datos.
- Val1,val2,val3…: El resto de propiedades del objeto indican con el nombre la etiqueta del campo en la pestaña y con el valor los datos que se insertarán en dicho campo.
Si el cliente y/o expediente no se encuentran en la base de datos se crearán y se asociará la información
de la llamada en el historial del expediente recién creado.
Ejemplo de uso
Para empezar debemos configurar una pestaña personalizada de actuación de historial con los campos personalizados que vamos a enviar en la llamada. En la imagen inferior se muestra la pestaña en el programa:
Una vez creada podremos enviar los datos personalizados en la llamada, en otro caso NO se guardarán,
el servicio SOAP no se encarga de crear las pestañas personalizadas.
A continuación se muestra un ejemplo de posibles datos válidos para una llamada del servicio, ejecutada
en local contra la empresa de prueba (Empresa 1):
<x:Envelope xmlns:x="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
<x:Header/>
<x:Body>
<tem:ContratosCliente>
<tem:instancia></tem:instancia>
<tem:numEmpresa>1</tem:numEmpresa>
<tem:operador>Supervisor</tem:operador>
<tem:passMD5>1239deed1159f6e514a3a649d51caabb</tem:passMD5>
<tem:datosContrato>
{ 'nombreCliente' : 'ELOY RAMIREZ GONZALEZ', 'cifCliente' : '53453456-F', 'importe' : 20, 'naturaleza' : 'Actuación desde SOAP}
</tem:datosContrato>
<tem:datosPerso>
[{ 'entidad' : '2', ' nombrePestana ' : 'Datos Expediente', 'Firma contrato' : '28/05/2018', 'Nombre cliente' : 'ELOY'}]
</tem:datosPerso>
</tem:ContratosCliente>
</x:Body>
</x:Envelope>
El resultado es la creación de una actuación en el historial del expediente “Contratos con cliente” (de tipo “Contrato”) y con cliente “ELOY RAMIREZ GONZALEZ”. Esta actuación tendrá como título “Actuación desde SOAP” e insertará en la pestaña personalizada “Datos Expediente” los valores del resto de propiedades del objeto “datosPerso”.
Con la imagen de la parte inferior se puede ver con más claridad el resultado de la llamada.
Como se puede apreciar, se ha creado una actuación “Actuación desde SOAP” en el expediente
“Contratos con Cliente” que contiene en los campos personalizados la información enviada en la
llamada.
Podemos enviar tantos campos personalizados como queramos en la llamada. En el caso de que no
existan en la pestaña simplemente no se registrará ese dato. Entidad y nombrePestana son propiedades
reservadas y no deben usarse como etiquetas de los campos personalizados. Por último salientar que
podemos enviar varias pestañas personalizadas en la misma llamada, incluyendo sus objetos dentro de
las llaves “[]” del campo datosPerso.
[{ 'entidad' : '2', ' nombrePestana ' : 'Personalizada 1', 'Firma contrato' : '28/05/2018', 'Nombre
cliente' : 'ELOY'},
{ 'entidad' : '2', ' nombrePestana ' : 'Personalizada 2', ‘Fecha emision’ : '03/08/2018'}]
Depuración
Para tener acceso al formulario de envío de la petición y probar su funcionamiento podemos acceder a la página del servicio. En los apartados de las distintas peticiones se proporcionan las rutas de las mismas dentro de la aplicación de MnProgram Web.
Simplemente debemos sustituir <URL_raíz_ MnProgram_Web> por la URL base de nuestra aplicación web.Es posible que no se muestre el formulario por motivos de seguridad. Podemos activarlo temporalmente
añadiendo las siguientes propiedades en el Web.config de nuestra aplicación de MnProgramWeb
dentro de la siguiente estructura de llaves:
reservadas y no deben usarse como etiquetas de los campos personalizados. Por último salientar que
podemos enviar varias pestañas personalizadas en la misma llamada, incluyendo sus objetos dentro de
las llaves “[]” del campo datosPerso.
<configuration>
<system.web>
<webServices>
<protocols>
<add name="HttpGet"/>
<add name="HttpPost"/>
</protocols>
</webServices>
</system.web>
</configuration>
¿Necesitas Ayuda?
Contacta con nuestros asesores
Llámanos al 981 146 300 o envíanos un email a comercial@mnprogram.com
