API SOAP Clientes Guía de desarrollo
Introducción
SGC Web Ri505 dispone de una API (interfaz de programación de aplicaciones (del inglés:
Application Programming Interface), que permite mediante una interfaz simple, potente y segura,
desarrollar aplicaciones para la obtención de los datos de operación de su compañía. Este
documento está dirigido a personas con conocimiento básico para el desarrollo de software, servicios
web (WebServices) y el sistema SGC Web Ri505.
La API de SGC Web Ri505 está basada en el protocolo SOAP (del inglés Simple Object Access
Protocol). El protocolo SOAP es un protocolo estándar que define como dos objetos en diferentes
entornos pueden comunicarse entre si, mediante intercambio de mensajes en formato XML.
¿Qué es SOAP?
• SOAP significa Simple Object Access Protocol
• SOAP es un protocolo de comunicación
• SOAP es para la comunicación entre aplicaciones
• SOAP es un formato para el envío de mensajes
• SOAP se comunica a través de Internet
• SOAP es independiente de la plataforma
• SOAP es independiente del lenguaje
• SOAP se basa en XML
• SOAP es simple y extensible
• SOAP permite la comunicación donde hay firewalls
• SOAP es una recomendación del W3C
Para mas información acerca de SOAP, ingrese al sitio oficial de la W3C
(http://www.w3schools.com/webservices/ws_soap_intro.asp):
Ubicación de la API
Para acceder a la API SOAP de SGC Web Ri505 es necesario establecer una conexión a la
siguiente dirección de acceso:
http://[nombre_instancia]/ws/1094AEV2/v2/soap.php
Ejemplo:
http://sgcmovil.sgcweb.com.mx/ws/1094AEV2/v2/soap.php
Autenticación de usuario:
Para poder establecer una conexión a la API, será necesario contar con una cuenta de usuario
previamente registrada así como conocer el password asignado a esta cuenta, esta cuenta de
usuario debe estar ligada a una estación red de tipo “Aplicación externa”.
Información disponible
La arquitectura de la aplicación está basada en módulos funcionales, la información a la que se
puede acceder desde la API es obtenida a través de una cadena de texto basada en objetos
formateados con el estándar JSON (http://www.w3schools.com/json/) de los siguientes objetos:
1. Clientes :
Identificador Clientes
Definición Clientes del sistema SGC Web RI505
(*) Campos Obligatorios
Atributos
Atributo Tipo descripción
numero_cliente int(20) Número generado por SGC Web
identificador_externo varchar(50) Identificador de la aplicación externa,
(*) Usado para hacer referencia a un registro.
nombre (*) varchar(150) Nombre Fiscal , Razón social del cliente
rfc (*) varchar(50) Identificador Fiscal del Cliente
calle (*) varchar(150) Calle del Cliente
no_exterior (*) varchar(15) Número exterior
no_interior varchar(15) Número interior
colonia (*) varchar(100) Colonia
localidad (*) varchar(100) Localidad
referencia varchar(100) Ayuda para la dirección
ciudad (*) varchar(100) Ciudad
estado (*) varchar(100) Estado
codigo_postal (*) varchar(20) Código postal
pais (*) varchar(150) País
telefono1 (*) varchar(25) Teléfono Principal
telefono2 varchar(25) Teléfono secundario
activo int(1) Si el cliente está inactivo se bloquean los
pedidos, valores :
“1” Activo
“0” Inactivo.
Cualquier valor diferente a 1 se toma como
inactivo.
email varchar(150) Correo electrónico del cliente
saldo decimal(12,4) Total de consumos que tiene el cliente, se
incrementa con las ventas, y decrementa
con los pagos.
politica_venta_id varchar(50) Identificador externo de la política de venta
relacionada
Atributos para filtrar numero_cliente
identificador_externo
Llamadas disponibles
Las llamadas disponibles para clientes son 3 :
1. “registrar” .- Registra o edita un cliente.
2. “obtenerUltimoFolio” .- Obtiene el último folio de clientes registrado
3. “obtenerListaPorFolio” .- Obtiene una lista de clientes en base al folio.
para todas las llamadas es necesario haber iniciado sesión mediante el método de sesión de la api
registrado en el documento SGC WEB Ventas - API SOAP Sesión, a continuación se muestran las
llamadas para el módulo de clientes :
Registrar Cliente
Llamada procesarPeticion
Función Registra o edita información de clientes.
Sintaxis procesarPeticion(session,modulo, accion, paquete)
Parámetros de entrada ● session: Id de sesión (Obtenido con login)
● modulo: Identificador del módulo, en este caso: “Clientes”
● accion: Identificador de la acción del módulo, en este caso: “registrar”
● paquete: String con el objeto de cliente codificado con el estándar JSON.
Respuesta La respuesta es un objeto con 2 atributos :
● codigo: Código de proceso nos indica si el proceso se realizó con éxito o no.
● informacion: Si la acción a ejecutar requiere retornar información entonces el sistema retornará
en este atributo la información.
Tabla de códigos e información de respuesta
Código Información Descripción
0000 json del objeto cliente Éxito, la acción de guardado se
procesó correctamente.
1111 json del objeto cliente Éxito, la acción de edición se
procesó correctamente
101701 Sin información Error, No se recibió información
válida en
identificador_externo.
101702 Sin información Error, No se recibió información
válida en el nombre.
101703 Sin información Error, No se recibió información
válida en el rfc.
101704 Sin información Error, No se recibió información
válida en el telefono1.
101705 Sin información Error, No se recibió información
válida en el atributo calle.
101706 Sin información Error, No se recibió información
válida en el atributo
no_exterior.
101707 Sin información Error, No se recibió información
válida en el atributo colonia.
101708 Sin información Error, No se recibió información
válida en el atributo localidad.
101709 Sin información Error, No se recibió información
válida en el atributo ciudad.
101710 Sin información Error, No se recibió información
válida en el atributo estado.
101711 Sin información Error, No se recibió información
válida en el atributo
codigo_postal (deben de ser 5
números).
101712 Sin información Error, No se recibió información
válida en el atributo pais.
101713 Sin información Error, No se encontró la política
especificada
101714 Sin información Error, campo ‘activo’ es un
valor diferente a ‘0’ y ‘1’.
101715 Sin información Error, valor no válido en campo
telefono2.
101716 Sin información Error, valor no válido en campo
referencia.
101717 Sin información Error, valor no válido en campo
saldo.
101718 Sin información Error, formato no válido para
campo correo.
101719 Sin información Error el rfc, ya existe.
101720 Sin información Error, el formato del rfc es
inválido.
Ejemplo de llamada: $options = array(
"location" => "http://sgcmovil.com/ws/1094AEV2/v2/soap.php",
"uri" => '',
"trace" => 0
);
$user_auth = array(
"user_name" => "aplicaciones_externas",
"password" => MD5("aplicaciones_externas"),
"version" => '.01'
);
$clientsoap = new SoapClient(NULL, $options);
$respuestalogin = $clientsoap->login($user_auth,"pegasus");
$sessionId = $respuestalogin->id;
//Para poder registrar un cliente en SGC WEB se debe crear un objeto Cliente, se tiene que //codificar
como string JSON, ejemplo:
$cliente->numero_cliente = "";//Dejar vacio ya que es asignado por SGC Web
$cliente->identificador_externo = "120045";
$cliente->nombre = "Público en general";
$cliente->rfc = "XAXX010101000";
$cliente->calle = "Paseo del Norte";
$cliente->no_exterior = "5600";
$cliente->no_interior = "";
$cliente->colonia = "Fraccionamiento Guadalajara Technology Park";
$cliente->localidad = "Zapopan";
$cliente->referencia = "Fraccionamiento Guadalajara Technology Park";
$cliente->ciudad = "Zapopan";
$cliente->estado = "Jalisco";
$cliente->codigo_postal = "45010";
$cliente->pais = "México";
$cliente->telefono1 = "Industrial";
$cliente->telefono2 = "";
$cliente->activo = 1;
$cliente->email = "cliente@corporativosade.com.mx";
$cliente->saldo = 0;
$cliente->politica_venta_id = "";
$cliente_json = json_encode($cliente);
$respuesta = $clientsoap->procesarPeticion(
$sessionId,
"Clientes",
"registrar",
$cliente_json );
if( $respuesta->codigo = ‘0000’ )
{
echo “Cliente registado con éxito”;
}
else
{
echo “Error , código : ”.$respuesta->codigo;
}
Ejemplo de salida: ● codigo: ‘0000’;
● informacion: ‘{"numero_cliente":"145","numero_cuenta":"120045","nombre":"P\u00fablico en
general","rfc":"XAXX010101000","calle":"Paseo del
Norte","no_exterior":"5600","no_interior":"","colonia":"Fraccionamiento Guadalajara
Technology Park","localidad":"Zapopan","referencia":"Fraccionamiento Guadalajara
Technology
Park","ciudad":"Zapopan","estado":"Jalisco","codigo_postal":"M\u00e9xico","pais":"45010","t
elefono1":"Industrial","telefono2":"","activo":true,"email":"cliente@corporativosade.com.mx","
saldo":0,"politica_venta_id":""}’;
if( $respuesta->codigo = ‘0000’ )
{
echo “Cliente registado con éxito”;
$cliente = json_decode( $respuesta->informacion );//Objeto cliente
}
else
{
echo “Error , código : ”.$respuesta->codigo;
}
Obtener el último folio de clientes
Llamada procesarPeticion
Función Obtiene el folio del clientes más reciente registrado en el sistema SGC Web
Sintaxis procesarPeticion(session, modulo, accion,paquete )
Parámetros de entrada ● session: Id de sesión (Obtenido con login)
● modulo: Identificador del módulo, en este caso: ‘Clientes’
● accion: Identificador de la acción del módulo, en este caso:’obtenerUltimoFolio’
● paquete: En este parámetro no se envía información.
Respuesta La respuesta es un objeto con 2 atributos :
● codigo: Código de proceso nos indica si el proceso se realizó con éxito o no.
● informacion: Si la acción a ejecutar requiere retornar información entonces el sistema
retornará en este atributo la información.
Tabla de códigos e información de respuesta
Código Información Descripción
0000 Ultimo Folio de clientes Éxito , la acción se procesó
correctamente.
Ejemplo PHP
$options = array(
"location" => "http://sgcmovil.com/ws/1094AEV2/v2/soap.php",
"uri" => '',
"trace" => 0
);
$user_auth = array(
"user_name" => "aplicaciones_externas",
"password" => MD5("aplicaciones_externas"),
"version" => '.01'
);
$clientsoap = new SoapClient(NULL, $options);
$respuestalogin = $clientsoap->login($user_auth,"pegasus");
$sessionId = $respuestalogin->id;
$respuesta = $clientsoap->procesarPeticion($sessionId, "Clientes", "obtenerUltimoFolio", “”
);
if( $respuesta->codigo = ‘0000’ )
{
$ultimo_folio = $respuesta->informacion;
}
Obtener lista de Clientes
Llamada procesarPeticion
Función Obtiene lista de objetos de clientes.
Sintaxis procesarPeticion(session, modulo, accion, paquete)
Parámetros de entrada ● session: Id de sesión (Obtenido con login)
● modulo: Identificador del módulo, en este caso:”Clientes”
● accion: Identificador de la acción del módulo, en este caso: “obtenerListaPorFolio”
● paquete: String con formato JSON en un objeto con los atributos ‘folioPosicion’ y
‘cantidadElementos’, en el caso del atributo ‘folioPosicion’ se refiere al folio del cliente
desde el cual se empezarán a obtener los mismos ( este parámetro es obligatorio ) y el
atributo ‘cantidadElementos’ que se refiere a la cantidad de cliente que se quieren obtener,
la cantidad máxima disponible son 200, más de esta cantidad generará un error (este
parámetro no es obligatorio, su valor por defecto es 200).
Respuesta La respuesta es un objeto con 2 atributos :
● codigo: Código de proceso nos indica si el proceso se realizó con éxito o no.
● informacion: Si la acción a ejecutar requiere retornar información entonces el sistema
retornará en este atributo la información.
Tabla de códigos e información de respuesta
Código Información Descripción
0000 lista json de objetos de cliente Éxito , la acción se procesó
correctamente.
101721 Sin información No se encontró información.
Ejemplo de llamada: $options = array(
"location" => "http://sgcmovil.com/ws/1094AEV2/v2/soap.php",
"uri" => '',
"trace" => 0
);
$user_auth = array(
"user_name" => "aplicaciones_externas",
"password" => MD5("aplicaciones_externas"),
"version" => '.01'
);
$clientsoap = new SoapClient(NULL, $options);
$respuestalogin = $clientsoap->login($user_auth,"pegasus");
$sessionId = $respuestalogin->id;
//Crear el parámetro paquete
$busqueda->folioPosicion = 457; (Obligatorio)
$busqueda->cantidadElementos = 1; (La cantidad máxima son 200)
$paquete_json = json_encode( $busqueda );
$respuesta = $client->procesarPeticion(
$sessionId,
"Clientes",
"obtenerListaPorFolio",
$paquete_json
);
if( $respuesta->codigo = ‘0000’ )
{
echo “Política se obtuvo con éxito ”;
$lista_clientes = json_decode( $respuesta->informacion );}
else
{echo “Error , código : ”.$respuesta->codigo;}
Ejemplo de respuesta: ● codigo: ‘0000’
● informacion:
‘[{"numero_cliente":"145","identificador_externo":"120045","nombre":"P\u00fablico en
general","rfc":"XAXX010101000","calle":"Paseo del
Norte","no_exterior":"5600","no_interior":"","colonia":"Fraccionamiento Guadalajara
Technology Park","localidad":"Zapopan","referencia":"Fraccionamiento Guadalajara
Technology
Park","ciudad":"Zapopan","estado":"Jalisco","codigo_postal":"M\u00e9xico","pais":"45
010","telefono1":"Industrial","telefono2":"","activo":true,"email":"cliente@corporativosa
de.com.mx","saldo":0,"politica_venta_id":""},{"numero_cliente":"146","identificador_ext
erno":"120089","nombre":"P\u00fablico en general
2","rfc":"XAXX010101001","calle":"Paseo del
Norte","no_exterior":"5610","no_interior":"","colonia":"Fraccionamiento Guadalajara
Technology Park","localidad":"Zapopan","referencia":"Fraccionamiento Guadalajara
Technology
Park","ciudad":"Zapopan","estado":"Jalisco","codigo_postal":"M\u00e9xico","pais":"45
010","telefono1":"Industrial","telefono2":"","activo":true,"email":"cliente2@corporativos
ade.com.mx","saldo":0,"politica_venta_id":""}]’
Para poder obtener la lista de clientes, se tiene que decodificar el string JSON,
if( $respuesta->codigo = ‘0000’ )
{
echo “Cleintes se obtuvo con éxito ”;
$lista_clientes = json_decode( $respuesta->informacion );}
else
{echo “Error , código : ”.$respuesta->codigo;}
