# Ventas

En este capítulo se gestionan las ventas del sistema

# Añadir nueva venta

Con esta función, es posible llevar a cabo la creación de ventas así como sus productos asociados y sus fechas de entrega.

NOTA:
- Si el producto no existe en la base de datos se devolverá un error y toda la transacción será cancelada. Se recomienda antes usar el endpoint ITEM/READ para comprobar que el producto existe realmente.
- Las fechas han de estar en el formato especificado.
- La venta se puede crear con nombre de cliente o su identificador del sistema. Pero uno de los dos deberá ser añadido pese a que se indican como NO OBLIGATORIO.
- Se recomienda antes usar el endpoint CUSTOMER/READ para validar el nombre del cliente.

IMPORTANTE
- Si el producto introducido es un artículo, se creará una estructura con el nombre PK-CODIGOVENTA-PRODUCTO-1.

### URL
`/CTNEAT/SALEORDER/ADD/{tkn}`

### Método HTTP
<span style="background-color: RGB(22,216,80); color: white; font-weight: bold; padding: 8px;">POST</span>


### Parámetros de la solicitud
#### Parámetros de la venta
| Nombre del parámetro | Tipo de dato | Descripción del parámetro | Obligatorio | Posibles valores |
| -------------------- | ------------ | ------------------------ | ----------- | -----------       |
|   CODIGOVENTA        |  cadena      |    Código de la venta    |       Sí    | Cualquiera        |
|   FECHACREACION      |  cadena      |    Fecha de la venta |    Sí    | Ha de ser una string con el formato YYYYMMDDHHmmSS |
|   REFERENCIACLIENTE  |  cadena      |    Código de la venta para el cliente |       No      | Cualquiera |
|   NOMBRECLIENTE      |  cadena      |   Nombre del cliente |       No      | Cualquiera que esté entre los que hay almacenados en el sistema |
|   IDCLIENTE      |  numérico   |   Identificador del cliente |       No      | Cualquiera que esté entre los que hay almacenados en el sistema |
|   LINEAS             |  Lista de objetos   |    Líneas asociadas a la venta |       No      | Cualquiera que tenga el formato de la tabla de parámetros de la línea de la venta |

#### Parámetros de la Línea de la venta
| Nombre del parámetro | Tipo de dato | Descripción del parámetro | Obligatorio | Posibles valores |
| -------------------- | ------------ | ------------------------ | ----------- | -----------       |
|   PRODUCTO           |  cadena      |    Código del producto asociado a la venta    |       Sí    | Cualquiera  que ya exista en la base de datos    |
|   UNIDADES           |  numérico    |    Unidades necesarias del producto  |    Sí       | Números positivos enteros |
|   VERSIONPRODUCTO    |  cadena      |    Versión del producto seleccionado   |       No      | Versión del producto que aparece en el sistema. Si no se informa el campo, se añadirá la versión por defecto (v0) |
|   PRECIO             |  numérico    |   Precio de la línea     |     Sí    | Cualquiera que no sea negativo con el siguiente formato 256.36 (9999999999.9999) |
|   FECHAS           |  Lista de objetos      |  Fechas de entrega asociadas a la venta |       No      | Cualquiera que cumpla los requisitos del objeto de la tabla de Parámetros de la fecha de entrega |

#### Parámetros de la fecha de entrega
| Nombre del parámetro | Tipo de dato | Descripción del parámetro | Obligatorio | Posibles valores |
| -------------------- | ------------ | ------------------------ | ----------- | -----------       |
|   FECHAENTREGA       |  cadena      |  Fecha de la entrega correspondiente a la línea de la venta  |   Sí    | Ha de ser una string con el formato YYYYMMDDHHmmSS |
|   UNIDADES           |  numérico    |    Unidades de la entrega  |    Sí       | Números positivos enteros |
|   PRECIO           |  numérico    |    Precio de la entrega  |    Sí       | Valores numéricos positivos. |

### Encabezados de la solicitud

| Nombre del encabezado | Descripción del encabezado | Obligatorio |
| --------------------- | -------------------------- | ----------- |
|     Content-Type      |  Tipo de contenido de la solicitud   |    Sí  |

### Cuerpo de la solicitud

Formato del cuerpo de la solicitud: application/json

Descripción del cuerpo de la solicitud:
```json
{
	"CODIGOVENTA": "NÚMERO VENTA",
	"FECHACREACION": "YYYYMMDDHHmmSS",
	"REFERENCIACLIENTE": "CÓDIGO_CLIENTE",
	"NOMBRECLIENTE": "CLIENTE",
	"LINEAS": [{
		"PRODUCTO": "CÓDIGO PRODUCTO",
		"UNIDADES": 50,
		"VERSIONPRODUCTO": "VERSIÓN DEL PRODUCTO",
		"PRECIO": 125.25, 
		"FECHAS": [{
			"FECHAENTREGA": "YYYYMMDDHHmmSS",
			"UNIDADES": 50,
          	"PRECIO": 125.25
          }]	
    }]
}
```

### Parámetros de la respuesta

| Nombre del parámetro | Tipo de dato | Descripción del parámetro |Formato|
| -------------------- | ------------ | ------------------------ | ------------------------ |
|        ErrorContent              |      JSON        |       Json con la descripción del resultado de la operación                   | <span style="color:blue">[Formato ErrorContent](https://docs.ctneat.com/link/64#bkmrk-elementos-de-errorco)</span> |

### Códigos de estado de la respuesta
| Código de estado | Descripción del código de estado | Posibles razones |
| ---------------- | -------------------------------- | ---------------- |
|     200             |            OK                      |     La solicitud fue exitosa             |
|     400             |            Petición errónea        |     	Alguno de los parámetros pasados no es correcto   |
|     500             |            Error interno           |     	Error en el servidor             |
|     401             |            Unauthorized            |     	El usuario no está autenticado             |

###  Ejemplo de consulta
#### URL
`http://ctincoming/CTNEAT/SALEORDER/ADD/6A201F1F5147079FF9CA80DCDBB032AB386905091BC973B53F50E6493EC53868`

#### Objeto de entrada
```json
{
	"CODIGOVENTA": "V-0001",
	"FECHACREACION": "20250410000000",
	"REFERENCIACLIENTE": "SP-098-REF",
	"NOMBRECLIENTE": "CLIENTE",
	"LINEAS": [{
		"PRODUCTO": "PROD_0001",
		"UNIDADES": 100,
		"VERSIONPRODUCTO": "v0",
		"PRECIO": 230.65, 
		"FECHAS": [{
			"FECHAENTREGA": "20250410000000",
			"UNIDADES": 50,
          	"PRECIO": 230.65
        }]	
    }]
}
```
### Ejemplo de respuesta
```json
{ "Success":true, "fault":{ "faultcode":"none", "faultstring":"Sale order has been added", "detail":"Sale order: V-0001 successfully added" } }
```

# Modificar venta

Con esta función, es posible llevar a cabo la modificación de algunos de los parámetros de una venta así como sus productos asociados y sus fechas de entrega.

Hay que tener en cuenta que se podrán añadir nuevas líneas de producto y nuevas fechas de entrega para estas, siemrpe y cuando no se superen las unidades totales del producto a entregar. En cuyo caso, devolverá un error.

En la adición de nuevos productos, no se pueden añadir productos que ya forma parte de la venta, pues el hacer esta acción devolverá un error.

No obstante, es posible modificar los siguientes parámetros:
- Referencia del cliente en la venta.
- Precio del producto en una línea ya existente.
- Añadir o eliminar una línea existente.
- Añadir o eliminar fechas de entrega de una línea existente.
- Añadir nuevas fechas de entrega a una línea existente.

NOTA:
- Se recomienda obtener la venta antes de modificar.
- Se recomienda pasar el objeto principal con TODOS los ítems anidados para evitar perder datos (líneas y fechas de entrega anteriores y nuevas).
- Para eliminar uno de los objetos anidados bastará con que no aparezca en el objeto de la request. Este se creará de nuevo con los ítems que se hayan proporcionado.

IMPORTANTE
- Si el producto introducido es un artículo, se creará una estructura con el nombre PK-CODIGOVENTA-PRODUCTO-1.

### URL
`/CTNEAT/SALEORDER/UPDATE/{tkn}`

### Método HTTP
<span style="background-color: RGB(222,112,10); color: white; font-weight: bold; padding: 8px;">PUT</span>

### Parámetros de la solicitud
#### Parámetros de la venta
| Nombre del parámetro | Tipo de dato | Descripción del parámetro | Obligatorio | Posibles valores |
| -------------------- | ------------ | ------------------------ | ----------- | -----------       |
|   CODIGOVENTA        |  cadena      |    Código de la venta    |       Sí    | Cualquiera previamente generado en el sistema. Este campo no es posible modificarlo.      |
|   REFERENCIACLIENTE  |  cadena      |    Código de la venta para el cliente |       No      | Cualquiera |
|   LINEAS             |  Lista de objetos   |    Líneas asociadas a la venta |       No      | Cualquiera que tenga el formato de la tabla de parámetros de la línea de la venta |

#### Parámetros de la Línea de la venta
| Nombre del parámetro | Tipo de dato | Descripción del parámetro | Obligatorio | Posibles valores |
| -------------------- | ------------ | ------------------------ | ----------- | -----------       |
|   PRODUCTO           |  cadena      |    Código del producto asociado a la venta    |       Sí    | Cualquiera        |
| VERSIONPRODUCTO | cadena | Versión del producto | Sí | La versión correspondiente o v0 que es la que se añade por defecto en todos los productos del sistema |
|   UNIDADES           |  numérico    |    Unidades necesarias del producto  |    Sí       | Números positivos enteros  |
|   PRECIO             |  numérico    |   Precio de la línea     |     Sí    | Cualquiera que no sea negativo con formato 256.36 (9999999999.9999) |
|   FECHAS           |  Lista de objetos      |  Fechas de entrega asociadas a la venta |       No      | Cualquiera que cumpla los requisitos del objeto de la tabla de Parámetros de la fecha de entrega |

#### Parámetros de la fecha de entrega
| Nombre del parámetro | Tipo de dato | Descripción del parámetro | Obligatorio | Posibles valores |
| -------------------- | ------------ | ------------------------ | ----------- | -----------       |
|   FECHAENTREGA       |  cadena      |  Fecha de la fecha de entrega  |   Sí    | Ha de ser una string con el formato YYYYMMDDHHmmSS |
|   UNIDADES           |  numérico    |    Unidades de la fecha de entrega  |    Sí       | Números positivos enteros |
|   PRECIO             |  numérico    |   Precio de la fecha de entrega     |     Sí    | Cualquiera que no sea negativo con formato 256.36 (9999999999.9999) |

### Encabezados de la solicitud

| Nombre del encabezado | Descripción del encabezado | Obligatorio |
| --------------------- | -------------------------- | ----------- |
|     Content-Type      |  Tipo de contenido de la solicitud   |    Sí  |

### Cuerpo de la solicitud

Formato del cuerpo de la solicitud: application/json

Descripción del cuerpo de la solicitud:
```json
{
	"CODIGOVENTA": "NÚMERO VENTA",
	"REFERENCIACLIENTE": "CÓDIGO_CLIENTE",
	"LINEAS": [{
    	"PRODUCTO": "CÓDIGO PRODUCTO",
        "VERSIONPRODUCTO": "VERSIÓN DEL PRODUCTO",
		"UNIDADES": 1000,
		"PRECIO": 125.25, 
		"FECHAS": [
          {
        	"FECHAENTREGA": "YYYYMMDDHHmmSS",
          	"UNIDADES": 50,
            "PRECIO": 25.25, 
          },
          {
        	"FECHAENTREGA": "YYYYMMDDHHmmSS",
          	"UNIDADES": 40,
            "PRECIO": 100
          }
        ]	
    }]
}
```

### Parámetros de la respuesta

| Nombre del parámetro | Tipo de dato | Descripción del parámetro |Formato|
| -------------------- | ------------ | ------------------------ | ------------------------ |
|        ErrorContent              |      JSON        |       Json con la descripción del resultado de la operación                   | <span style="color:blue">[Formato ErrorContent](https://docs.ctneat.com/link/64#bkmrk-elementos-de-errorco)</span> |

### Códigos de estado de la respuesta
| Código de estado | Descripción del código de estado | Posibles razones |
| ---------------- | -------------------------------- | ---------------- |
|     200             |            OK                      |     La solicitud fue exitosa             |
|     400             |            Petición errónea        |     	Alguno de los parámetros pasados no es correcto   |
|     500             |            Error interno           |     	Error en el servidor             |
|     401             |            Unauthorized            |     	El usuario no está autenticado             |

###  Ejemplo de consulta
#### URL
`http://ctincoming/CTNEAT/SALEORDER/UPDATE/6A201F1F5147079FF9CA80DCDBB032AB386905091BC973B53F50E6493EC53868`

#### Objeto de entrada
```json
{
	"CODIGOVENTA": "V-0001",
	"REFERENCIACLIENTE": "SP-098-REF",
	"LINEAS": [{
		"PRODUCTO": "PROD_0001",
        "VERSIONPRODUCTO": "v1",
		"UNIDADES": 100,
		"PRECIO": 230.65, 
		"FECHAS": [
          {
        	"FECHAENTREGA": "20260120030325",
          	"UNIDADES": 50
          },
          {
        	"FECHAENTREGA": "20260120030325",
          	"UNIDADES": 50
          }
        ]	
	}]
}
```
### Ejemplo de respuesta
```json
{ "Success":true, "fault":{ "faultcode":"none", "faultstring":"Sale order has been modified", "detail":"Sale order: V-0001 successfully updated" } }
```

# Eliminar una venta

Con esta función, es posible eliminar una venta y todas sus asociaciones a productos o fechas de entrega.
Este proceso es irreversible, por lo que, si se elimina una venta no habrá forma de recuperarla.

### URL
`/CTNEAT/SALEORDER/DELETE/{tkn}`

### Método HTTP
<span style="background-color: RGB(234,2,2); color: white; font-weight: bold; padding: 8px;">DELETE</span>

### Parámetros de la solicitud
#### Parámetros de la venta
| Nombre del parámetro | Tipo de dato | Descripción del parámetro | Obligatorio | Posibles valores |
| -------------------- | ------------ | ------------------------ | ----------- | -----------       |
|   CODIGOVENTA        |  cadena      |    Código de la venta    |       Sí    | Cualquiera previamente generado en el sistema. |

### Encabezados de la solicitud

| Nombre del encabezado | Descripción del encabezado | Obligatorio |
| --------------------- | -------------------------- | ----------- |
|     Content-Type      |  Tipo de contenido de la solicitud   |    Sí  |

### Cuerpo de la solicitud
Esta llamada no tiene cuerpo de solicitud, solo una query añadida en la URL.

### Parámetros de la respuesta
| Nombre del parámetro | Tipo de dato | Descripción del parámetro |Formato|
| -------------------- | ------------ | ------------------------ | ------------------------ |
|        ErrorContent              |      JSON        |       Json con la descripción del resultado de la operación                   | <span style="color:blue">[Formato ErrorContent](https://docs.ctneat.com/link/64#bkmrk-elementos-de-errorco)</span> |

### Códigos de estado de la respuesta
| Código de estado | Descripción del código de estado | Posibles razones |
| ---------------- | -------------------------------- | ---------------- |
|     200             |            OK                      |     La solicitud fue exitosa             |
|     400             |            Petición errónea        |     	Alguno de los parámetros pasados no es correcto   |
|     500             |            Error interno           |     	Error en el servidor             |
|     401             |            Unauthorized            |     	El usuario no está autenticado             |

###  Ejemplo de consulta
#### URL
`http://ctincoming/CTNEAT/SALEORDER/DELETE/6A201F1F5147079FF9CA80DCDBB032AB386905091BC973B53F50E6493EC53868?V0001`

### Ejemplo de respuesta
```json
{ "Success":true, "fault":{ "faultcode":"none", "faultstring":"Sale order has been deleted", "detail":"Sale order: V0001 successfully deleted" } }
```

# Buscar ventas

Con esta función, se tiene la capacidad de leer las ventas que han sido registrados en el sistema. 
Es importante destacar que se puede proporcionar el nombre de una en concreto a través de un parámetro de URL query así como una fecha de creación de esta.
En caso de no especificar estos parámetro, se llevará a cabo la lectura de todos las ventas del sistema.
Si la fecha se introduce en el formato no deseado, se mostrarán todas las fechas.

### URL
`/CTNEAT/SALEORDER/READ/{tkn}`
### Método HTTP

<span style="background-color: RGB(49,213,254); color: white; font-weight: bold; padding: 8px;">GET</span>


### Parámetros de la solicitud

| Nombre del parámetro | Tipo de dato | Descripción del parámetro | Obligatorio | Posibles valores |
| -------------------- | ------------ | ------------------------ | ----------- | ----------- |
|   CODIGOVENTA               |  cadena      |    Nombre de la venta  |       No      | Cualquiera |
|   FECHACREACION               |  cadena      |    Fecha de creación o lanzamiento del pedido  |       No     | Fechas en formato DD/MM/YYYY |

### Encabezados de la solicitud

| Nombre del encabezado | Descripción del encabezado | Obligatorio |
| --------------------- | -------------------------- | ----------- |

### Cuerpo de la solicitud

No se requiere un cuerpo de solicitud para este método HTTP.

### Parámetros de la respuesta

| Nombre del parámetro | Tipo de dato | Descripción del parámetro |
| -------------------- | ------------ | ------------------------ |
|        Result              |      JSON        |       Json con la descripción del resultado de la operación                   |

##### Elementos de Result
- Result.NRecords: Valor numérico que indica el número de registros en la matriz Result.Data.
- Result.Data: Matriz que contiene uno o más objetos (Cantidad de registrios leídos).
- Result.Data[x].CODIGOVENTA: Nombre de la venta.
- Result.Data[x].NOMBRECLIENTE: Nombre del cliente.
- Result.Data[x].REFERENCIACLIENTE: Referencia de la venta para el cliente.
- Result.Data[x].FECHACREACION: Fecha de creación de la venta.
- Result.Data[x].LINES: Líneas asociadas a la venta
- Result.Data[x].LINES[y].PRODUCTO: Código del producto de la venta.
- Result.Data[x].LINES[y].VERSIONPRODUCTO: Versión del producto.
- Result.Data[x].LINES[y].UNIDADES: Cantidad específica de la línea.
- Result.Data[x].LINES[y].PRECIO: Precio total de la línea.
- Result.Data[x].LINES[y].FECHAS: Listado de fechas de entrega asociadas a una línea de la venta.
- Result.Data[x].LINES[y].FECHAS[t].UNIDADES: Precio de le fecha de entrega.
- Result.Data[x].LINES[y].FECHAS[t].FECHAENTREGA: fecha de entrega de la línea de la venta.
- Result.Data[x].LINES[y].FECHAS[t].PRECIO: Precio de la entrega de la línea de la venta.

### Códigos de estado de la respuesta

| Código de estado | Descripción del código de estado | Posibles razones |
| ---------------- | -------------------------------- | ---------------- |
|     200             |            OK                      |     La solicitud fue exitosa             |
|     400             |            Petición errónea     |     	Alguno de los parámetros pasados no es correcto             |
|     500             |            Error interno      |     	Error en el servidor             |
|     401             |            Unauthorized       |     	El usuario no está autenticado             |

###  Ejemplo de consulta
`http://ctincoming/SALEORDER/READ/693DDFEC2F4BFDDEAF04DD2724984C9B3CA89D553DD8E5B9BB233AD6BB6075F1?CODIGOVENTA=PEDIDO&FECHACREACION=20250302112358`
### Ejemplo de respuesta
```json
{ 
  "NRecords":1, 
  "Data":[ 
    {
        "CODIGOVENTA": "V-0001",
        "FECHACREACION": "24/02/2025",
        "REFERENCIACLIENTE": "SP-098-REF",
        "NOMBRECLIENTE": "CLIENTE",
        "LINEAS": [{
            "PRODUCTO": "PROD_0001",
            "UNIDADES": 100,
            "VERSIONPRODUCTO": "v0",
            "PRECIO": 230.65, 
            "FECHAS": [{
                "FECHAENTREGA": "24/04/2025",
                "UNIDADES": 50,
                "PRECIO": 10
            }]	
        }]
    } 
  ] 
}
```