Efectivo esperado - Fire Docs

GET https://app.fire.rest/api/v1/adapters/xmart/cash-management/expected?storeId=550e8400-e29b-41d4-a716-446655440000&businessDayDate=2026-05-06
x-api-key: <tu_api_key>

{
  "store": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "storeCode": "BR-SP-001",
    "storeName": "Loja Centro - SP",
    "accountId": "100",
    "vendorId": "v_blueco_br",
    "timezone": "America/Sao_Paulo"
  },
  "businessDay": {
    "date": "2026-05-06",
    "state": "OPEN",
    "openedAt": "2026-05-06T06:00:00.000Z",
    "closedAt": null
  },
  "generatedAt": "2026-05-06T16:50:00.000Z",
  "summary": {
    "totalOrders": 157,
    "completedOrders": 152,
    "openOrders": 3,
    "cancelledOrders": 2,
    "forceClosedOrders": 0
  },
  "currencies": [
    {
      "currency": "BRL",
      "sales": {
        "gross": 4523.50,
        "net": 4350.25,
        "taxes": 623.75,
        "discounts": 173.25,
        "orderCount": 152
      },
      "byPaymentMethod": [
        {
          "processor": "cash",
          "transactionCount": 95,
          "approvedCount": 95,
          "rejectedCount": 0,
          "pendingCount": 0,
          "totalBilled": 2250.00,
          "cashTendered": 2350.00,
          "changeGiven": 100.00,
          "expectedCashOnHand": 2250.00
        },
        {
          "processor": "MASTERCARD",
          "transactionCount": 57,
          "approvedCount": 55,
          "rejectedCount": 1,
          "pendingCount": 1,
          "totalBilled": 2100.25,
          "cashTendered": null,
          "changeGiven": null,
          "expectedCashOnHand": null
        }
      ],
      "byChannelAndService": [
        {
          "channel": "KIOSK",
          "orderCount": 95,
          "total": 2850.50,
          "services": [{ "service": "DINE_IN", "orderCount": 95, "total": 2850.50 }]
        }
      ],
      "byOperator": [
        { "operatorUid": "op-cashier-123", "operatorName": "Operator Name", "orderCount": 75, "total": 2200.00 }
      ],
      "byDevice": [
        { "deviceUid": "device-uuid-1", "deviceName": "Terminal 1", "orderCount": 152, "total": 4350.25 }
      ],
      "byOperatorAndPaymentMethod": [
        {
          "operatorUid": "op-cashier-123",
          "operatorName": "Operator Name",
          "byPaymentMethod": [
            {
              "processor": "cash",
              "transactionCount": 75,
              "approvedCount": 75,
              "rejectedCount": 0,
              "pendingCount": 0,
              "totalBilled": 2200.00,
              "cashTendered": 2300.00,
              "changeGiven": 100.00,
              "expectedCashOnHand": 2200.00
            }
          ]
        }
      ],
      "cancelled": {
        "count": 2,
        "totalLost": 95.50,
        "byReason": [
          { "reason": "Customer Request", "count": 1, "total": 45.00 },
          { "reason": "System Error",     "count": 1, "total": 50.50 }
        ]
      },
      "pendingRisk": {
        "openOrdersTotal": 189.75,
        "paymentPendingTotal": 150.00,
        "paymentFailedTotal": 39.75
      }
    }
  ]
}

GET

api

adapters

xmart

cash-management

expected

GET https://app.fire.rest/api/v1/adapters/xmart/cash-management/expected?storeId=550e8400-e29b-41d4-a716-446655440000&businessDayDate=2026-05-06
x-api-key: <tu_api_key>

{
  "store": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "storeCode": "BR-SP-001",
    "storeName": "Loja Centro - SP",
    "accountId": "100",
    "vendorId": "v_blueco_br",
    "timezone": "America/Sao_Paulo"
  },
  "businessDay": {
    "date": "2026-05-06",
    "state": "OPEN",
    "openedAt": "2026-05-06T06:00:00.000Z",
    "closedAt": null
  },
  "generatedAt": "2026-05-06T16:50:00.000Z",
  "summary": {
    "totalOrders": 157,
    "completedOrders": 152,
    "openOrders": 3,
    "cancelledOrders": 2,
    "forceClosedOrders": 0
  },
  "currencies": [
    {
      "currency": "BRL",
      "sales": {
        "gross": 4523.50,
        "net": 4350.25,
        "taxes": 623.75,
        "discounts": 173.25,
        "orderCount": 152
      },
      "byPaymentMethod": [
        {
          "processor": "cash",
          "transactionCount": 95,
          "approvedCount": 95,
          "rejectedCount": 0,
          "pendingCount": 0,
          "totalBilled": 2250.00,
          "cashTendered": 2350.00,
          "changeGiven": 100.00,
          "expectedCashOnHand": 2250.00
        },
        {
          "processor": "MASTERCARD",
          "transactionCount": 57,
          "approvedCount": 55,
          "rejectedCount": 1,
          "pendingCount": 1,
          "totalBilled": 2100.25,
          "cashTendered": null,
          "changeGiven": null,
          "expectedCashOnHand": null
        }
      ],
      "byChannelAndService": [
        {
          "channel": "KIOSK",
          "orderCount": 95,
          "total": 2850.50,
          "services": [{ "service": "DINE_IN", "orderCount": 95, "total": 2850.50 }]
        }
      ],
      "byOperator": [
        { "operatorUid": "op-cashier-123", "operatorName": "Operator Name", "orderCount": 75, "total": 2200.00 }
      ],
      "byDevice": [
        { "deviceUid": "device-uuid-1", "deviceName": "Terminal 1", "orderCount": 152, "total": 4350.25 }
      ],
      "byOperatorAndPaymentMethod": [
        {
          "operatorUid": "op-cashier-123",
          "operatorName": "Operator Name",
          "byPaymentMethod": [
            {
              "processor": "cash",
              "transactionCount": 75,
              "approvedCount": 75,
              "rejectedCount": 0,
              "pendingCount": 0,
              "totalBilled": 2200.00,
              "cashTendered": 2300.00,
              "changeGiven": 100.00,
              "expectedCashOnHand": 2200.00
            }
          ]
        }
      ],
      "cancelled": {
        "count": 2,
        "totalLost": 95.50,
        "byReason": [
          { "reason": "Customer Request", "count": 1, "total": 45.00 },
          { "reason": "System Error",     "count": 1, "total": 50.50 }
        ]
      },
      "pendingRisk": {
        "openOrdersTotal": 189.75,
        "paymentPendingTotal": 150.00,
        "paymentFailedTotal": 39.75
      }
    }
  ]
}

API de partner. Este endpoint está pensado para integradores de plataforma. Los clientes estándar de Fire no tienen acceso directo — contactá a tu account manager si necesitás esta integración.

Devuelve el reporte de ventas y efectivo rastreado por el sistema para una tienda/día, usado para determinar lo que el cajón de efectivo debería contener antes de que un operador cuente. La respuesta es densa — cubre todas las monedas, todos los métodos de pago (con valores específicos para efectivo: tendered/change/expected-on-hand), totales por canal y servicio, desgloses por operador y dispositivo, y un resumen de cancelaciones. Este es el input principal para POST conciliaciones de efectivo — llama esto primero, presenta expectedCashOnHand al operador, después registra su conteo declarado.

Autenticación

x-api-key

string

requerido

Tu API key de Fire con scope cash-management:read. La key debe ser vendor-scoped — las keys system-only se rechazan con 403.

Query parameters

storeId

string

requerido

UUID de la tienda. Debe pertenecer al account/vendor de tu API key.

businessDayDate

string

YYYY-MM-DD. El día de negocio sobre el que reportar. Default es el día operacional actual de la tienda en su zona horaria.

operatorUid

string

Filtra el reporte a un solo cajero/operador. Cuando se omite, el reporte cubre todos los operadores del día.

GET https://app.fire.rest/api/v1/adapters/xmart/cash-management/expected?storeId=550e8400-e29b-41d4-a716-446655440000&businessDayDate=2026-05-06
x-api-key: <tu_api_key>

Respuesta

store

object

Metadata a nivel tienda.

Mostrar store

storeId

string

UUID.

storeCode

string | null

Código de tienda (p. ej. BR-SP-001).

storeName

string | null

Nombre para mostrar.

accountId

string

Account dueño de la tienda.

vendorId

string | null

Scope de vendor.

timezone

string | null

Zona horaria IANA — usada para calcular el día de negocio.

businessDay

object

Estado del día de negocio que cubre este reporte.

Mostrar businessDay

date

string | null

YYYY-MM-DD.

state

string

OPEN o CLOSED.

openedAt

string | null

ISO 8601 UTC.

closedAt

string | null

ISO 8601 UTC. null mientras está abierto.

generatedAt

string

ISO 8601 UTC de cuándo se calculó este reporte. Snapshot — llama de nuevo para refrescar.

summary

object

Conteos de órdenes de un vistazo.

Mostrar summary

totalOrders

number

Todas las órdenes en el scope.

completedOrders

number

status=COMPLETED && paymentStatus=SUCCEEDED.

openOrders

number

status=OPEN.

cancelledOrders

number

status=CANCELLED.

forceClosedOrders

number

Órdenes force-closed al cierre del día (system-driven).

currencies

object[]

Una entrada por moneda observada en el día. La mayoría de tiendas tienen una moneda; tiendas multi-moneda tienen una entrada por cada una.

Mostrar currencies[n]

currency

string

ISO 4217.

sales

object

Revenue agregado.

Mostrar sales

gross

number

Revenue total antes de descuentos/impuestos.

net

number

Después de descuentos.

taxes

number

Monto de impuestos.

discounts

number

Monto total de descuentos.

orderCount

number

Número de órdenes completadas que aportan.

byPaymentMethod

object[]

Una entrada por procesador de pago usado en el día.

Mostrar byPaymentMethod[n]

processor

string

p. ej. cash, Kushki, MASTERCARD, voucher.

transactionCount

number

Todos los intentos.

approvedCount

number

transactionStatus = APPROVED.

rejectedCount

number

Declinados / fallidos.

pendingCount

number

En vuelo.

totalBilled

number

Suma de totalBill en transacciones aprobadas.

cashTendered

number | null

Solo cash — total de efectivo entregado por clientes.

changeGiven

number | null

Solo cash — total de cambio devuelto.

expectedCashOnHand

number | null

Solo cash — cashTendered - changeGiven. Es el valor canónico para comparar contra el conteo declarado del operador.

byChannelAndService

object[]

Ventas desglosadas por canal (KIOSK, IFOOD, RAPPI, APP, …) con sub-desgloses por servicio de fulfillment (DELIVERY, DINE_IN, TAKEAWAY, PICKUP).

byOperator

object[]

Por cajero/operador: operatorUid, operatorName, orderCount, total. Útil para reportes de fin de turno.

byDevice

object[]

Por dispositivo: deviceUid, deviceName, orderCount, total.

byOperatorAndPaymentMethod

object[]

Cross-cut: por operador, la misma forma byPaymentMethod. Úsalo para calcular el efectivo esperado por cajero al correr una conciliación multi-cajero.

cancelled

object

count, totalLost (revenue perdido por cancelaciones), y array byReason (reason, count, total).

pendingRisk

object

Indicadores de riesgo: openOrdersTotal, paymentPendingTotal, paymentFailedTotal. Úsalo para flaggear revenue incierto al cierre.

{
  "store": {
    "storeId": "550e8400-e29b-41d4-a716-446655440000",
    "storeCode": "BR-SP-001",
    "storeName": "Loja Centro - SP",
    "accountId": "100",
    "vendorId": "v_blueco_br",
    "timezone": "America/Sao_Paulo"
  },
  "businessDay": {
    "date": "2026-05-06",
    "state": "OPEN",
    "openedAt": "2026-05-06T06:00:00.000Z",
    "closedAt": null
  },
  "generatedAt": "2026-05-06T16:50:00.000Z",
  "summary": {
    "totalOrders": 157,
    "completedOrders": 152,
    "openOrders": 3,
    "cancelledOrders": 2,
    "forceClosedOrders": 0
  },
  "currencies": [
    {
      "currency": "BRL",
      "sales": {
        "gross": 4523.50,
        "net": 4350.25,
        "taxes": 623.75,
        "discounts": 173.25,
        "orderCount": 152
      },
      "byPaymentMethod": [
        {
          "processor": "cash",
          "transactionCount": 95,
          "approvedCount": 95,
          "rejectedCount": 0,
          "pendingCount": 0,
          "totalBilled": 2250.00,
          "cashTendered": 2350.00,
          "changeGiven": 100.00,
          "expectedCashOnHand": 2250.00
        },
        {
          "processor": "MASTERCARD",
          "transactionCount": 57,
          "approvedCount": 55,
          "rejectedCount": 1,
          "pendingCount": 1,
          "totalBilled": 2100.25,
          "cashTendered": null,
          "changeGiven": null,
          "expectedCashOnHand": null
        }
      ],
      "byChannelAndService": [
        {
          "channel": "KIOSK",
          "orderCount": 95,
          "total": 2850.50,
          "services": [{ "service": "DINE_IN", "orderCount": 95, "total": 2850.50 }]
        }
      ],
      "byOperator": [
        { "operatorUid": "op-cashier-123", "operatorName": "Operator Name", "orderCount": 75, "total": 2200.00 }
      ],
      "byDevice": [
        { "deviceUid": "device-uuid-1", "deviceName": "Terminal 1", "orderCount": 152, "total": 4350.25 }
      ],
      "byOperatorAndPaymentMethod": [
        {
          "operatorUid": "op-cashier-123",
          "operatorName": "Operator Name",
          "byPaymentMethod": [
            {
              "processor": "cash",
              "transactionCount": 75,
              "approvedCount": 75,
              "rejectedCount": 0,
              "pendingCount": 0,
              "totalBilled": 2200.00,
              "cashTendered": 2300.00,
              "changeGiven": 100.00,
              "expectedCashOnHand": 2200.00
            }
          ]
        }
      ],
      "cancelled": {
        "count": 2,
        "totalLost": 95.50,
        "byReason": [
          { "reason": "Customer Request", "count": 1, "total": 45.00 },
          { "reason": "System Error",     "count": 1, "total": 50.50 }
        ]
      },
      "pendingRisk": {
        "openOrdersTotal": 189.75,
        "paymentPendingTotal": 150.00,
        "paymentFailedTotal": 39.75
      }
    }
  ]
}

Cómo usarlo con conciliación

El expectedCashOnHand canónico contra el cual comparar es por moneda, por método de pago cash. Para cierres por cajero, entra a byOperatorAndPaymentMethod[i].byPaymentMethod y encuentra la entrada cash — ese es el esperado específico del operador.

Patrones comunes

Dashboard de fin de turno en tiempo real. Pollea este endpoint cada pocos minutos durante un día ocupado para mostrar totales corriendo; congela el snapshot al cierre del turno.
Cierre por cajero. Filtra con operatorUid=... para sacar solo los totales de ese cajero; registra su conciliación contra byOperatorAndPaymentMethod[].byPaymentMethod[cash].expectedCashOnHand.
Tiendas multi-moneda. Itera sobre currencies[] — cada entrada es independiente; concilia cada moneda por separado.
Riesgo pendiente. Muestra pendingRisk.paymentFailedTotal y pendingRisk.openOrdersTotal a operadores antes de que cierren — son montos que el sistema no puede confirmar.

Relacionado

Conciliaciones de efectivo

Registra el conteo del operador después de leer el efectivo esperado acá.

Autenticación

API keys vendor-scoped y el scope cash-management:read.

Datos fiscales para impresión Conciliaciones de efectivo

​Autenticación

​Query parameters

​Respuesta

​Cómo usarlo con conciliación

​Patrones comunes

​Relacionado

Conciliaciones de efectivo

Autenticación

Autenticación

Query parameters

Respuesta

Cómo usarlo con conciliación

Patrones comunes

Relacionado