POST/api/mod/comercial/{espacio}/cotizar

Cotiza el envío de un pedido

Le das el pedido, la ciudad y el método de pago, y te devuelve el envío, lo que el cliente paga hoy, lo que cobra el mensajero y el total, con un desglose listo para enseñar. Es lo que va a la orden de Facturación.

PERMISOescribe
CRÉDITOSno gasta
AUTENTICACIÓNBearer bth_…

PARÁMETROS

CAMPO	TIPO	REQUERIDO	QUÉ ES
espacio	string	SÍ	El id del espacio (sale en GET /api/companies). Tiene que tener el módulo Comercial.

CUERPO · JSON

CAMPO	TIPO	REQUERIDO	QUÉ ES
ciudad_destino	string	SÍ	Adónde va. Sin importar tildes ni mayúsculas; también vale una dirección que empiece por la ciudad («Bogotá, Calle 10 # 20-30»).
metodo_pago	"contra" \| "transferencia" \| "mixto"	SÍ	contra: paga todo al mensajero. transferencia: paga todo por adelantado. mixto: los productos por transferencia y el envío al mensajero.
lineas	[{ sku, nombre, cantidad, precio_unitario }]	ESTA O SUBTOTAL	El pedido, con los precios de Productos. `cantidad` es entera (por defecto 1). Si la mandas, el subtotal sale de aquí y el peso, de `peso_sku`.
subtotal	string	ESTA O LINEAS	El subtotal de los productos, si no mandas lineas.
peso_kg	string	no	El peso del pedido en kilos. Manda sobre peso_sku y sobre el de fábrica.
envio_gratis	boolean	no	Si un beneficio da envío gratis. Por defecto false.
descuento	string	no	El descuento de los beneficios, en monto. Por defecto 0.

RESPUESTA 200

CAMPO	TIPO	QUÉ ES
metodo_pago · ciudad_destino	string	El método y la ciudad, con el nombre que tiene en tu tabla si se encontró.
zona · rango_peso	string \| null	La zona del destino y el rango de peso de la tabla que se usó.
peso_kg · moneda	string	El peso usado y la moneda.
subtotal	string	El de los productos.
base_envio	string	La tarifa de tu tabla para esa zona y ese peso. 0 con envío gratis.
cargo_fijo · iva_envio	string	Contraentrega bajo el umbral: el cargo fijo. Contraentrega desde el umbral: el IVA del envío. Si no, 0.
comision_recaudo	string	Contraentrega desde el umbral: la comisión de recaudo. Si no, 0.
descuento · envio_gratis	string · boolean	Los que mandaste.
total_envio	string	El envío con ese método. Es el `envio` de la orden en Facturación.
total_a_pagar_hoy	string	Lo que el cliente paga ya: todo en transferencia, los productos menos el descuento en mixto, 0 en contraentrega.
total_mensajero	string	Lo que cobra el mensajero: todo en contraentrega, el envío en mixto, 0 en transferencia.
total_pedido	string	subtotal + total_envio − descuento. Nunca negativo.
lineas[]	{ concepto, monto, tipo }	El desglose listo para enseñar. `tipo`: producto, envio, cargo, iva, comision, beneficio o total.
tarifa_version	string \| null	La versión de la tabla activa. Pásala a la orden con el envío.
degradado · notas	boolean · string[]	`degradado: true`: no hay tarifa para ese destino y el envío no está calculado; `notas` dice por qué. También avisan de un peso estimado o fuera de la tabla.
ciudad_sugerida	string \| null	Si la ciudad no se encontró pero hay una sola muy parecida en tu tabla: pregúntale al cliente si es esa.

ERRORES DE ESTA RUTA · SIEMPRE {"detail": …}

STATUS	CUÁNDO	DETAIL LITERAL
403	El espacio no tiene el módulo Comercial	módulo no habilitado para este espacio.
403	La clave es de solo lectura	Tu cuenta es de solo lectura en este espacio.
422	Falta ciudad_destino, o metodo_pago no es contra, transferencia ni mixto	—
422	Falta un campo obligatorio o uno no es de su tipo (detail es una lista)	—

Y los de cualquier ruta —clave inválida, cuenta no al día, IP, límites—, en Errores, límites y créditos.

CONVIENE SABER

Solo calcula: no guarda nada. Aun así pide una clave escribe, porque es un POST.
Un destino sin tarifa no es un error: responde 200 con degradado: true. No cobres ese envío: confírmalo a mano.
Las cifras van como texto, redondeadas a unidades enteras de la moneda (la mitad, hacia arriba).
Los beneficios no se deciden aquí: evalúalos antes con beneficios y pasa su descuento y su envio_gratis.