Sitios

Un sitio es un punto de venta del comercio: una tienda en línea, un canal telefónico, un punto físico. Cada sitio tiene sus propias credenciales, su moneda, su idioma y su configuración de operación.

La colección sites viaja en la raíz del cuerpo, junto a los campos del propio comercio, y la aceptan tanto la creación como la actualización. Una petición puede traer varios sitios a la vez.

Crear o modificar un sitio

Lo que determina si un elemento crea un sitio nuevo o modifica uno existente es la presencia del campo id:

En una creación (POST), enviar sites[].id responde 422, porque no hay sitios previos que modificar. En una actualización, el id debe pertenecer al comercio de la URL. El campo customerId responde 422 siempre: el comercio viaja en la URL.

Credenciales del sitio

Cada sitio tiene sus propias credenciales, con las que se identifica ante la plataforma de pagos:

Si no las envías, Onboarding las genera. Esa es la razón por la que son opcionales incluso al crear un sitio.

Como el login no distingue mayúsculas, ACME y acme son el mismo identificador y no pueden coexistir. Sigue estando disponible en dos casos, además de cuando está libre: cuando lo tiene el propio sitio que estás modificando, y cuando pertenece a un sitio que esta misma clave de idempotencia ya creó —sin lo cual un reintento colisionaría con su propio primer intento—.

Campos del sitio

{
  "sites": [
    {
      "name": "Tienda principal",
      "displayName": "Acme",
      "type": "INT",
      "category": "ECOMMERCE",
      "email": "[email protected]",
      "currency": "COP",
      "language": "ES",
      "onTest": true,
      "integration": {
        "allowPartial": false,
        "checkoutVersion": "v4",
        "connectionMethod": "REDIRECT",
        "notificationUrl": "https://acme.example.com/pay/notify",
        "allowWallet": true,
        "checkoutAttemptsLimit": 5
      },
      "control": {
        "minAmount": 1000,
        "maxAmount": 5000000,
        "allowedDays": 127,
        "allowedHours": "ffffffffffffffffffffffffffffffffffffffffff",
        "filterPse": false,
        "filterByBin": false,
        "allowedBankCountries": ["CO"]
      },
      "threeDS": { "setting": "LOW", "minAmount": 0 },
      "securityFilters": { "onlyWhitelisted": false, "dayMax": 5 },
      "operation": { "taxPercentage": 19, "mailCustomer": true },
      "branding": { "buttonColor": "#1a73e8" }
    }
  ]
}

Bloque integration

Define cómo se conecta el sitio con la plataforma de pagos.

Bloque control

Restringe cuándo y con qué montos puede operar el sitio.

Los demás bloques

Varios límites son más estrechos que lo que el registro admitiría, porque replican los que impone la configuración estándar de la plataforma. Enviar un valor fuera de esos límites responde 422 señalando el campo.

Metadatos del sitio

{
  "sites": [
    {
      "name": "Tienda principal",
      "metadata": {
        "contractRef": "AC-2026-0042",
        "onboardingBatch": 17,
        "requiresManualReview": true
      }
    }
  ]
}

Se fusiona, y se borra nombrando la clave

{
  "sites": [
    {
      "id": 412,
      "metadata": {
        "onboardingBatch": 18,
        "reviewedBy": "riesgo",
        "legacyFlag": null
      }
    }
  ]
}

contractRef sobrevive sin haberse reenviado, legacyFlag desaparece por haberse nombrado con null, y las otras dos se escriben.

El tamaño se mide sobre el documento resultante

Es una consecuencia directa de la fusión: como el documento nunca se reemplaza, solo puede crecer. Acotar únicamente la petición dejaría pasar escrituras que después no se podrían almacenar.

Retirar claves es la única forma de recuperar espacio. Si un sitio se acerca al tope, nombra con null lo que ya no uses.

Ten en cuenta también que el bloque se valida en cadena y se detiene en el primer fallo: si envías a la vez un nombre inválido y un documento demasiado grande, solo verás el error del nombre.

Los límites exactos están en la referencia de la API, junto con la longitud máxima de un nombre y de un valor.

No se puede leer de vuelta

Un cuerpo que no envía metadata deja el result exactamente igual que antes de que este bloque existiera.

Qué no poner aquí

Ten en cuenta además que el back office todavía no muestra estos datos. Quedan guardados y auditados, pero verlos desde la ficha del sitio requiere un desarrollo pendiente del lado del back office.

Comportamiento en una actualización

La colección es upsert-only: un sitio que el cuerpo no nombra sobrevive intacto, y dentro de un sitio que sí nombras solo cambia lo que envías.

Los bloques branding y los ajustes internos del sitio se fusionan en lugar de reemplazarse, porque contienen claves que solo la plataforma escribe y que una actualización no podría restaurar.

Efectos de una edición posterior desde el back office

Hay tres valores que la plataforma normaliza la primera vez que una persona guarda el sitio desde el back office. No son fallos y no se pueden devolver como error, pero conviene conocerlos:

• Un allowedHours que no habilite ninguna hora se convierte en «todas las horas».
• Una fecha de expiración pierde su componente de hora.
• Una comisión heredada de un medio de pago del sitio pasa a 0.00. Ver Medios de pago del sitio.

El resultado

{
  "result": {
    "merchantId": 18,
    "sites": [
      {
        "id": 214,
        "login": "aabbccdd1234567890aabbccdd123456",
        "tranKey": "ABC123example456trankey+789abc012def3456ABC=",
        "active": true,
        "action": "created"
      },
      {
        "id": 209,
        "login": "123example456token789abc012def345",
        "tranKey": null,
        "active": true,
        "action": "updated"
      }
    ]
  }
}

Las claves se mantienen siempre presentes para que la forma del resultado no dependa de qué cambió.

Colecciones dentro de un sitio

Un sitio puede llevar sus propias colecciones, con reglas propias:

• Integraciones del sitio — sites[].integrations
• Medios de pago del sitio — sites[].paymentMethods

¿Qué sigue?

• Integraciones del sitio
• Medios de pago del sitio
• Actualizar un comercio