Conciliações de caixa

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

{
  "error": {
    "code": "validation_error",
    "message": "storeId not found in your scope"
  }
}

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

POST

api

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

{
  "error": {
    "code": "validation_error",
    "message": "storeId not found in your scope"
  }
}

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

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

string

required

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

string

required

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.

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.

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.

string

required

Código ISO 4217 (ex.: BRL, USD, ARS, CLP, COP, VES). Tamanho 3.

number

required

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.

string

required

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.

string

Free-text. Até 2000 caracteres. Use para capturar contexto extra (nome do operador, notas de turno, etc.).

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

string

UUID da linha de conciliação.

string

Account dono da loja.

string | null

Escopo de vendor quando se aplica.

string

Eco do request.

string

YYYY-MM-DD.

string | null

Eco do request.

string

ISO 4217.

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.

number

Eco do request.

number

declaredCash - systemCash. Negativo para shortage, positivo para overage, zero para match.

string

MATCH (zero), SHORTAGE (declarado menor que sistema), ou OVERAGE (declarado maior que sistema).

string | null

Eco ou null.

string

Identidade do principal que registrou esta conciliação. Para callers via API key: "apikey:<keyId>".

string

ISO 8601 UTC.

object

Show details

string

Eco do request.

string | null

Eco do request.

boolean

true quando a conciliação foi registrada após o fechamento do dia de negócio.

object | null

Quando authorizationTokenId foi fornecido e validado, tem { approved_by, approved_at }.

string

ISO 8601 UTC.

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

{
  "error": {
    "code": "validation_error",
    "message": "storeId not found in your scope"
  }
}

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

Campos novos na resposta. Desde que existe a v2, toda conciliação — inclusive as registradas aqui — devolve também apiVersion, openingBalance, withdrawalsTotal, sessionExternalId e terminalUid, e details pode trazer withdrawals e operator_name.Nas linhas da v1, apiVersion é 1, withdrawalsTotal é 0 e sessionExternalId é null. São acréscimos: nenhum campo existente mudou de valor nem de significado.

GET — Listar conciliações

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

Query parameters

string

required

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

string

YYYY-MM-DD. Retorna conciliações registradas para este dia de negócio específico. Mutuamente exclusivo com from/to.

string

Filtra para um único operador/caixa.

string

YYYY-MM-DD. Limite inferior inclusivo para filtro de intervalo. Use com 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

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.

​Autenticação

​POST — Registrar uma conciliação

​Corpo da requisição

​Resposta POST

​GET — Listar conciliações

​Query parameters

​Resposta GET

​Padrões comuns

​Relacionado

Caixa esperado

Autenticação

Autenticação

POST — Registrar uma conciliação

Corpo da requisição

Resposta POST

GET — Listar conciliações

Query parameters

Resposta GET

Padrões comuns

Relacionado