Proceso de Conciliacion de Transacciones

Alcance

Este documento define el formato del archivo JSON, la ruta de carga en Cloud Storage y las reglas de conciliacion.

Resumen

Cuando un archivo JSON se sube al bucket de conciliacion, se ejecuta automaticamente un proceso que compara transacciones reportadas vs. transacciones registradas en base de datos.

Ubicacion del Archivo

Bucket (ejemplo seguro)

gs://example-conciliation-bucket

Estructura de ruta

principals/<principal-id>/conciliation/<filename>.json

Parametro	Descripcion
<principal-id>	Identificador del principal (sin exponer correos reales ni service accounts reales).
<filename>	Nombre descriptivo del archivo, idealmente con fecha.

Ejemplo de ruta valida (anonimizada)

gs://example-conciliation-bucket/principals/demo-principal-001/conciliation/conciliacion-2026-03-11.json

Formato del Archivo JSON

Estructura

{
  "fechatransaccion": "YYYY-MM-DD",
  "items": [
    {
      "id": "string",
      "monto": 0,
      "referencia": "string",
      "fecha": "ISO 8601 timestamp",
      "sku": "string"
    }
  ]
}

Definicion de campos

Campo	Tipo	Requerido	Regla
fechatransaccion	string	Si	Formato YYYY-MM-DD en horario de Ciudad de Mexico.
items	array	Si	Minimo 1 elemento.
items[].id	string	Si	Identificador unico de la transaccion.
items[].monto	number	Si	Monto en MXN, hasta 2 decimales.
items[].referencia	string	Si	Referencia de la transaccion (telefono o folio).
items[].fecha	string	Si	Timestamp ISO 8601 en UTC.
items[].sku	string	Si	SKU del producto o servicio.

Regla importante de zona horaria

items[].fecha viene en UTC, pero la conciliacion se evalua contra fechatransaccion en horario de Ciudad de Mexico.

Ejemplo Completo

Archivo: transacciones-2026-02-13.json

{
  "fechatransaccion": "2026-02-13",
  "items": [
    {
      "id": "TX-55146",
      "monto": 30.0,
      "referencia": "6640000001",
      "fecha": "2026-02-14T00:25:51.98872Z",
      "sku": "A030"
    },
    {
      "id": "TX-55147",
      "monto": 100.0,
      "referencia": "6640000002",
      "fecha": "2026-02-14T00:29:44.530341Z",
      "sku": "A100"
    },
    {
      "id": "TX-55148",
      "monto": 50.0,
      "referencia": "6640000003",
      "fecha": "2026-02-13T20:15:30.123456Z",
      "sku": "A050"
    }
  ]
}

Zona Horaria: UTC vs Mexico

Para fechatransaccion: "2026-02-13" (Mexico), el rango UTC consultado es:

• Inicio: 2026-02-13 06:00:00 UTC
• Fin: 2026-02-14 05:59:59 UTC

Transacciones incluidas (ejemplo):

• 2026-02-13T08:00:00Z
• 2026-02-14T00:25:51Z
• 2026-02-14T05:59:00Z

No incluida:

• 2026-02-14T06:00:00Z (ya corresponde al siguiente dia en Mexico)

Carga del Archivo

Selecciona el lenguaje o herramienta que prefieras:

gsutil

gsutil cp transacciones-2026-03-11.json \
  gs://example-conciliation-bucket/principals/demo-principal-001/conciliation/

gsutil ls gs://example-conciliation-bucket/principals/demo-principal-001/conciliation/

Python

from google.cloud import storage

client = storage.Client()
bucket = client.bucket("example-conciliation-bucket")

principal_id = "demo-principal-001"
filename = "transacciones-2026-03-11.json"
blob_name = f"principals/{principal_id}/conciliation/{filename}"

blob = bucket.blob(blob_name)
blob.upload_from_filename(filename)

print(f"Archivo subido: {blob_name}")

Node.js

const { Storage } = require("@google-cloud/storage");

const storage = new Storage();
const bucketName = "example-conciliation-bucket";
const principalId = "demo-principal-001";
const filename = "transacciones-2026-03-11.json";
const destination = `principals/${principalId}/conciliation/${filename}`;

async function uploadFile() {
  await storage.bucket(bucketName).upload(filename, { destination });
  console.log(`${filename} uploaded to ${destination}`);
}

uploadFile();

cURL

# Usa variables de entorno y placeholders; no publiques tokens reales.
ACCESS_TOKEN="<temporary-access-token>"

curl -X POST \
  "https://storage.googleapis.com/upload/storage/v1/b/example-conciliation-bucket/o?uploadType=media&name=principals/demo-principal-001/conciliation/transacciones-2026-03-11.json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @transacciones-2026-03-11.json

Resultados de Conciliacion

Conciliacion exitosa

Total en archivo: 10
Total en base de datos: 10
Coincidencias: 10
Faltan en BD: 0
Faltan en archivo: 0
Discrepancias de monto: 0

Diferencias detectadas

Transacciones faltantes en BD:

Total en archivo: 12
Total en base de datos: 10
Coincidencias: 10
Faltan en BD: 2
Faltan en archivo: 0
Discrepancias de monto: 0

Transacciones faltantes en archivo:

Total en archivo: 8
Total en base de datos: 10
Coincidencias: 8
Faltan en BD: 0
Faltan en archivo: 2
Discrepancias de monto: 0

Discrepancias de monto:

Total en archivo: 10
Total en base de datos: 10
Coincidencias: 8
Faltan en BD: 0
Faltan en archivo: 0
Discrepancias de monto: 2

Referencias

• Cloud Storage Documentation