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,
        "reviewers": ["riesgo", "legal"]
      }
    }
  ]
}

Qué admite un nombre y qué admite un valor

Un nombre admite hasta 64 caracteres y distingue mayúsculas.

Un valor es un dato simple o una estructura. El anidamiento llega hasta tres niveles, y cada dato simple admite 1024 caracteres, esté suelto o dentro de una estructura.

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.

Dónde se lee

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

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.

Sitios migrados desde Copper

{
  "sites": [
    {
      "name": "Tienda principal",
      "metadata": {
        "copper": {
          "is_migrated": true,
          "id": "cu_8f2a91",
          "parent_id": "cu_1d77e0",
          "integration_type": "TC",
          "secret": "exampleCopperSecret",
          "error_code_level": 2,
          "card_data_return": "bin_last4",
          "allow_preauth": false,
          "requires_cvv": true,
          "assigned_version": "1.0"
        }
      }
    }
  ]
}

Las diez claves

id es el identificador del sitio en Copper, y parent_id, el identificador en Copper del comercio padre. secret es el secreto de la integración en Copper, y assigned_version, la versión de la integración que Copper le asignó al sitio.

Cómo se valida

• Solo is_migrated: true marca el sitio como migrado, y entonces exige las seis claves obligatorias. Con false, o sin la clave, no se exige ninguna, pero las que envíes se validan igual: tipo y valores admitidos.
• Los tipos son estrictos. Un booleano es true o false de JSON: "true", "1" y 1 responden 422. Un entero es un número de JSON: "2" responde 422. Una versión es una cadena de JSON con uno de los cuatro valores exactos: 1.1 como número, "1" y "1.10" responden 422.
• Ninguna clave admite null ni texto vacío, tampoco is_migrated. Una clave sin valor simplemente no se envía.
• copper es un objeto con al menos una clave. {}, una lista o un valor suelto responden 422.
• Una clave fuera de las diez responde 422, y el error la nombra. Así, una errata como is_migrate no deja el sitio sin marcar en silencio.
• El id de Copper no tiene que ser único: dos sitios pueden compartirlo, en la misma petición o en comercios distintos.
• Siguen rigiendo los límites de metadata: 1024 caracteres por texto, tres niveles de anidamiento y el tope de tamaño del documento.

En una actualización

{
  "sites": [
    {
      "id": 214,
      "metadata": {
        "copper": null
      }
    }
  ]
}

Los errores

Cada problema llega en errors bajo la ruta de la clave, como cualquier otro error de validación. Estos son los mensajes propios del bloque, tomando como ejemplo el primer sitio del cuerpo:

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": "exampleTranKey16",
        "md5Hash": "exampleMd5Hash16",
        "active": true,
        "action": "created"
      },
      {
        "id": 209,
        "login": "example456token789abc012def3456",
        "tranKey": null,
        "md5Hash": 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