Endpoint de creación de documentos comerciales de recepciones de compras

Endpoint de creación de documentos comerciales de recepciones de compras en las tablas cialdoco/cialdocolin

Disponemos de una vista editable que nos permite crear documentos y líneas de documentos, con origen, usable como endpoint de la API. Esta vista es:

cialdocomanrec_v para gestionar documentos de recepción de compras

Campos del Endpoint

Campo	Tipo SQL	Descripción	Valores
SECCIÓN: ORIGEN
`set_document_ori`	`TINYINT`	Cómo asignar doc origen	0: No procede
			1: id_cocabe_ori
			2: soporte_ori / anyo_ori / cod_serie_ori / numero_ori
			3: cod_cuenta_ori / su_documento_ori / [fecha_ori]
`id_cocabe_ori`	`BIGINT`	Doc Id origen
`soporte_ori`	`CHAR(2)`	Tipo origen	PC: Pedido de compra
`anyo_ori`	`SMALLINT`	Año doc origen
`cod_serie_ori`	`CHAR(3)`	Serie doc origen
`numero_ori`	`INT`	Número doc origen
`cod_cuenta_ori`	`CHAR(12)`	Cuenta origen
`su_documento_ori`	`VARCHAR(250)`	Su doc origen	Identificador del pedido de la cuenta
`fecha_ori`	`DATE`	Fecha doc origen
`set_linea_ori`	`TINYINT`	Cómo asignar línea origen	0: No procede
			1: id_coline_ori
			2: linea_ori
			3: cod_articulo_ori / id_maescombarti_ori / cod_und_emb_ori
`id_coline_ori`	`BIGINT`	Línea Id origen
`linea_ori`	`INT`	Línea origen
`estado_ori`	`CHAR(1)`	Estado origen	P: Pendiente
			D: Detenido
			T: Traspasado
`cod_articulo_ori`	`CHAR(30)`	Producto origen
`id_maescombart_ori`	`INT`	Nº Combinación origen
`cantidad_ori`	`DECIMAL`	Cantidad origen
`cod_und_emb_ori`	`CHAR(3)`	Embalaje origen
`cant_emb_ori`	`DECIMAL`	Cant. embalajes origen
`num_lote_ori`	`INT`	Nº Lote origen
`cod_almacen_ori`	`CHAR(3)`	Almacén origen
`cod_ubicacion_ori`	`CHAR(15)`	Ubicación origen
`observaciones_ori`	`TEXT`	Observaciones origen

SECCIÓN: DESTINO
`set_document_des`	`TINYINT`	Cómo asignar doc destino	0: No procede
			1: id_cocabe_des
			2: soporte_des / anyo_des / cod_serie_des / numero_des
			3: cod_cuenta_des / su_documento_des / [fecha_des]
`soporte_des`	`CHAR(2)`	Tipo doc destino	AC: Albarán de compra
			FC: Factura de compra
`id_cocabe_des`	`BIGINT`	Doc Id destino
`anyo_des`	`SMALLINT`	Año destino
`cod_serie_des`	`CHAR(3)`	Serie destino
`numero_des`	`INT`	Número doc destino
`cod_cuenta_des`	`CHAR(12)`	Cuenta destino
`su_documento_des`	`VARCHAR(250)`	Su documento destino
`fecha_des`	`DATE`	Fecha doc destino
`set_linea_des`	`TINYINT`	Cómo asignar línea destino	0: No procede
			1: id_coline_des
			2: linea_des
			3: cod_articulo_des / id_maescombarti_des / cod_und_emb_des / [cod_almacen_des] / [cod_ubicacion_des]
`id_coline_des`	`BIGINT`	Línea Id destino
`linea_des`	`INT`	Línea destino
`estado_des`	`CHAR(1)`	Estado destino	P: Pendiente
			D: Detenido
			T: Traspasado
`cod_articulo_des`	`CHAR(30)`	Referencia Producto destino	Si se omite, se usará el mixed_articulo_des
`id_maescombart_des`	`INT`	Nº Combinación destino
`mixed_articulo_des`	`CHAR(30)`	Identificador de Producto destino	Puede ser cualquiera de los códigos de productos: código principal, código secundario, código de barras de producto, código de barras de producto/embalaje, y código de producto/cuenta
`cantidad_des`	`DECIMAL`	Cantidad destino
`cod_und_emb_des`	`CHAR(3)`	Embalaje destino	Si no se recibe este dato, y el mixed_articulo_des es un código de producto/embalaje, se usará el embalaje de este último
`cant_emb_des`	`DECIMAL`	Cant. embalajes destino	Si se omite, y se encuentra embalaje, se calcula según este último
`num_lote_des`	`INT`	Nº Lote destino	Si se omite, y también se omite el campo lista_lotes_des, y el producto es de lotes, se creará un lote automático
`lista_lotes_des`	`TEXT`	Lista lotes destino	Formato compacto para informar de los lotes que componen las unidades cantidad_des de la forma: Lote1∗Cantidad1∗FechaCaducidad1∗FechaFabricacion1 + Lote2∗Cantidad2∗FechaCaducidad2∗FechaFabricacion2 + ...
`cod_almacen_des`	`CHAR(3)`	Almacén destino	Si se omite, se asigna valor automático
`cod_ubicacion_des`	`CHAR(15)`	Ubicación destino	Si se omite, se asigna valor automático
`observaciones_des`	`TEXT`	Observaciones destino

Usos del Endpoint

Este endpoint admite creaciones (create) y borrados (delete), pero no modificaciones (update).

En las creaciones enviadas al Endpoint se usa el siguiente protocolo:
- pasos en documento origen
- se busca el documento origen según el criterio del campo set_document_ori
- si no se encuentra documento origen, se finaliza retornando error
- se busca la línea del documento origen según el criterio del campo set_linea_ori
- si no se encuentra línea del documento origen, se finaliza retornando error
- pasos en documento destino
- se busca el documento destino según el criterio del campo set_document_des
- si no se encuentra documento destino, se crea
- si se encuentra el documento destino, se actualiza
- se busca la línea del documento destino según el criterio del campo set_linea_des
- si no se encuentra la línea del documento destino, se crea
- si se encuentra la línea del documento destino, se actualiza, pero los campos de cantidad_des y cant_emb_des se acumulan a la línea existente
En los borrados, solo se permiten borrar líneas del documento destino
- se busca la línea destino por el campo id_coline_des
- si no se encuentra la línea destino, se retorna error
- si se encuentra la línea destino, se borra
El Endpoint NO permite gestionar creaciones, modificaciones o borrados del documento origen

Ejemplo de Uso en Creación

Ejemplo de uso del endpoint para crear/actualizar un albarán y crear/actualizar una línea del mismo.

Este ejemplo muestra una configuración recomendada donde se identifica el origen por IDs directos y el destino por referencias de negocio.

1. Configuración del ORIGEN

Se utiliza la identificación por ID interno para asegurar precisión absoluta en la extracción.

Campo	Valor	Observación / Recomendación
`set_document_ori`	1	Recomendado (1 o 2). Usamos 1 por simplicidad.
`id_cocabe_ori`	`xxx`	ID único de la cabecera del documento.
`set_linea_ori`	1	Recomendado (1 o 2). Usamos 1 por simplicidad.
`id_coline_ori`	`xxx`	ID único de la línea del documento.

2. Configuración del DESTINO

Se utiliza la identificación por lógica de negocio para buscar o crear el documento y la línea.

Campo	Valor	Observación / Recomendación
`set_document_des`	3	Recomendado. Busca el documento destino por:
		Cuenta / Su-documento / [Fecha].
`cod_cuenta_des`	`xxx`	Código de la cuenta contable/cliente.
`su_documento_des`	`xxx`	Referencia externa del documento.
`fecha_des`	`xxx`	Fecha del documento destino.
`set_linea_des`	3	Recomendado. Busca la línea (por si ya existe) por:
		Articulo / Combinación / Embalaje / [Almacén] / [Ubicación].
`cod_articulo_des`	`xxx`	Código del producto.
`id_maescombart_des`	`xxx`	ID de la combinación (talla/color/etc).
`mixed_articulo_des`	`xxx`	Referencia mixta del producto.
`cantidad_des`	`xxx`	Cantidad a traspasar/asignar.
`cod_und_emb_des`	`xxx`	Unidad de embalaje.
`cant_emb_des`	`xxx`	Cantidad en formato embalaje.
`num_lote_des`	`xxx`	Número de lote asignado.
`lista_lotes_des`	`xxx`	Listado detallado de lotes (si aplica).
`observaciones_des`	`xxx`	Notas adicionales para la línea de destino.

Tip de implementación: Al usar el valor 3 en los campos set_document_des, estás permitiendo que el sistema sea "inteligente": si el documento ya existe (coincide cuenta y número), añadirá la línea a ese documento en lugar de crear uno nuevo. Si la línea ya existe, incrementará las cantidades y actualizará.

Ejemplo de Uso en Borrado

Ejemplo de uso del endpoint para borrar una línea del documento destino.

Campo	Valor	Observación / Recomendación
`id_coline_des`	`xxx`	ID único de la línea del documento.

Si el id_coline_des no correspondiera a una línea de Albarán de compra, se retornaría error