Saltar para o conteúdo principal
POST
/
api
/
v1
/
adapters
/
xmart
/
cash-management
/
reconciliations
POST https://app.fire.rest/api/v1/adapters/xmart/cash-management/reconciliations
x-api-key: <sua_api_key>
Content-Type: application/json

{
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "declaredCash": 1250.50,
  "reason": "COUNTING_ERROR",
  "notes": "Contagem curta no fechamento da tarde — pagamento extra do cliente não contado"
}

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "accountId": "100",
  "vendorId": "v_blueco_br",
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "systemCash": 1300.75,
  "declaredCash": 1250.50,
  "discrepancy": -50.25,
  "discrepancyType": "SHORTAGE",
  "authorizationTokenId": null,
  "reportedBy": "apikey:k_ab12cd34",
  "reportedAt": "2026-05-06T16:45:30.000Z",
  "details": {
    "reason": "COUNTING_ERROR",
    "notes": "Contagem curta no fechamento da tarde — pagamento extra do cliente não contado",
    "post_close": false,
    "authorization": null
  },
  "createdAt": "2026-05-06T16:45:30.000Z",
  "updatedAt": "2026-05-06T16:45:30.000Z"
}
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.
Registre uma contagem de caixa de fim de turno ou fim de dia para uma loja e faça o Fire compará-la contra o que o sistema diz que deveria estar em caixa. O Fire calcula a diferença (SHORTAGE, OVERAGE ou MATCH), categoriza a causa e armazena o resultado em cash_reconciliations para auditoria e relatórios downstream. Esta página cobre duas operações no mesmo path: POST para registrar uma nova conciliação, GET para listar conciliações por loja/dia/operador.

​
Autenticação

​
x-api-key
string
obrigatório
Sua API key do Fire.
  • POST — requer scope cash-management:write.
  • GET — requer scope cash-management:read.
A key deve ser vendor-scoped (binding de account exigido). Keys system-only são rejeitadas com 403.

​
POST — Registrar uma conciliação

​
Corpo da requisição

​
storeId
string
obrigatório
UUID da loja à qual a conciliação pertence. Deve pertencer ao account/vendor da API key — o Fire retorna 400 (com comportamento hide-existence — equivalente a 404) caso contrário.
​
businessDayDate
string
Dia de negócio em YYYY-MM-DD. Default é o dia operacional atual da loja. Use para registrar uma conciliação de um dia passado (ex.: correções retroativas) — o Fire marca o resultado com details.post_close: true se o dia já estiver fechado.
​
operatorUid
string
ID do operador/caixa. Opcional. Use quando a conciliação é para um turno de caixa específico; omita ao conciliar toda a loja-dia.
​
currency
string
obrigatório
Código ISO 4217 (ex.: BRL, USD, ARS, CLP, COP, VES). Tamanho 3.
​
declaredCash
number
obrigatório
Valor declarado de caixa em mãos pelo operador. Decimal não negativo. O Fire compara contra systemCash (o que o sistema acha que deveria estar em caixa baseado em vendas e pagamentos) para calcular a diferença.
​
reason
string
obrigatório
Causa categórica de qualquer diferença. Um de:
  • WRONG_CHANGE_GIVEN
  • COUNTING_ERROR
  • INCOMPLETE_CUSTOMER_PAYMENT
  • MINOR_UNIDENTIFIED_DIFFERENCE
  • THEFT_SUSPECTED
  • UNRECORDED_PAYMENT
  • OTHER
Exigido mesmo quando não há diferença — para contagens que batem, use MINOR_UNIDENTIFIED_DIFFERENCE ou OTHER conforme sua política operacional.
​
notes
string
Free-text. Até 2000 caracteres. Use para capturar contexto extra (nome do operador, notas de turno, etc.).
​
authorizationTokenId
string
UUID de um token de autorização. Quando presente, marca a conciliação como “que requer/tem aprovação” — tipicamente usado para casos de THEFT_SUSPECTED ou SHORTAGE grandes que precisam de assinatura do supervisor.
POST https://app.fire.rest/api/v1/adapters/xmart/cash-management/reconciliations
x-api-key: <sua_api_key>
Content-Type: application/json

{
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "declaredCash": 1250.50,
  "reason": "COUNTING_ERROR",
  "notes": "Contagem curta no fechamento da tarde — pagamento extra do cliente não contado"
}

​
Resposta POST

​
id
string
UUID da linha de conciliação.
​
accountId
string
Account dono da loja.
​
vendorId
string | null
Escopo de vendor quando se aplica.
​
storeId
string
Eco do request.
​
businessDayDate
string
YYYY-MM-DD.
​
operatorUid
string | null
Eco do request.
​
currency
string
ISO 4217.
​
systemCash
number
Valor calculado de caixa que o sistema diz que deveria estar em mãos para este escopo (loja + dia + operador opcional). Derivado de pagamentos em dinheiro aprovados menos troco dado, mais fundo de abertura.
​
declaredCash
number
Eco do request.
​
discrepancy
number
declaredCash - systemCash. Negativo para shortage, positivo para overage, zero para match.
​
discrepancyType
string
MATCH (zero), SHORTAGE (declarado menor que sistema), ou OVERAGE (declarado maior que sistema).
​
authorizationTokenId
string | null
Eco ou null.
​
reportedBy
string
Identidade do principal que registrou esta conciliação. Para callers via API key: "apikey:<keyId>".
​
reportedAt
string
ISO 8601 UTC.
​
details
object
​
createdAt
string
ISO 8601 UTC.
​
updatedAt
string
ISO 8601 UTC.
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "accountId": "100",
  "vendorId": "v_blueco_br",
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "systemCash": 1300.75,
  "declaredCash": 1250.50,
  "discrepancy": -50.25,
  "discrepancyType": "SHORTAGE",
  "authorizationTokenId": null,
  "reportedBy": "apikey:k_ab12cd34",
  "reportedAt": "2026-05-06T16:45:30.000Z",
  "details": {
    "reason": "COUNTING_ERROR",
    "notes": "Contagem curta no fechamento da tarde — pagamento extra do cliente não contado",
    "post_close": false,
    "authorization": null
  },
  "createdAt": "2026-05-06T16:45:30.000Z",
  "updatedAt": "2026-05-06T16:45:30.000Z"
}

​
GET — Listar conciliações

Retorna as conciliações que combinam com os filtros.

​
Query parameters

​
storeId
string
obrigatório
UUID da loja. Deve pertencer ao account/vendor da sua API key.
​
businessDayDate
string
YYYY-MM-DD. Retorna conciliações registradas para este dia de negócio específico. Mutuamente exclusivo com from/to.
​
operatorUid
string
Filtra para um único operador/caixa.
​
from
string
YYYY-MM-DD. Limite inferior inclusivo para filtro de intervalo. Use com to.
​
to
string
YYYY-MM-DD. Limite superior inclusivo. Use com from.
GET https://app.fire.rest/api/v1/adapters/xmart/cash-management/reconciliations?storeId=550e8400-e29b-41d4-a716-446655440000&businessDayDate=2026-05-06
x-api-key: <sua_api_key>

​
Resposta GET

​
reconciliations
object[]
Array de registros de conciliação — mesmo formato que os dados da resposta POST.
{
  "reconciliations": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "accountId": "100",
      "vendorId": "v_blueco_br",
      "storeId": "550e8400-e29b-41d4-a716-446655440000",
      "businessDayDate": "2026-05-06",
      "operatorUid": "op-cashier-123",
      "currency": "BRL",
      "systemCash": 1300.75,
      "declaredCash": 1250.50,
      "discrepancy": -50.25,
      "discrepancyType": "SHORTAGE",
      "authorizationTokenId": null,
      "reportedBy": "apikey:k_ab12cd34",
      "reportedAt": "2026-05-06T16:45:30.000Z",
      "details": {
        "reason": "COUNTING_ERROR",
        "notes": "Contagem curta no fechamento da tarde",
        "post_close": false,
        "authorization": null
      },
      "createdAt": "2026-05-06T16:45:30.000Z",
      "updatedAt": "2026-05-06T16:45:30.000Z"
    }
  ]
}

​
Padrões comuns

  • Fluxo de fim de turno. Chame POST com a contagem declarada do operador quando o turno fechar. Mostre discrepancy e discrepancyType ao supervisor para assinar.
  • Conciliação de fim de dia. Chame POST sem operatorUid para uma contagem de toda a loja após todos os turnos terem fechado.
  • Trilha de auditoria. Use GET com um intervalo de datas para extrair todas as conciliações de uma loja em um período — útil para auditorias mensais ou trimestrais de caixa.

​
Relacionado

Caixa esperado

Calcule o caixa esperado pelo sistema para uma loja/dia antes de registrar a contagem.

Autenticação

Como as API keys vendor-scoped e os scopes cash-management:* funcionam.