Autenticación y alcance de la cuenta
Cada conector usa autenticación HTTP Basic con tu clave de API de Fluz:accountIdentifier de Tango, no seleccionan una subcuenta aquí. Si operas varias cuentas, solicita una clave por cuenta.
Valores de estado de la orden
El campostatus en una orden (OrderStatus en InComm) lleva un valor de Fluz, no el de tu proveedor:
Las cadenas de estado de tu proveedor no se trasladan. Una verificación escrita contra un valor del proveedor, por ejemplo
status === "COMPLETE", no coincidirá con COMPLETED. Actualiza cada comparación de estado antes de la migración.Tiempos
Tango Card e InComm crean una orden de manera sincrónica, siempre hasta completarse. La llamada no retorna hasta que la compra haya finalizado, lo que puede tomar hasta 150 segundos, así que configura el tiempo de espera de lectura de tu cliente por encima de eso. Runa es asíncrono por defecto.POST /v2/order devuelve 202 de inmediato con un ID de referencia, y lees la orden más tarde. Envía X-Execution-Mode: sync para bloquear hasta que la compra se complete y recibir el resultado completo, como lo hacen Tango e InComm.
Lectura de una orden
Una orden se puede leer una vez que su compra se ha completado. Leer un ID de referencia antes de eso devuelve un error en lugar de un estado pendiente, así que trata un error en una orden asíncrona recién creada como aún en proceso y vuelve a leer en breve. Los endpoints de listado devuelven las 100 órdenes más recientes de la cuenta en una sola respuesta, de la más nueva a la más antigua.Respuestas de error
Los errores usan el sobre de Fluz, no el esquema de errores de tu proveedor:
Una solicitud rechazada y una falla del servidor devuelven
500. Lee el mensaje en error para diferenciarlas: un rechazo significa que la solicitud debe cambiar, una falla es segura de reintentar.
Límites de tasa
20 solicitudes por segundo, aplicadas por clave de API y por IP de origen. Exceder cualquiera de los límites bloquea esa clave o IP por 10 segundos, así que retrocede al menos ese tiempo después de un429.
El límite por clave es compartido, por lo que varios hosts usando una clave comparten un mismo presupuesto.
Saldos
Una lectura de saldo informa el saldo disponible de la cuenta de Fluz para la cual se emitió tu clave de API. Tango lo devuelve comocurrentBalance y Runa como balance; InComm devuelve availableBalance junto con prepaidBalance, que cubre el saldo de la tarjeta de regalo por sí solo.
Una lectura de saldo siempre está limitada a la cuenta para la cual se emitió tu clave, por lo que los discriminadores en las llamadas de saldo de tu proveedor no lo restringen más: :accountId de Tango, :programId de InComm y ?currency= de Runa se aceptan por compatibilidad con la forma de solicitud que ya usas.
Un comportamiento a vigilar: una llamada de saldo con cualquier query string devuelve un solo objeto, y una llamada sin query string devuelve un arreglo con uno. Si tu cliente llama .map() sobre la respuesta, mantén la query string fuera.
Códigos de marca
Los tres conectores resuelven códigos de marca contra un único catálogo de Fluz, sin importar en qué campo viajen:utid en Tango, Sku en InComm, items[].products.value en Runa. Los códigos de producto de tu proveedor no se trasladan, y un código que Fluz no reconozca devuelve un error.
Mapea tu lista completa de marcas contra el catálogo de Fluz antes de la migración. Un código que resuelva a la oferta equivocada de Fluz entregará la tarjeta incorrecta sin error.
Restricciones de solicitud
Los conectores aceptan la forma de solicitud de tu proveedor, pero algunos valores son fijos. Una solicitud que rompa una de estas se rechaza.
Fluz devuelve las credenciales de la tarjeta de regalo directamente en la respuesta de la orden, por lo que las banderas de email anteriores deben estar desactivadas: la entrega al destinatario permanece bajo tu control.