Comando 19 — Crear una ventamultipaso
Este es el cambio más grande de toda la migración. La V1 montaba el ticket, sus líneas y sus pagos en un único envío de formulario, con sus propias reglas simplificadas. La V2 lo monta como lo hace la aplicación — crear el ticket, añadir líneas, aplicar descuentos y promociones, registrar pagos, cerrarlo — y por el camino aplica todas las reglas que la clínica tenga configuradas. Léete la sección entera antes de portarla: el camino feliz es corto, pero casi todo el trabajo está en gestionar lo que puede fallar en cada paso.
Permisos
Sección titulada «Permisos»La V2 comprueba un permiso de aplicación en cada llamada — la V1 no comprobaba ninguno — y una llamada a la que le falte responde 400 con errorCode 15, el mismo estado que un payload inválido (ver 4.4). Dáselos al usuario de API antes de portar el comando; los nombres son los del árbol de permisos de flowww.
| Llamada | Permiso |
|---|---|
POST /invoice/{TicketGID}/promotioncode/{code} | Ventas - Tickets → Utilizar código de promoción |
POST /invoice/{TicketGID}/detail/product/{productID} | Ventas - Tickets → Añadir producto |
PATCH /invoice/{TicketGID}/detail/{TicketID} | Ventas - Tickets → Editar precio PVP |
POST /invoice/{TicketGID}/detail/{TicketID}/discount | Ventas - Tickets → Aplicar descuento por valor final Ventas - Tickets → Aplicar descuento porcentual Ventas - Tickets → Aplicar descuento catálogo |
GET /invoice/{TicketGID} | Ventas - Tickets → Editar |
POST /invoice/{TicketGID}/payment/{paymethodID} | Ventas - Tickets → Añadir pago |
PATCH /invoice/{TicketGID} | Ventas - Tickets → Cerrar |
PATCH /invoice/{TicketGID}/user | Ventas - Tickets → Modificar vendedor |
POST /invoice | Ventas - Tickets → Crear |
POST /invoice/{TicketGID}/resend | Ventas - Tickets → Ticket - Reenviar Ticket |
PATCH /client/{clientID} | Clientes → Clientes - Guardar |
DELETE /invoice/{TicketGID} | Ventas - Tickets → Borrar ticket |
DELETE /invoice/{TicketGID}/paymethod/{TicketPID} | Ventas - Tickets → Borrar pago |
DELETE /invoice/{TicketGID}/detail/{TicketID} | Ventas - Tickets → Borrar línea |
POST /invoice/{TicketGID}/cancel | Ventas - Tickets → Anular factura por diferencia Ventas - Tickets → Anular factura por sustitución |
POST /invoice/{id}/detail/advance | Ventas - Tickets → Añadir un anticipo |
PUT /client/{clientID}/voucher/{voucherID} | Ventas - Bonos → Editar |
El flujo
Sección titulada «El flujo»- 1
POST /invoice?clientID={id}&clinicID={n}
→201 {"TicketGID": 128}
Sustituye la queryClientID/ClinicIDdel cmd 19 - 2
POST /invoice/{TicketGID}/promotioncode/{code}
Solo si hay código. En V2 no se valida: cualquier código se acepta con 200.
ShoppingCart_PromoCode - 3
POST /invoice/{TicketGID}/detail/product/{productID}
Una vez por línea, con{"ProductUnits": n, "ProductUserID": u}→{"TicketID": 642}
ShoppingCart_X_Id - 3b
PATCH /invoice/{TicketGID}/detail/{TicketID}
Precio manual:{"TicketTotalAmount": p}, precio unitario con IVA incluido
ShoppingCart_X_Price - 3c
POST /invoice/{TicketGID}/detail/{TicketID}/discount
DiscountTypees obligatorio:Pporcentaje,Vvalor final de la línea,Did de un descuento predefinido
ShoppingCart_X_Disc,_Disc_Acc - 4
GET /invoice/{TicketGID}
Lee el total a pagar antes de registrar ningún pago
Sin equivalente en V1 - 5
POST /invoice/{TicketGID}/payment/{paymethodID}
Una vez por línea de pago.TicketPAmountes obligatorio, con punto decimal. En efectivo, tambiénTicketPCashGiven.
ShoppingCart_PayX_* - 6
PATCH /invoice/{TicketGID}
Cierra el ticket, llevando{"TicketGFWA_Ref": "…"}
El cierre del ticket +ShoppingCart_Ref - 7
GET /invoice/{TicketGID}
Comprueba que no queda nada pendiente y lee los ids de pago. Si está cerrado se ve en la lista de tickets:GET /invoice→TicketGClosed: 1
Sin equivalente en V1
La misma venta, antes y después
Sección titulada «La misma venta, antes y después»curl --location 'https://euapi.flowww.net/v1/fwa_external_get.asp?cmd=19&doctor=USER_LOGIN&pass=USER_PASS&country=ES&key=SYSTEM_KEY&ClinicID=1&ClientID=93271' \ --data-urlencode 'ShoppingCart_PromoCode=' \ --data-urlencode 'ShoppingCart_Ref=WEB-8841' \ --data-urlencode 'ShoppingCart_1_Id=2983' \ --data-urlencode 'ShoppingCart_1_Price=1000' \ --data-urlencode 'ShoppingCart_Pay1_Amount=1000' \ --data-urlencode 'ShoppingCart_Pay1_Paymentmethod=5'
<Cmd19><Result>1</Result> <Ticket><TicketGID>128</TicketGID>…</Ticket></Cmd19>curl --location --request POST 'https://api.flowww.net/v2/invoice?clientID=93271&clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Length: 0'
→ 201 {"TicketGID": 128}curl --location --request POST 'https://api.flowww.net/v2/invoice/128/promotioncode/SUMMER25?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Length: 0'curl --location 'https://api.flowww.net/v2/invoice/128/detail/product/2983?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{"ProductUnits": 1}'
→ {"TicketID": 642}curl --location --request PATCH 'https://api.flowww.net/v2/invoice/128/detail/642?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{"TicketTotalAmount": 1000.00}'curl --location 'https://api.flowww.net/v2/invoice/128?clinicID=1' \ --header 'Authorization: Bearer <api_key>'curl --location 'https://api.flowww.net/v2/invoice/128/payment/1?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{"TicketPAmount": 1000.00, "TicketPCashGiven": 1000.00}'curl --location --request PATCH 'https://api.flowww.net/v2/invoice/128?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{"TicketGFWA_Ref": "WEB-8841"}'curl --location 'https://api.flowww.net/v2/invoice/128?clinicID=1' \ --header 'Authorization: Bearer <api_key>'Envía siempre el mismo clinicID en todas las llamadas de la venta.
Qué cambia respecto a V1
Sección titulada «Qué cambia respecto a V1»| Tema | API V1 | API V2 |
|---|---|---|
| Atomicidad | Todo o nada: ante cualquier fallo, la V1 eliminaba los pagos, las líneas y el ticket. | Cada llamada se guarda por su cuenta. Un fallo a medias deja un ticket abierto — ver Limpiar tras un fallo. |
| Reglas de la clínica | Se saltaba casi todas (campos obligatorios del cliente, reglas de caja, límites de pago, comprobaciones al cerrar…). | Las aplica todas. Ver Ajustes que pueden bloquear la venta. |
| Profesional de la línea | Ninguno. | El que envíes en ProductUserID; si lo omites, el usuario de API. Mándalo si tus comisiones o estadísticas dependen de ello. |
| Quién cierra la venta | El usuario del login de V1. | El usuario del ticket (por defecto el de API). Cámbialo con PATCH /invoice/{TicketGID}/user si hace falta. |
| Productos | Se podían vender productos deshabilitados, y el id del producto se traducía al catálogo propio de la clínica. | El producto tiene que estar habilitado y pertenecer a la tarifa de la clínica desde la que llamas (errorCode 717 si no). Los productos con lote o caducidad (trazabilidad) no se pueden vender por API. |
| Unidades por línea | Siempre 1. | ProductUnits, mayor que 0. |
| Precio manual | _Price era el precio unitario con IVA; el descuento automático se seguía aplicando salvo que enviaras _Disc. | PATCH …/detail/{TicketID} con el precio unitario, IVA incluido. Cambia solo el precio: los descuentos y promociones que ya tenga la línea se mantienen. |
| Código promocional | Se validaba: un código desconocido o no aplicable era un error. | No se valida: cualquier código se acepta con 200. Comprueba el descuento en el ticket (paso 4) si el código importa. |
| Importe del pago | Un pago único podía omitir el importe (se usaba el total). | TicketPAmount es obligatorio en cada pago, con punto decimal. Lee antes el total (paso 4). Algunas formas piden más campos: efectivo TicketPCashGiven; cheque TicketPCheckNumber y TicketPSettlement; domiciliación TicketPSettlement, TicketPClientCCCID y TicketPClientCCCBIC. |
| Cierre | Directo; se saltaban varias comprobaciones de cierre de la aplicación. | Se aplican las comprobaciones de cierre de la aplicación (citas del día pendientes, límite de factura simplificada, trazabilidad de stock…). |
| Cuerpos de respuesta | El ticket entero. | El pago y el cierre responden 200 con el cuerpo vacío. Lee el ticket (paso 7) para obtener el número de factura, los ids de pago y el estado final. |
| Correo de confirmación | Enviaba el correo de venta de la tienda online si la clínica lo tenía activado. | El correo de venta de la tienda online ya no se envía. El del ticket al cerrar sí se envía, en las dos versiones, si la clínica lo tiene activado. No hay parámetro para forzarlo ni en POST /invoice ni en el PATCH de cierre: para mandar un ticket que no haya salido, llama a POST /invoice/{TicketGID}/resend (permiso Sales · Tickets · Ticket · Resend Ticket). |
| Clientes fusionados | Un id antiguo se traducía al cliente superviviente. | No se traduce: la llamada falla. Ver 4.7. |
Ajustes que pueden bloquear la venta
Sección titulada «Ajustes que pueden bloquear la venta»Estas reglas vienen de la configuración de la clínica. La V1 ignoraba casi todas, así que una integración que llevaba años funcionando puede empezar a fallar en la primera llamada a V2. Repásalas con cada cliente antes de cambiar.
| Regla configurada en la clínica | Paso | Qué obtienes | Qué hacer |
|---|---|---|---|
| Campos del cliente obligatorios para crear un ticket (documento, dirección o fecha de nacimiento, por ejemplo) | 1 | 400 {"message":"The client is missing required fields: …","errorCode":"502"} con la lista de campos | Completa el cliente con PATCH /client/{clientID} antes de crear el ticket, o que la clínica relaje la regla. |
| Caja del día ya cerrada, cuando la clínica no permite reabrirla para nuevas ventas | 1 | 400 errorCode 50 | La clínica tiene que reabrir la caja del día, o permitir cajas parciales. La V1 colgaba la venta de la caja cerrada igualmente. |
| Cajas de días anteriores sin cerrar | 1 | 400 errorCode 142 | La clínica tiene que cerrarlas. |
| Cliente pendiente de regularizar (protocolos obligatorios) | 1 | 400 errorCode 145 | Completa el cliente en la aplicación. |
| Contraseña de descuentos por usuario | 3c | 403 errorCode 206 | Con esta regla activa ningún descuento pasa por API: pide la contraseña del usuario, que la API no envía. Que la clínica la desactive. |
| Autorización de descuentos por encima de un umbral | 3c | 403 errorCode 206 | El descuento no se aplica. Repite la llamada añadiendo al cuerpo "GlobalPassword" con la contraseña global de descuentos de la clínica, o mantén el descuento por debajo del umbral. |
| Descuentos que no se pueden combinar | 3c | 400 errorCode 507 / 531 / 533 | 533: la línea ya tiene una promoción avanzada — envía DiscountAccumulated: -1. |
| Límite legal de pagos en efectivo del país | 5 | 400 errorCode 555 | Reparte el importe en otra forma de pago. |
| Citas del día pendientes de validar | 6 | 400 errorCode 586 | Valida las citas del día del cliente, o que la clínica cambie la regla. |
| Importe máximo de una factura simplificada (el total supera el límite del país) | 6 | Se cierra igual, como factura ordinaria | La API confirma la factura ordinaria por ti y responde con el resultado real. Si esa confirmación falla: 503 invoice-not-closed, y el ticket se queda abierto — reintenta. |
| Confirmación automática de packs y bonos | 6 | 400 errorCode 616 | Que la clínica cambie la regla. |
| Stock con trazabilidad | 3 / 6 | 400 errorCode 669 / 656 | Los productos que necesitan lote o caducidad no se pueden vender por API. |
| Campos del cliente obligatorios para cerrar un ticket | 6 | 400 errorCode 280 | Completa el cliente y vuelve a cerrar. |
| Caja de la fecha del ticket cerrada (el ticket se creó un día anterior) | 6 | 409 errorCode 739 | Crea y cierra el ticket el mismo día. |
Errores, paso a paso
Sección titulada «Errores, paso a paso»Además de las respuestas comunes (401, 403, 429, 5xx — ver 4.4), cada paso puede responder:
| Paso | Respuesta | Qué significa | Qué queda |
|---|---|---|---|
| 1 Crear | 400 495 | El cliente no existe (o se fusionó). | No se crea nada. |
| 1 Crear | 400 502 / 50 / 142 / 145 | Ver Ajustes. | No se crea nada. |
| 3 Añadir línea | 400 717 | Producto deshabilitado, de un tipo que no se puede vender, o fuera de la tarifa de la clínica. | El ticket no cambia. |
| 3 Añadir línea | 400 520 | Las unidades deben ser mayores que 0. | El ticket no cambia. |
| 3 Añadir línea | 400 46 | No se pudo añadir la línea (ticket cerrado o de otra clínica). | El ticket no cambia. |
| 3b Precio | 400 invalid-params | Precio negativo o línea no encontrada. | La línea no cambia. |
| 3c Descuento | 400 190 | Línea o ticket no encontrados, ticket cerrado, precio 0, línea pagada con bono, o importe superior al total de la línea. | La línea no cambia. |
| 3c Descuento | 403 206 | El descuento necesita la autorización de la clínica (ver Ajustes). El mensaje de error explica cómo enviarla. | La línea no cambia. |
| 5 Pago | 400 (validación) | Falta TicketPAmount, o no es un número con punto decimal; fechas que no son dd/MM/yyyy. | No se añade nada. |
| 5 Pago | 400 48 | Id de forma de pago desconocido, o el ticket está cerrado o es de otra clínica. | No se añade nada. |
| 5 Pago | 400 173 / 174 | Bono regalo no encontrado / caducado. | No se añade nada. |
| 5 Pago | 400 465 | Efectivo entregado (TicketPCashGiven) inferior al importe. | No se añade nada. |
| 5 Pago | 400 489 | El anticipo ya se ha usado, o su saldo restante es inferior al importe. | No se añade nada. |
| 5 Pago | 400 555 | Límite de efectivo, ver Ajustes. | No se añade nada. |
| 6 Cerrar | 409 49 | Los pagos no suman el total, o el ticket ya está cerrado. | Ticket abierto (o ya cerrado). |
| 6 Cerrar | 409 739 | Caja de la fecha del ticket cerrada. | Ticket abierto. |
| 6 Cerrar | 409 456 | El total supera el límite de la factura simplificada y los datos de facturación del cliente están incompletos para la factura ordinaria. | Ticket abierto. |
| 6 Cerrar | 503 invoice-not-closed | El total supera el límite de la factura simplificada y no se ha podido emitir la factura ordinaria. Vuelve a intentarlo. | Ticket abierto. |
| 6 Cerrar | 400 586 / 616 / 656 / 280 | Ver Ajustes. | Ticket abierto. |
| 6 Cerrar | 400 (facturación electrónica) | El servicio de facturación electrónica del país ha rechazado la factura. | El ticket puede estar ya cerrado. No repitas el cierre: léelo (paso 7). |
Limpiar tras un fallo
Sección titulada «Limpiar tras un fallo»La V1 era todo o nada: ante cualquier fallo eliminaba los pagos, las líneas y el ticket. En V2 cada llamada se guarda por su cuenta, así que un fallo a medias deja un ticket abierto — y un ticket abierto impide cerrar la caja del día.
DELETE /invoice/{TicketGID} solo elimina un ticket abierto que ya no tenga pagos ni líneas. Lee el ticket con GET /invoice/{TicketGID}, elimina primero cada pago con DELETE /invoice/{TicketGID}/paymethod/{TicketPID} y después cada línea con DELETE /invoice/{TicketGID}/detail/{TicketID}. Por último, elimina el ticket vacío. Si aún tiene pagos o líneas, el borrado del ticket falla.
Un 409 con errorCode 376 indica que aún quedan pagos o líneas, o que el ticket ya está cerrado. Si devuelve 514 (anticipos o pagos aplazados vinculados) o 574 (propinas), la limpieza automática no basta: revisa el ticket en la aplicación.
Un 404 con errorCode 51 indica que el ticket no existe o ya no es el último de la clínica (se creó otro después), así que no se puede eliminar. Quítale los pagos y las líneas y ciérralo vacío con PATCH /invoice/{TicketGID}, para que no bloquee la caja.
# Obtén PAYMENT_ID (TicketPID) y los TicketID con GET /invoice/128.curl --location --request DELETE 'https://api.flowww.net/v2/invoice/128/paymethod/PAYMENT_ID?clinicID=1' \ --header 'Authorization: Bearer <api_key>'curl --location --request DELETE 'https://api.flowww.net/v2/invoice/128/detail/642?clinicID=1' \ --header 'Authorization: Bearer <api_key>'curl --location --request DELETE 'https://api.flowww.net/v2/invoice/128?clinicID=1' \ --header 'Authorization: Bearer <api_key>'Ten en cuenta:
- No es
POST /invoice/{TicketGID}/cancel. El cancel es para tickets cerrados y emite un abono, que es un movimiento contable. El delete es para un ticket abierto, que nunca llegó a ser una venta. - Para quitar solo un producto o un pago y seguir con la venta, usa esas mismas llamadas de detalle. Lee el
TicketPIDconGET /invoice/{TicketGID}.
La mejor limpieza sigue siendo no necesitarla: comprueba los campos obligatorios del cliente y el producto antes del paso 1, y al reintentar termina el mismo ticket en vez de empezar uno nuevo.
Formas de pago
Sección titulada «Formas de pago»La V1 tenía su propia enumeración 0–6 en ShoppingCart_PayX_Paymentmethod. La V2 pone el id de la forma de pago en la ruta de POST /invoice/{TicketGID}/payment/{paymethodID}.
| Valor V1 | paymethodID de V2 | Notas |
|---|---|---|
0 PayPal | 8 PayPal | — |
1 Tarjeta de crédito/débito (Visa/MC) | 7 VISA/MC | — |
2 Pago aplazado | 3 Pago aplazado | Fecha de vencimiento: ShoppingCart_PayX_Settlement → TicketPSettlement (dd/MM/yyyy). |
3 Cheque | 4 Cheque | Los datos del cheque en TicketPCheckNumber. Que el cheque se confirme automáticamente ahora depende del ajuste de la clínica (la V1 lo confirmaba siempre). |
4 Tarjeta de débito + Paymentbank | 5 Tarjeta de débito + TicketPBankID | El banco pasa de ShoppingCart_PayX_Paymentbank a TicketPBankID. |
5 Efectivo | 1 Efectivo | La V2 exige TicketPCashGiven, el importe entregado. |
6 Puntos | 9 Puntos | Falla si el cliente no tiene puntos suficientes. |
| — | 2, 6, 10, 11 | También disponibles: tarjeta de crédito (2), bono regalo (6, TicketPGiftVoucherCode), domiciliación (10, TicketPClientCCCID, TicketPClientCCCBIC) y anticipos (11, TicketPAdvanceID). |
El resto del payload
Sección titulada «El resto del payload»| Parámetro V1 | API V2 | Notas |
|---|---|---|
ShoppingCart_Ref | TicketGFWA_Ref en PATCH /invoice/{id} | Tu número de pedido, guardado con el ticket. Hasta 64 caracteres (uno más largo se descarta). No lo devuelve GET /invoice/{id}. |
ShoppingCart_PromoCode | POST /invoice/{id}/promotioncode/{code} | Sáltate la llamada si no hay código. Aplícalo antes que las líneas. |
ShoppingCart_X_Id | {productID} en la ruta | — |
ShoppingCart_X_Price | TicketTotalAmount en PATCH …/detail/{TicketID} | Precio unitario, IVA incluido. |
ShoppingCart_X_Disc | DiscountAmount + DiscountType: "P" | P = porcentaje, V = valor final de la línea, D = id de un descuento predefinido. DiscountType es obligatorio. |
ShoppingCart_X_Disc_Acc | DiscountAccumulated | La V1 tomaba 0/1. En V2: -1 se acumula al descuento existente, 0/omitido lo sustituye. Obligatorio como -1 cuando la línea ya lleva una promoción avanzada (errorCode 533). |
ShoppingCart_X_VAT_Advance | AdvanceVAT en POST /invoice/{id}/detail/advance | Los anticipos tienen su propia llamada: {"AdvanceAmount": …, "AdvanceVAT": …}. La V1 tomaba el IVA como porcentaje (21); la V2 lo toma como fracción (21 % → 0.21). |
KeepOpened | — | Simplemente no envíes el paso 6. Un ticket sigue abierto hasta que lo cierras. |
ShoppingCart_X_VoucherExpiryDate | — | Hueco: no está disponible mientras montas el ticket. Cambia la caducidad del bono después con PUT /client/{clientID}/voucher/{voucherID}. |
ShoppingCart_X_ExtraID / _Extra | — | Hueco: sin equivalente en la línea de factura. |