Ir al contenido

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.

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.

LlamadaPermiso
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}/discountVentas - 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}/userVentas - Tickets → Modificar vendedor
POST /invoiceVentas - Tickets → Crear
POST /invoice/{TicketGID}/resendVentas - 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}/cancelVentas - Tickets → Anular factura por diferencia
Ventas - Tickets → Anular factura por sustitución
POST /invoice/{id}/detail/advanceVentas - Tickets → Añadir un anticipo
PUT /client/{clientID}/voucher/{voucherID}Ventas - Bonos → Editar
  • 1POST /invoice?clientID={id}&clinicID={n}
    → 201 {"TicketGID": 128}
    Sustituye la query ClientID / ClinicID del cmd 19
  • 2POST /invoice/{TicketGID}/promotioncode/{code}
    Solo si hay código. En V2 no se valida: cualquier código se acepta con 200.
    ShoppingCart_PromoCode
  • 3POST /invoice/{TicketGID}/detail/product/{productID}
    Una vez por línea, con {"ProductUnits": n, "ProductUserID": u} → {"TicketID": 642}
    ShoppingCart_X_Id
  • 3bPATCH /invoice/{TicketGID}/detail/{TicketID}
    Precio manual: {"TicketTotalAmount": p}, precio unitario con IVA incluido
    ShoppingCart_X_Price
  • 3cPOST /invoice/{TicketGID}/detail/{TicketID}/discount
    DiscountType es obligatorio: P porcentaje, V valor final de la línea, D id de un descuento predefinido
    ShoppingCart_X_Disc, _Disc_Acc
  • 4GET /invoice/{TicketGID}
    Lee el total a pagar antes de registrar ningún pago
    Sin equivalente en V1
  • 5POST /invoice/{TicketGID}/payment/{paymethodID}
    Una vez por línea de pago. TicketPAmount es obligatorio, con punto decimal. En efectivo, también TicketPCashGiven.
    ShoppingCart_PayX_*
  • 6PATCH /invoice/{TicketGID}
    Cierra el ticket, llevando {"TicketGFWA_Ref": "…"}
    El cierre del ticket + ShoppingCart_Ref
  • 7GET /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
API V1 — una llamada
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>
API V2 — 1. Crea el ticket
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}
2. Código promocional (solo si lo hay)
curl --location --request POST 'https://api.flowww.net/v2/invoice/128/promotioncode/SUMMER25?clinicID=1' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Length: 0'
3. Añade la línea
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}
3b. Fija el precio a mano (precio unitario, IVA incluido)
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}'
4. Lee el total a pagar
curl --location 'https://api.flowww.net/v2/invoice/128?clinicID=1' \
--header 'Authorization: Bearer <api_key>'
5. Registra el pago (forma 5 de V1 = efectivo → paymethodID 1 de V2 = Efectivo)
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}'
6. Cierra el ticket, llevando la referencia externa
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"}'
7. Confirma
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.

TemaAPI V1API V2
AtomicidadTodo 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ínicaSe 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íneaNinguno.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 ventaEl usuario del login de V1.El usuario del ticket (por defecto el de API). Cámbialo con PATCH /invoice/{TicketGID}/user si hace falta.
ProductosSe 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íneaSiempre 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 promocionalSe 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 pagoUn 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.
CierreDirecto; 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 respuestaEl 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ónEnviaba 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 fusionadosUn id antiguo se traducía al cliente superviviente.No se traduce: la llamada falla. Ver 4.7.

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ínicaPasoQué obtienesQué hacer
Campos del cliente obligatorios para crear un ticket (documento, dirección o fecha de nacimiento, por ejemplo)1400 {"message":"The client is missing required fields: …","errorCode":"502"} con la lista de camposCompleta 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 ventas1400 errorCode 50La 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 cerrar1400 errorCode 142La clínica tiene que cerrarlas.
Cliente pendiente de regularizar (protocolos obligatorios)1400 errorCode 145Completa el cliente en la aplicación.
Contraseña de descuentos por usuario3c403 errorCode 206Con 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 umbral3c403 errorCode 206El 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 combinar3c400 errorCode 507 / 531 / 533533: la línea ya tiene una promoción avanzada — envía DiscountAccumulated: -1.
Límite legal de pagos en efectivo del país5400 errorCode 555Reparte el importe en otra forma de pago.
Citas del día pendientes de validar6400 errorCode 586Valida 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)6Se cierra igual, como factura ordinariaLa 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 bonos6400 errorCode 616Que la clínica cambie la regla.
Stock con trazabilidad3 / 6400 errorCode 669 / 656Los productos que necesitan lote o caducidad no se pueden vender por API.
Campos del cliente obligatorios para cerrar un ticket6400 errorCode 280Completa el cliente y vuelve a cerrar.
Caja de la fecha del ticket cerrada (el ticket se creó un día anterior)6409 errorCode 739Crea y cierra el ticket el mismo día.

Además de las respuestas comunes (401, 403, 429, 5xx — ver 4.4), cada paso puede responder:

PasoRespuestaQué significaQué queda
1 Crear400 495El cliente no existe (o se fusionó).No se crea nada.
1 Crear400 502 / 50 / 142 / 145Ver Ajustes.No se crea nada.
3 Añadir línea400 717Producto 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ínea400 520Las unidades deben ser mayores que 0.El ticket no cambia.
3 Añadir línea400 46No se pudo añadir la línea (ticket cerrado o de otra clínica).El ticket no cambia.
3b Precio400 invalid-paramsPrecio negativo o línea no encontrada.La línea no cambia.
3c Descuento400 190Lí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 Descuento403 206El 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 Pago400 (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 Pago400 48Id de forma de pago desconocido, o el ticket está cerrado o es de otra clínica.No se añade nada.
5 Pago400 173 / 174Bono regalo no encontrado / caducado.No se añade nada.
5 Pago400 465Efectivo entregado (TicketPCashGiven) inferior al importe.No se añade nada.
5 Pago400 489El anticipo ya se ha usado, o su saldo restante es inferior al importe.No se añade nada.
5 Pago400 555Límite de efectivo, ver Ajustes.No se añade nada.
6 Cerrar409 49Los pagos no suman el total, o el ticket ya está cerrado.Ticket abierto (o ya cerrado).
6 Cerrar409 739Caja de la fecha del ticket cerrada.Ticket abierto.
6 Cerrar409 456El 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 Cerrar503 invoice-not-closedEl total supera el límite de la factura simplificada y no se ha podido emitir la factura ordinaria. Vuelve a intentarlo.Ticket abierto.
6 Cerrar400 586 / 616 / 656 / 280Ver Ajustes.Ticket abierto.
6 Cerrar400 (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).

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.

Abandonar una venta
# 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 TicketPID con GET /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.

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 V1paymethodID de V2Notas
0 PayPal8 PayPal—
1 Tarjeta de crédito/débito (Visa/MC)7 VISA/MC—
2 Pago aplazado3 Pago aplazadoFecha de vencimiento: ShoppingCart_PayX_Settlement → TicketPSettlement (dd/MM/yyyy).
3 Cheque4 ChequeLos 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 + Paymentbank5 Tarjeta de débito + TicketPBankIDEl banco pasa de ShoppingCart_PayX_Paymentbank a TicketPBankID.
5 Efectivo1 EfectivoLa V2 exige TicketPCashGiven, el importe entregado.
6 Puntos9 PuntosFalla si el cliente no tiene puntos suficientes.
—2, 6, 10, 11También disponibles: tarjeta de crédito (2), bono regalo (6, TicketPGiftVoucherCode), domiciliación (10, TicketPClientCCCID, TicketPClientCCCBIC) y anticipos (11, TicketPAdvanceID).
Parámetro V1API V2Notas
ShoppingCart_RefTicketGFWA_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_PromoCodePOST /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_PriceTicketTotalAmount en PATCH …/detail/{TicketID}Precio unitario, IVA incluido.
ShoppingCart_X_DiscDiscountAmount + DiscountType: "P"P = porcentaje, V = valor final de la línea, D = id de un descuento predefinido. DiscountType es obligatorio.
ShoppingCart_X_Disc_AccDiscountAccumulatedLa 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_AdvanceAdvanceVAT en POST /invoice/{id}/detail/advanceLos 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.