Conciliaciones de efectivo

POST https://app.fire.rest/api/v1/adapters/xmart/cash-management/reconciliations
x-api-key: <tu_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": "Conteo corto en cierre de la tarde — sobrepago de cliente no 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": "Conteo corto en cierre de la tarde — sobrepago de cliente no 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: <tu_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": "Conteo corto en cierre de la tarde — sobrepago de cliente no 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": "Conteo corto en cierre de la tarde — sobrepago de cliente no 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 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.

Registra un conteo de efectivo de fin de turno o fin de día para una tienda y haz que Fire lo compare contra lo que el sistema dice que debería estar en caja. Fire calcula la diferencia (SHORTAGE, OVERAGE o MATCH), categoriza la causa y guarda el resultado en cash_reconciliations para auditoría y reportes downstream. Esta página cubre dos operaciones en el mismo path: POST para registrar una nueva conciliación, GET para listar conciliaciones por tienda/día/operador.

Autenticación

string

requerido

Tu API key de Fire.

POST — requiere scope cash-management:write.
GET — requiere scope cash-management:read.

La key debe ser vendor-scoped (binding de account requerido). Las keys system-only se rechazan con 403.

POST — Registrar una conciliación

Body de la petición

string

requerido

UUID de la tienda a la que pertenece la conciliación. Debe pertenecer al account/vendor de la API key — Fire devuelve 400 (con comportamiento hide-existence — equivalente a 404) en caso contrario.

string

Día de negocio en YYYY-MM-DD. Default es el día operacional actual de la tienda. Úsalo para registrar una conciliación de un día pasado (p. ej. correcciones retroactivas) — Fire marca el resultado con details.post_close: true si el día ya está cerrado.

string

ID del operador/cajero. Opcional. Úsalo cuando la conciliación es para un turno de cajero específico; omítelo cuando concilias toda la tienda-día.

string

requerido

Código ISO 4217 (p. ej. BRL, USD, ARS, CLP, COP, VES). Longitud 3.

number

requerido

Monto declarado de efectivo en caja por el operador. Decimal no negativo. Fire lo compara contra systemCash (lo que el sistema piensa que debería estar en caja según las ventas y pagos) para calcular la diferencia.

string

requerido

Causa categórica de cualquier diferencia. Una de:

WRONG_CHANGE_GIVEN
COUNTING_ERROR
INCOMPLETE_CUSTOMER_PAYMENT
MINOR_UNIDENTIFIED_DIFFERENCE
THEFT_SUSPECTED
UNRECORDED_PAYMENT
OTHER

Requerido incluso cuando no hay diferencia — para conteos que matchean, usa MINOR_UNIDENTIFIED_DIFFERENCE u OTHER según tu política operacional.

string

Free-text. Hasta 2000 caracteres. Úsalo para capturar contexto extra (nombre del operador, notas de turno, etc.).

string

UUID de un token de autorización. Cuando está presente, marca la conciliación como “que requiere/tiene aprobación” — típicamente usado para casos de THEFT_SUSPECTED o SHORTAGE grandes que necesitan firma del supervisor.

POST https://app.fire.rest/api/v1/adapters/xmart/cash-management/reconciliations
x-api-key: <tu_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": "Conteo corto en cierre de la tarde — sobrepago de cliente no contado"
}

Respuesta POST

string

UUID de la fila de conciliación.

string

Account dueño de la tienda.

string | null

Scope de vendor cuando aplica.

string

Eco del request.

string

YYYY-MM-DD.

string | null

Eco del request.

string

ISO 4217.

number

Monto calculado de efectivo que el sistema dice que debería estar en caja para este scope (tienda + día + operador opcional). Derivado de pagos cash aprobados menos cambio entregado, más fondo de apertura.

number

Eco del request.

number

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

string

MATCH (cero), SHORTAGE (declarado menor que sistema), o OVERAGE (declarado mayor que sistema).

string | null

Eco o null.

string

Identidad del principal que registró esta conciliación. Para callers vía API key: "apikey:<keyId>".

string

ISO 8601 UTC.

object

Mostrar details

string

Eco del request.

string | null

Eco del request.

boolean

true cuando la conciliación se registró después del cierre del día de negocio.

object | null

Cuando se proveyó authorizationTokenId y se validó, tiene { 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": "Conteo corto en cierre de la tarde — sobrepago de cliente no 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"
  }
}

GET — Listar conciliaciones

Devuelve las conciliaciones que matchean los filtros.

Query parameters

string

requerido

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

string

YYYY-MM-DD. Devuelve conciliaciones registradas para este día de negocio específico. Mutuamente excluyente con from/to.

string

Filtra a un solo operador/cajero.

string

YYYY-MM-DD. Cota inferior inclusiva para filtro de rango. Usar con to.

string

YYYY-MM-DD. Cota superior inclusiva. Usar con 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: <tu_api_key>

Respuesta GET

object[]

Array de registros de conciliación — misma forma que la data del response 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": "Conteo corto en cierre de la tarde",
        "post_close": false,
        "authorization": null
      },
      "createdAt": "2026-05-06T16:45:30.000Z",
      "updatedAt": "2026-05-06T16:45:30.000Z"
    }
  ]
}

Patrones comunes

Flow de fin de turno. Llama POST con el conteo declarado del operador cuando cierra su turno. Muestra discrepancy y discrepancyType al supervisor para firmar.
Conciliación de fin de día. Llama POST sin operatorUid para un conteo de toda la tienda después de que todos los turnos hayan cerrado.
Trail de auditoría. Usa GET con un rango de fechas para sacar todas las conciliaciones de una tienda en un período — útil para auditorías mensuales o trimestrales de efectivo.

Relacionado

Efectivo esperado

Calcula el efectivo esperado por el sistema para una tienda/día antes de registrar el conteo.

Autenticación

Cómo funcionan las API keys vendor-scoped y los scopes cash-management:*.

API

APIs de partner

PayBridge

Conciliaciones de efectivo

Autenticación

POST — Registrar una conciliación

Body de la petición

Respuesta POST

GET — Listar conciliaciones

Query parameters

Respuesta GET

Patrones comunes

Relacionado

Efectivo esperado

Autenticación

​Autenticación

​POST — Registrar una conciliación

​Body de la petición

​Respuesta POST

​GET — Listar conciliaciones

​Query parameters

​Respuesta GET

​Patrones comunes

​Relacionado

Efectivo esperado

Autenticación

Autenticación

POST — Registrar una conciliación

Body de la petición

Respuesta POST

GET — Listar conciliaciones

Query parameters

Respuesta GET

Patrones comunes

Relacionado