Caixa 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: <sua_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: <sua_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 parceiro. Este endpoint é destinado a integradores de plataforma. Clientes padrão do Fire não têm acesso direto — entre em contato com seu account manager se precisar desta integração.

Retorna o relatório de vendas e caixa rastreado pelo sistema para uma loja/dia, usado para determinar o que o caixa deveria conter antes do operador fazer a contagem. A resposta é densa — cobre todas as moedas, todos os métodos de pagamento (com valores específicos para dinheiro: tendered/change/expected-on-hand), totais por canal e serviço, detalhamentos por operador e dispositivo, e um resumo de cancelamentos. Este é o input principal para POST conciliações de caixa — chame isto primeiro, apresente expectedCashOnHand ao operador, depois registre sua contagem declarada.

Autenticação

string

obrigatório

Sua API key do Fire com scope cash-management:read. A key deve ser vendor-scoped — keys system-only são rejeitadas com 403.

Query parameters

string

obrigatório

UUID da loja. Deve pertencer ao account/vendor da sua API key.

string

YYYY-MM-DD. O dia de negócio sobre o qual reportar. Default é o dia operacional atual da loja no seu fuso horário.

string

Filtra o relatório para um único caixa/operador. Quando omitido, o relatório cobre todos os operadores do dia.

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: <sua_api_key>

Resposta

object

Metadata a nível de loja.

Mostrar store

string

UUID.

string | null

Código de loja (ex.: BR-SP-001).

string | null

Nome de exibição.

string

Account dono da loja.

string | null

Escopo de vendor.

string | null

Fuso horário IANA — usado para calcular o dia de negócio.

object

Status do dia de negócio que este relatório cobre.

Mostrar businessDay

string | null

YYYY-MM-DD.

string

OPEN ou CLOSED.

string | null

ISO 8601 UTC.

string | null

ISO 8601 UTC. null enquanto aberto.

string

ISO 8601 UTC de quando este relatório foi calculado. Snapshot — chame de novo para atualizar.

object

Contagens de pedidos rapidamente.

Mostrar summary

number

Todos os pedidos do escopo.

number

status=COMPLETED && paymentStatus=SUCCEEDED.

number

status=OPEN.

number

status=CANCELLED.

number

Pedidos force-closed no fechamento do dia (system-driven).

object[]

Uma entrada por moeda observada no dia. A maioria das lojas tem uma moeda; lojas multi-moeda têm uma entrada por cada.

Mostrar currencies[n]

string

ISO 4217.

object

Revenue agregado.

Mostrar sales

number

Revenue total antes de descontos/impostos.

number

Após descontos.

number

Valor de impostos.

number

Valor total de descontos.

number

Número de pedidos completados contribuindo.

object[]

Uma entrada por processador de pagamento usado no dia.

Mostrar byPaymentMethod[n]

string

ex.: cash, Kushki, MASTERCARD, voucher.

number

Todas as tentativas.

number

transactionStatus = APPROVED.

number

Recusadas / falhas.

number

Em voo.

number

Soma de totalBill em transações aprovadas.

number | null

Apenas cash — total de dinheiro entregue pelos clientes.

number | null

Apenas cash — total de troco devolvido.

number | null

Apenas cash — cashTendered - changeGiven. É o valor canônico para comparar contra a contagem declarada do operador.

object[]

Vendas detalhadas por canal (KIOSK, IFOOD, RAPPI, APP, …) com sub-detalhamentos por serviço de fulfillment (DELIVERY, DINE_IN, TAKEAWAY, PICKUP).

object[]

Por caixa/operador: operatorUid, operatorName, orderCount, total. Útil para relatórios de fim de turno.

object[]

Por dispositivo: deviceUid, deviceName, orderCount, total.

object[]

Cross-cut: por operador, o mesmo formato byPaymentMethod. Use para calcular o caixa esperado por caixa ao rodar uma conciliação multi-caixa.

object

count, totalLost (revenue perdido por cancelamentos), e array byReason (reason, count, total).

object

Indicadores de risco: openOrdersTotal, paymentPendingTotal, paymentFailedTotal. Use para sinalizar revenue incerto no fechamento.

{
  "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"
  }
}

Como usar com conciliação

O expectedCashOnHand canônico para comparar é por moeda, por método de pagamento cash. Para fechamentos por caixa, entre em byOperatorAndPaymentMethod[i].byPaymentMethod e encontre a entrada cash — esse é o esperado específico do operador.

Padrões comuns

Dashboard de fim de turno em tempo real. Pollee este endpoint a cada poucos minutos durante um dia movimentado para mostrar totais correndo; congele o snapshot no fechamento do turno.
Fechamento por caixa. Filtre com operatorUid=... para obter apenas os totais desse caixa; registre sua conciliação contra byOperatorAndPaymentMethod[].byPaymentMethod[cash].expectedCashOnHand.
Lojas multi-moeda. Itere sobre currencies[] — cada entrada é independente; concilie cada moeda separadamente.
Risco pendente. Mostre pendingRisk.paymentFailedTotal e pendingRisk.openOrdersTotal aos operadores antes do fechamento — são valores que o sistema não pode confirmar.

Relacionado

Conciliações de caixa

Registre a contagem do operador após ler o caixa esperado aqui.

Autenticação

API keys vendor-scoped e o scope cash-management:read.

​Autenticação

​Query parameters

​Resposta

​Como usar com conciliação

​Padrões comuns

​Relacionado

Conciliações de caixa

Autenticação

Autenticação

Query parameters

Resposta

Como usar com conciliação

Padrões comuns

Relacionado