Integraciones del sitio

Además de las integraciones del comercio, cada sitio puede tener las suyas. Viajan dentro del elemento del sitio, en sites[].integrations.

Usan el mismo vocabulario y el mismo catálogo que las del comercio —un type y un bloque settings—, pero son independientes: el mismo tipo puede existir a la vez en el comercio y en uno de sus sitios, y son dos configuraciones distintas.

Forma de un elemento

  • Name
    type
    Type
    string
    is Required
    REQUERIDO
    Description

    Tipo de integración, del catálogo de Placetopay.

  • Name
    settings
    Type
    object
    is Required
    REQUERIDO
    Description

    Configuración del proveedor para este sitio.

La colección es opcional en todos los casos, incluida la creación: un sitio sin integraciones es perfectamente válido.

Enviar id o siteId dentro de un elemento responde 422. La identidad es «el sitio que la contiene, más el tipo», y el sitio es el elemento del que cuelga la colección, nunca un campo suyo.

sites[].integrations

{
  "sites": [
    {
      "id": 214,
      "integrations": [
        {
          "type": "kount",
          "settings": {
            "sandbox": false,
            "website": "ACME_STORE",
            "merchant": "201001"
          }
        }
      ]
    }
  ]
}

Unicidad por sitio

Un tipo no puede repetirse dentro del mismo sitio: dos elementos con el mismo type en un sitio responden 422.

En cambio, el mismo tipo en dos sitios distintos es perfectamente legal, y son dos configuraciones independientes. Cada sitio tiene su propio espacio de integraciones.

El bloque settings

Se valida igual que el del comercio: una clave que el catálogo no declara para ese tipo responde 422 nombrándola, y las claves condicionales se evalúan contra las demás claves del mismo bloque.

A diferencia de los medios de pago del sitio, aquí el bloque settings se reemplaza entero. Una clave que estaba guardada y no reenvías desaparece. Para cambiar un solo valor, envía el bloque completo.

Es la misma semántica que las integraciones del comercio. La diferencia con los medios de pago —que fusionan— es intencional y merece una comprobación consciente cada vez que envías una actualización.

El límite de tamaño del bloque es propio del sitio y no cuenta contra el del comercio.

El efecto del tipo notifier

Una integración de tipo notifier reescribe la URL de notificación del sitio con una dirección derivada del servicio de notificaciones de Placetopay. Es el efecto lateral más importante de esta colección.

Tres consecuencias que conviene conocer, porque ninguna se puede devolver como error:

  1. Depende solo del tipo. Un notifier con enabled: false reescribe la URL igual que uno habilitado. Basta con que el elemento exista.
  2. Gana sobre lo que envíes en el mismo cuerpo. Si en ese mismo PUT envías sites[].integration.notificationUrl, ese valor se descarta y prevalece la URL derivada.
  3. Una edición manual posterior la cambia. Si alguien guarda ese sitio desde el back office, la URL pasará a derivarse de otra forma y apuntará a otro destino.

Si tu integración depende de recibir notificaciones de transacción en una URL propia, no envíes un notifier a ese sitio.

Comportamiento en una actualización

La colección es upsert-only, como todas: una integración que el cuerpo no nombra sobrevive intacta, y no hay forma de eliminar una desde este contrato.

Escribir una integración no marca el sitio

Un sitio puede aparecer como unchanged en el resultado mientras sus integraciones aparecen como created o updated. Son elementos independientes y cada uno informa de lo que realmente le pasó.

Los medios de pago del sitio son la excepción: escribir uno sí marca el sitio como modificado.

El resultado

Cuando un sitio escribe integraciones, su entrada en result.sites[] incluye una clave integrations con la misma forma que publica el comercio.

  • Name
    type
    Type
    string
    is Required
    REQUERIDO
    Description

    El tipo de la integración.

  • Name
    id
    Type
    integer
    is Required
    REQUERIDO
    Description

    Identificador con el que quedó registrada.

  • Name
    action
    Type
    string
    is Required
    REQUERIDO
    Description

    created, updated o unchanged.

Nunca incluye settings. La clave aparece solo en los sitios que escribieron alguna integración.

result

{
  "result": {
    "merchantId": 18,
    "sites": [
      {
        "id": 214,
        "login": "aabbccdd1234567890aabbccdd123456",
        "tranKey": null,
        "active": true,
        "action": "unchanged",
        "integrations": [
          {
            "type": "kount",
            "id": 77,
            "action": "created"
          }
        ]
      }
    ]
  }
}

¿Qué sigue?