Satmovil API

La API de SATMovil ofrece un potente conjunto de criterios para la búsqueda, lectura y actualización de contenidos. Este documento describe cómo usar un estilo llamado REST para acceder y editar los datos de SATMovil. La API de SATMovil puede ser útil para varios proyectos de integración con las aplicaciones web u otras aplicaciones. Por ejemplo, puede utilizar la API de SATMovil para sincronizar los datos con una aplicación de escritorio.

Operaciones| Autenticación| Listar| Insertar| Obtener| Actualizar| Eliminar| Colecciones| Ejemplos

Inicio

Operaciones

Puede invocar cinco métodos diferentes, tal como se describe en la siguiente tabla.

Operación Descripción Petición
listar Se obtiene la lista de registros de una colección GET
insertar Se crea un nuevo registro dentro de una colección POST donde se pasarán los datos del recurso
obtener Se obtiene un registro especifico GET donde se pasará el identificador del registro
actualizar Se actualizar un registro especifico PUT donde se pasarán los datos del recurso con su identificador
eliminar Se elimina un registro especifico DELETE donde se pasará el identificador del registro
Inicio

Autenticación

Todas las peticiones que se realicen requieren la autenticación del usuario. Una vez realizada la autenticación se devolverá un "token" que se deberá enviar en cada petición.

Petición

POST http://satmovil.onyx.cloud/api/auth

Parámetros

Nombre Valor Descripción
Parámetros requeridos
usuario string Usuario de acceso a la aplicación
clave string Clave de acceso a la aplicación

Respuesta

Sí es satisfactoria devolverá un cadena de caracteres (token). Esta cadena se deberá enviar en cada petición que se realice y tendrá validez durante el día que se ha obtenido (para no tener que autenticarse en cada petición).

string "cfd9663c6b27f87a0c0d132222f601c2"
Inicio

Listar

Se obtiene la lista de registros de una colección.

Petición

GET http://satmovil.onyx.cloud/api/rest/{colección}/{extension}?token={token}

Parámetros

Nombre Valor Descripción
Parámetros requeridos
token string Cadena obtenida en la autenticación
colección string Nombre de la colección - Ver listado de colecciones
Parámetros opcionales
extension string Formato de los datos de respuesta.
vacío: respuesta en formato json
"xml": respuesta en formato xml
Ver listado de colecciones para ver los parámetros opcionales para cada colección.

Respuesta

Sí es satisfactoria la petición, devolverá el listado de registros de la colección en el formato seleccionado.

json
[
{
"id": "25",
"nombre": "Nombre 25",
....
},
...
]
xml
<objects>
<object id="0">
<id>25</id>
<nombre>Nombre 25</nombre>
....
</object>
...
</objects>
Inicio

Insertar

Se crea un nuevo registro dentro de una colección.

Petición

POST http://satmovil.onyx.cloud/api/rest/{colección}/{extension}?token={token}

Parámetros

Nombre Valor Descripción
Parámetros requeridos
token string Cadena obtenida en la autenticación
colección string Nombre de la colección - Ver listado de colecciones
Parámetros opcionales
extension string Formato de los datos de respuesta.
vacío: respuesta en formato json
"xml": respuesta en formato xml

Cuerpo Petición

En el cuerpo de la petición se deben enviar los parámetros específicos para cada colección. Ver listado de colecciones

Respuesta

Sí es satisfactoria la petición, devolverá los datos del registro creado en el formato seleccionado.

json
{
"id": "25",
"nombre": "Nombre 25",
....
}
xml
<object>
<id>25</id>
<nombre>Nombre 25</nombre>
....
</object>
Inicio

Obtener

Se obtiene un registro especifico de una colección.

Petición

GET http://satmovil.onyx.cloud/api/rest/{colección}/{id}/{extension}?token={token}

Parámetros

Nombre Valor Descripción
Parámetros requeridos
token string Cadena obtenida en la autenticación
colección string Nombre de la colección - Ver listado de colecciones
id integer Identificador numérico del registro a obtener
Parámetros opcionales
extension string Formato de los datos de respuesta.
vacío: respuesta en formato json
"xml": respuesta en formato xml

Respuesta

Sí es satisfactoria la petición, devolverá los datos del registro seleccionado en el formato seleccionado.

json
{
"id": "25",
"nombre": "Nombre 25",
....
}
xml
<object>
<id>25</id>
<nombre>Nombre 25</nombre>
....
</object>
Inicio

Actualizar

Se actualizará un registro existente de una colección.

Petición

POST http://satmovil.onyx.cloud/api/rest/{colección}/{id}/{extension}?token={token}

Parámetros

Nombre Valor Descripción
Parámetros requeridos
token string Cadena obtenida en la autenticación
colección string Nombre de la colección - Ver listado de colecciones
id integer Identificador numérico del registro a actualizar
Parámetros opcionales
extension string Formato de los datos de respuesta.
vacío: respuesta en formato json
"xml": respuesta en formato xml

Cuerpo Petición

Nombre Valor Descripción
Parámetros requeridos
sf_method string Su valor debe ser "PUT"
Parámetros opcionales
Ver listado de colecciones para ver los parámetros opcionales para cada colección.

Respuesta

Sí es satisfactoria la petición, devolverá los datos del registro actualizado en el formato seleccionado.

json
{
"id": "25",
"nombre": "Nombre 25",
....
}
xml
<object>
<id>25</id>
<nombre>Nombre 25</nombre>
....
</object>
Inicio

Eliminar

Se elimina un registro especifico de una colección.

Petición

POST http://satmovil.onyx.cloud/api/rest/{colección}/{id}/{extension}?token={token}

Parámetros

Nombre Valor Descripción
Parámetros requeridos
token string Cadena obtenida en la autenticación
colección string Nombre de la colección - Ver listado de colecciones
id integer Identificador numérico del registro a eliminar
Parámetros opcionales
extension string Formato de los datos de respuesta.
vacío: respuesta en formato json
"xml": respuesta en formato xml

Cuerpo Petición

Nombre Valor Descripción
Parámetros requeridos
sf_method string Su valor debe ser "DELETE"

Respuesta

Sí la petición no ha sido satisfactoria, la respuesta se devolverá en el formato seleccionado con los errores que han causado el fallo. Sí un elemento esta ya relacionado, no se podrá borrar el elemento. Por ejemplo, si un Aviso tiene intervenciones realizadas, ya no se podrá eliminar el aviso.

Inicio

Colecciones

En la siguiente tabla se muestran las colecciones disponibles para la api y que métodos están disponibles para cada una de ellas. Para cada colección existen varios parámetros que se pueden usar en los diferentes métodos.

Nombre Descripción Listar Insertar Obtener Actualizar Eliminar
Cliente clientes
Direccion ubicaciones de los clientes
Contacto contactos de los clientes
Almacen almacenes
Empleado empleados
Grupos de empleados empleados
Familia familias de artículos
Subfamilia Subfamilias de artículos
Articulo artículos
ArticulosAlmacen stock de artículos en los almacenes
Equipo elementos de los clientes
Aviso avisos
Intervencion intervenciones de los avisos
TipoContacto tipos de contactos
TipoContrato tipos de contratos
TipoGasto tipos de gastos
TipoHora tipos de horas
TipoIntervencion tipos de intervención
TipoNota tipos de notas de aceptación (Intervención)
TipoProblema tipos de problema
Tarifa tipos de tarifas
Contrato contratos de mantenimiento
Inicio Colecciones

Cliente

Insertar

Nombre Valor Descripción
Parámetros requeridos
codigo string (25) Código del cliente, debe ser único.
nombre string (100) Nombre del cliente.
Parámetros opcionales
cif string (25) El cif del cliente
cpais string (2) El código del país en formato ISO 3166-1 alpha-2. Ver códigos
estado string (50) Estado o provincia
poblacion string (100) Población del cliente
cpostal string (20) Código postal
direccion string (100) Dirección principal
telefono string (25) Número de teléfono
fax string (25) Número de fax
email string (100) Dirección de correo electrónico
web string (150) Página web del cliente
kilómetros float (18,2) Distancia en kilómetros hasta el cliente
horario text Horario del cliente
notas text Notas

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Direccion

Listar

Nombre Valor Descripción
Parámetros opcionales
cliente integer Id de un registro de la colección Cliente

Insertar

Nombre Valor Descripción
Parámetros requeridos
cliente_id integer Id del cliente.
nombre string (100) Nombre de la dirección.
Parámetros opcionales
cpais string (2) El código del país en formato ISO 3166-1 alpha-2. Ver códigos
estado string (50) Estado o provincia
poblacion string (100) Población
cpostal string (20) Código postal
direccion string (100) Dirección
telefono string (25) Número de teléfono

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Contacto

Listar

Nombre Valor Descripción
Parámetros opcionales
cliente integer Id de un registro de la colección Cliente
ubicacion integer Id de un registro de la colección Direccion

Insertar

Nombre Valor Descripción
Parámetros requeridos
cliente_id integer Id del cliente al que pertenece el contacto.
nombre string (100) Nombre del contacto.
Parámetros opcionales
email string (100) Dirección de correo electrónico
telefono string (25) Número de teléfono
movil string (25) Número de móvil
direccion_id integer Id de la ubicación a la que pertenece el contacto

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Almacen

Insertar

Nombre Valor Descripción
Parámetros requeridos
codigo string (25) Código del almacén, debe ser único.
descripcion string (255) Descripción del almacén.

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Empleado

Listar

Nombre Valor Descripción
Parámetros opcionales
almacen integer Id de un registro de la colección Almacen

Insertar

Nombre Valor Descripción
Parámetros requeridos
nombre string (100) Nombre del empleado.
Parámetros opcionales
codigo string (25) El código del empleado
telefono string (25) Número de teléfono
email string (100) Dirección de correo electrónico
color string (7) Color asignado al empleado. El código del color en formato HEX. Ver códigos
almacen_id integer Id del almacen por defecto del empleado

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Grupo de empleado

Listar

Nombre Valor Descripción
Parámetros opcionales
almacen integer Id de un registro de la colección Almacen

Insertar

Nombre Valor Descripción
Parámetros requeridos
nombre string (100) Nombre del empleado.
Parámetros opcionales
color string (7) Color asignado al empleado. El código del color en formato HEX. Ver códigos
almacen_id integer Id del almacen por defecto del empleado

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Familia

Insertar

Nombre Valor Descripción
Parámetros requeridos
codigo string (25) Código de la familia, debe ser único.
descripcion string (100) Descripción de la familia.

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Subamilia

Insertar

Nombre Valor Descripción
Parámetros requeridos
codigo string (25) Código de la subfamilia, debe ser único.
descripcion string (100) Descripción de la subfamilia.
familia_id bigint (20) id de la familia.

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Articulo

Listar

Nombre Valor Descripción
Parámetros opcionales
familia integer Id de un registro de la colección Familia

Insertar

Nombre Valor Descripción
Parámetros requeridos
codigo string (25) El código del artículo
familia_id integer Id de un registro de la colección Familia
descripcion string (100) Descripción del artículo
Parámetros opcionales
imagen_url string (255) Dirección web de la imagen del artículo
precio float (18,2) Precio de venta
precio_coste float (18,2) Precio de compra
marca string(20) Marca del artículo
modelo string(20) Modelo del artículo
ubicacion string(255) Lugar donde se coloca el artículo
garantia integer Meses de garantía
notas text Notas

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

ArticulosAlmacen

Listar

Nombre Valor Descripción
Parámetros opcionales
articulo integer Id de un registro de la colección Articulo
almacen integer Id de un registro de la colección Almacen

Insertar

Nombre Valor Descripción
Parámetros requeridos
almacen_id integer Id de un registro de la colección Almacen
articulo_id integer Id de un registro de la colección articulo
cantidad float (18,2) Cantidad traspasada
Parámetros opcionales
fecha date Fecha del movimiento, por defecto la fecha actual (yyyy-mm-dd)
entrada integer(1) Tipo de movimiento: 0 = Salida; 1 = Entrada; Por defecto "0" (Salida)
concepto text Concepto del movimiento
Inicio Colecciones

Equipo

Listar

Nombre Valor Descripción
Parámetros opcionales
articulo integer Id de un registro de la colección Articulo
ubicacion integer Id de un registro de la colección Direccion
empleado integer Id de un registro de la colección Empleado

Insertar

Nombre Valor Descripción
Parámetros requeridos
direccion_id integer Id de un registro de la colección Direccion
n_serie string (255) Nº de serie del elemento. Solo es obligatorio sí en la configuración general no se ha activado la opción "Códigos Autonuméricos" para los elementos.
Parámetros opcionales
descripcion text Descripción del elemento.
articulo_id integer Id de un registro de la colección Articulo
empleado_id integer Id de un registro de la colección Empleado. El empleado que ha instalado el elemento.
f_instalacion date Fecha de instalación del elemento (yyyy-mm-dd)
marca string(20) Marca del artículo
modelo string(20) Modelo del artículo
ubicacion string(255) Lugar donde se coloca el artículo
f_garantia_i date Fecha de inicio de la garantía (yyyy-mm-dd).
f_garantia_f date Fecha final de la garantía (yyyy-mm-dd).
notas text Notas

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Aviso

Listar

Nombre Valor Descripción
Parámetros opcionales
cliente integer Id de un registro de la colección Cliente
ubicacion integer Id de un registro de la colección Direccion
elemento integer Id de un registro de la colección Equipo
empleado integer Id de un registro de la colección Empleado
f_cierre DATE fecha de cierre en formato yyyy-mm-dd
estado integer estado=0: avisos cerrados; estado=1: avisos abiertos
fecha_prevista DATE fecha prevista en formato yyyy-mm-dd

Insertar

Nombre Valor Descripción
Parámetros requeridos
cliente_id integer Id del cliente al que pertenece el contacto.
Parámetros opcionales
equipo_id integer Id del elemento al que pertenece el aviso
direccion_id integer Id de la ubicación a la que pertenece el aviso
contacto_id integer Id del contacto del aviso
n_referencia varchar(255) Número de aviso externo

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Intervención

Listar

Nombre Valor Descripción
Parámetros opcionales
cliente integer Id de un registro de la colección Cliente
aviso integer Id de un registro de la colección Aviso
empleado integer Id de un registro de la colección Empleado
desde date Fecha inicio intervalo
hasta date Fecha fin intervalo
fmodif date Modificados a partir de la fecha
Inicio Colecciones

TipoContacto

Insertar

Nombre Valor Descripción
Parámetros requeridos
tipo string (50) Nombre del tipo
defecto integer(1) Si es por defecto. 0 = No; 1 = Si; Por defecto "0"

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

TipoContrato

Insertar

Nombre Valor Descripción
Parámetros requeridos
tipo_contrato string (50) Nombre del tipo
defecto integer(1) Si es por defecto. 0 = No; 1 = Si; Por defecto "0"

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

TipoGasto

Insertar

Nombre Valor Descripción
Parámetros requeridos
tipo_gasto string (50) Nombre del tipo
precio float (15,5) precio
visible_cliente integer(1) gasto interno (No visible al cliente)
defecto integer(1) Si es por defecto. 0 = No; 1 = Si; Por defecto "0"

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

TipoHora

Insertar

Nombre Valor Descripción
Parámetros requeridos
tarifa_id integer Id de la tarifa a la que pertenece
tipo_hora string (50) Nombre del tipo
precio float (15,5) precio
defecto integer(1) Si es por defecto. 0 = No; 1 = Si; Por defecto "0"

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

TipoIntervencion

Insertar

Nombre Valor Descripción
Parámetros requeridos
tipo string (50) Nombre del tipo
defecto integer(1) Si es por defecto. 0 = No; 1 = Si; Por defecto "0"

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

TipoNota

Insertar

Nombre Valor Descripción
Parámetros requeridos
tipo string (50) Nombre del tipo
texto text Texto
defecto integer(1) Si es por defecto. 0 = No; 1 = Si; Por defecto "0"

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

TipoProblema

Insertar

Nombre Valor Descripción
Parámetros requeridos
tipo_problema string (50) Nombre del tipo
tiempo string (5) Tiempo en formato hh:mm
defecto integer(1) Si es por defecto. 0 = No; 1 = Si; Por defecto "0"

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Tarifa

Insertar

Nombre Valor Descripción
Parámetros requeridos
tarifa string (50) Nombre de la tarifa
defecto integer(1) Si es por defecto. 0 = No; 1 = Si; Por defecto "0"

Actualizar

Los mismos parámetros que el método insertar pero en este caso todos los parámetros son opcionales.

Inicio Colecciones

Contrato

Insertar

Nombre Valor Descripción
Parámetros requeridos
cliente_id bigint (20) Id de la colección Cliente
descripcion string(255) Descripción del contrato de mantenimiento
importe float Importe del contrato de mantenimiento
f_inicio date Fecha de inicio del contrato
f_final date Fecha final del contrato
Parámetros opcionales
f_acept date Fecha de aceptación del contrato
direccion_id bigint(20) Id de la colección Direccion, tiene que existir ésa dirección para el Cliente del contrato.
tipo bigint(20) Id de la colección TipoContrato
Inicio

Ejemplos

Aquí podéis encontrar unos ejemplos de como aplicar la api en diferentes lenguajes y soluciones.

.NET

Ejemplo en c# de cómo hacer la autenticación para obtener el token, y cómo parametrizarlo en un request para hacer un GET de una colección.

/// Realiza la autenticación y obtiene un token que deberemos pasar en cada solicitud
/// </summary>

public static string GetRestAuthToken(string url, string user, string password)
{
    String token = "";
    try
    {
        using (var client = new WebClient())
        {
            var values = new NameValueCollection();
            values["usuario"] = user;
            values["clave"] = password;
            client.Encoding = Encoding.UTF8;
            if (url.EndsWith("/")) url = url.Remove(url.Length - 1, 1);
            var response = client.UploadValues(url + "/api/auth", values);
            token = UTF8Encoding.UTF8.GetString(response).Trim();
        }
    }
    catch { }
    return token;
}

/// <summary>
/// Realiza un GET caracterísitco para obtener listas de resultados pasando el token. Si el token
/// ha expirado vuelve a solicitarlo y refresca su valor para volver a ser usado

/// </summary>
/// <param name="entityName"></param>
/// <param name="parameters"></param>
/// <returns></returns>
private static string ListJsonFromRequest(string entityName, string parameters)
{
    string jsonResult = "";
    using (var client = new WebClient())
    {
        string entityUri = GetApiURL() + entityName+"?" +
        ((parameters != null) ? (parameters + "&"): "") + "token=" + token;
        try
        {
            jsonResult = WebUtils.DownloadStringAwareOfEncoding(client, new Uri(entityUri));
        }
        catch (WebException e)
        {
            if (e.Message.Contains("(401)"))
            {
                token = WebUtils.GetRestAuthToken(baseURLService, User, Password);
                entityUri = GetApiURL() + entityName + "?" +
                ((parameters != null) ? (parameters + "&") : "") + "token=" + token;
                jsonResult = client.DownloadData(entityUri);
            }
            else throw new Exception(e.Message);
        }
    }
    return jsonResult;
}

PHP

Ejemplo en PHP para realizar una autentificación de empleado.

<?php
    $ch = curl_init("satmovil.onyx.cloud/api/auth");
    $login = array(
        'usuario' => '',
        'clave' => ''
    );
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $login);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true );
    $content = curl_exec( $ch );
    $response = curl_getinfo( $ch );
    if($response['http_code'] != 401){
        $token = trim($content);
        $url = "http://satmovil.onyx.cloud/api/rest/Empleado?token={$token}";
        $param = array(
            'nombre' => 'prueba API5'
        );
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true); //SOLO caso de POST
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($param)); //en caso de POST o PUT
        $content = curl_exec( $ch );
        $response = curl_getinfo( $ch );
        exit(print_r($content).print_r($response));
        if($response['http_code'] != 500){
            if(strpos($response['content_type'],'xml') === false){
                $objects = json_decode($content);
            }else{
                exit($content);
                $content2 = str_replace(array('<','>'),array('','lt;','','gt;'),$content);
                echo nl2br($content2);
                $objects = simplexml_load_string($content);
            }
            var_dump($objects);
        }else{
            exit(print_r($content));
        }
    }else{
        echo $content;
    }
    curl_close($ch);
?>