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
      }
    }
  ]
}

{
  "error": {
    "code": "validation_error",
    "message": "storeId must be a UUID"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "cash-management endpoints require a vendor-scoped API key"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Store not found"
  }
}

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
      }
    }
  ]
}

{
  "error": {
    "code": "validation_error",
    "message": "storeId must be a UUID"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "cash-management endpoints require a vendor-scoped API key"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Store not found"
  }
}

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

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

string

requerido

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

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.

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

object

Metadata a nivel tienda.

Mostrar store

string

UUID.

string | null

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

string | null

Nombre para mostrar.

string

Account dueño de la tienda.

string | null

Scope de vendor.

string | null

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

object

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

Mostrar businessDay

string | null

YYYY-MM-DD.

string

OPEN o CLOSED.

string | null

ISO 8601 UTC.

string | null

ISO 8601 UTC. null mientras está abierto.

string

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

object

Conteos de órdenes de un vistazo.

Mostrar summary

number

Todas las órdenes en el scope.

number

status=COMPLETED && paymentStatus=SUCCEEDED.

number

status=OPEN.

number

status=CANCELLED.

number

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

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]

string

ISO 4217.

object

Revenue agregado.

Mostrar sales

number

Revenue total antes de descuentos/impuestos.

number

Después de descuentos.

number

Monto de impuestos.

number

Monto total de descuentos.

number

Número de órdenes completadas que aportan.

object[]

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

Mostrar byPaymentMethod[n]

string

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

number

Todos los intentos.

number

transactionStatus = APPROVED.

number

Declinados / fallidos.

number

En vuelo.

number

Suma de totalBill en transacciones aprobadas.

number | null

Solo cash — total de efectivo entregado por clientes.

number | null

Solo cash — total de cambio devuelto.

number | null

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

object[]

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

object[]

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

object[]

Por dispositivo: deviceUid, deviceName, orderCount, total.

object[]

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

object

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

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
      }
    }
  ]
}

{
  "error": {
    "code": "validation_error",
    "message": "storeId must be a UUID"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "cash-management endpoints require a vendor-scoped API key"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Store not found"
  }
}

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.

​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