SimanG8 Web API - Generales

Generales

En esta sección encontrará información general del uso y consumo de los servicios proporcionados por SimanG8^® WebAPI.

Solicitudes (Requests)

Las solicitudes se envían mediante una solicitud (request) HTTP estándar y a continuación se describen los distintos elementos que la conforman. Ejemplo:


                PUT /SimanG8.WebAPI/api/erp/Clientes HTTP/1.1
    Host: localhost
    Content-Type: application/json
    Cache-Control: no-cache
    Postman-Token: e7161323-6d90-4daa-bc7c-987a9c4124c4

    [
        {
            "idCliente":"ef355e76-af41-4029-9004-583f525f8af7",
            "NombreComercial": "NOMBRE COMERCIAL MODIFICADO",
            "PrimerContactoForma": "SECCIÓN AMARILLA"
        }
    ]

Encabezado (headers)

Autenticación

Todas las peticiones a SimanG8® WebAPI requieren autenticación. Esto se logra mediante autenticación básica. Por lo que deberá añadir el parámetro “Authorization” e indicar el nombre de usuario y contraseña codificado en Base64. El usuario y contraseña deberá corresponder a una cuenta activa de SimanG8® ERP. Ejemplo:

Authorization: Basic QWRtaW45UzNtMW4=

Formato

SimanG8® WebAPI recibe la información en formato JSON, por lo que es importante especificarlo en el parámetro Content-Type en el encabezado: Ejemplo:

Content-Type: application/json

Cuerpo (body)

Las operaciones CRUD (PUT/POST/DELETE) reciben la información en el body en forma de arreglo en formato JSON, por lo que podrán procesar uno o varios registros en cada llamada. Las estructuras del cuerpo de la solicitud dependerán de cada uno de los servicios. En la sección de modelos de datos podrá consultar las distintas estructuras de datos y sus elementos. En los servicios PUT y POST deberá incluir, al menos, aquellos elementos que estén marcados como requeridos.

Verbos

Los verbos o métodos HTTP identifican el propósito de la solicitud. En función de los lineamientos REST API se implementan los siguientes verbos para cada tipo de operación.

Verbo	Acción
`GET`	Obtener información
`POST`	Crear registros nuevos
`PUT`	Actualizar registros existentes
`DELETE`	Eliminar registros existentes

Respuestas (Response)

Las respuestas de los métodos se obtienen en un mensaje HTTP estándar (response) que puede contener información tanto en el encabezado como en el cuerpo.

Códigos de respuesta (HTTP Status Code)

Las respuestas podrán utilizar alguno de los siguientes códigos HTTP de respuesta:

Código	Descripción
`200 OK`	La petición se completó correctamente.
`201 Created`	La petición de creación se completó correctamente.
`401 Unauthorized`	El usuario no cuenta con los permisos suficientes para realizar la operación solicitada. Vea "Autenticación".
`404 Not Found`	El registro solicitado no existe.
`409 Conflict`	El registro genera un conflicto. Podría deberse a una duplicidad (infracción de llave privada) o infracción de llave foránea.
`500 Internal Server Error`	Ocurrió algún error al procesar la solicitud. Por ejemplo una validación de una regla de negocio o un error interno (como un error en el acceso a la base d edatos). Ver los detalles de la respuesta (en el body) para más información.

Encabezados (Header)

Los encabezados de la respuesta contendrán información general de la llamada. Los resultados específicos de cada elemento (del cuerpo) se incluirán en el cuerpo de la respuesta.

Siman

Para ampliar la información de la respuesta se podrán añadir encabezados con el prefijo “Siman-“
Según la operación podrá tener información específica de la misma, pero los siguientes encabezados siempre formarán parte de las respuestas, según el verbo de la petición:

Encabezado	Descripción	Verbo
`Siman-Afectados`	Número de elementos efectivamente afectados (Por ejemplo: Agregados, actualizados o eliminados).	`POST/PUT/DELETE`
`Siman-Procesados`	Número de elementos recibidos en la llamada.	`POST/PUT/DELETE`
`Siman-Errores`	Número de elementos con estado de error.	`POST/PUT/DELETE`
`Siman-Registros`	Número de registros regresados.	`GET`

Ejemplo:

Cache-Control →no-cache
Content-Length →224
Content-Type →application/json; charset=utf-8
Date →Tue, 03 Apr 2018 22:00:19 GMT
Expires →-1
Pragma →no-cache
Server →Microsoft-IIS/10.0
Siman-Afectados →1
Siman-Errores →0
Siman-Procesados →1
X-AspNet-Version →4.0.30319

Cuerpo (Body)

En el cuerpo de la respuesta se recibirán detalles de la acción realizada con cada elemento que fue afectado o que tuvo error. Según la operación podrá tener información específica de la misma, pero todas las respuestas a los verbos POST/PUT/DELETE contendrán las siguientes propiedades:

Encabezado	Descripción
`Indice`	Número de elemento al que corresponde la respuesta. Corresponde a cada elemento recibido, en base cero.
`StatusCode`	Código de estatus (HTTP Status Code) para indicar el resultado de la operación con el elemento.
`Detalles`	Información adicional con respecto a la acción del elemento. Si el StatusCode es un error, aquí se indicará información del error.

Ejemplo:


                [
    {
        "Location": "http://localhost/SimanG8.WebAPI/api/erp/Clientes/ef355e76-af41-4029-9004-583f525f8af7",
        "Indice": 0,
        "StatusCode": 200,
        "Detalles": "Se modificó el cliente.\nClave:GC-1967\nId:ef355e76-af41-4029-9004-583f525f8af7"
    }
]