Integraciones

La colección integrations registra las integraciones del comercio con proveedores externos: antifraude, notificaciones, mensajería y otros servicios que el comercio use.

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.

Forma de un elemento

Name
type
Type
string
is Required
REQUERIDO
Description
Tipo de integración. Debe ser uno de los que reconoce el catálogo de Placetopay.
Name
settings
Type
object
is Required
REQUERIDO
Description
Configuración del proveedor. Las claves admitidas dependen del type.

integrations

{
  "integrations": [
    {
      "type": "kount",
      "settings": {
        "sandbox": false,
        "website": "ACME",
        "merchant": "201000"
      }
    }
  ]
}

Cómo se identifica una integración

Una integración se direcciona por su type. No hay identificadores numéricos en este contrato: enviar id o siteId dentro de un elemento responde 422.

Esto significa que un comercio tiene como mucho una integración de cada tipo, y que para modificarla basta con volver a enviar ese mismo type con la configuración nueva.

Tipos disponibles

Los tipos y las claves que admite cada uno vienen del catálogo de integraciones de Placetopay. Estos son algunos de los más habituales:

`type`	Para qué sirve
`paygate`	Conexión con la pasarela de pagos
`kount`	Servicio antifraude
`notifier`	Envío de notificaciones de transacción
`sms`	Envío de mensajes de texto

La lista completa es más amplia y puede crecer. Si necesitas un tipo que no aparece aquí, consúltalo con tu contacto en Placetopay antes de enviarlo: un tipo que el catálogo no reconoce responde 422.

El bloque `settings`

Cada tipo declara qué claves acepta y de qué forma. La validación es estricta en ambas direcciones:

Una clave que el catálogo no declara para ese tipo responde 422 nombrándola. No se descarta en silencio.
Una clave obligatoria que falte responde 422.
Algunas claves son condicionales: se vuelven obligatorias según el valor de otra clave del mismo bloque.

Que una clave desconocida se rechace en lugar de ignorarse es deliberado, porque Onboarding nunca devuelve el contenido de settings. Si se descartara en silencio, un error de escritura en el nombre de una clave sería indetectable para siempre.

El contenido se guarda exactamente como lo envías: no se recortan espacios ni se convierten las cadenas vacías en null. Esto importa cuando una credencial tiene espacios significativos o cuando el propio catálogo usa la cadena vacía como valor por defecto.

Los sub-objetos que el catálogo deja abiertos —por ejemplo, cabeceras HTTP personalizadas— siguen aceptando cualquier clave.

Comportamiento en una actualización

La colección es upsert-only: una integración que el cuerpo no nombra sobrevive intacta.

Si borrara por omisión, cada actualización del comercio obligaría a retransmitir todas las credenciales de todos los proveedores, y olvidar una causaría una incidencia con un servicio externo.

Dentro de una integración que sí nombras, el bloque settings se reemplaza entero. Una clave que estaba guardada y no reenvías desaparece. Si solo quieres cambiar un valor, envía el bloque completo con ese valor modificado.

Enviar "integrations": [] responde 422 en lugar de borrar todas las integraciones. No existe forma de eliminar una integración desde este contrato.

El orden no importa

Los elementos se ordenan por type antes de compararse con una petición anterior. Reconstruir el cuerpo desde un diccionario —donde el orden puede variar entre ejecuciones— sigue produciendo un reintento válido y no un conflicto de idempotencia.

Cambiar el valor de una clave de settings sí produce un contenido distinto, y por tanto un 409 si reutilizas la clave. Ver Idempotencia.

El resultado

Cuando el proceso termina bien, result.integrations trae una entrada por cada integración procesada.

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
Qué ocurrió: created, updated o unchanged.

El resultado nunca incluye settings: viajaría al webhook, y ahí podría contener credenciales de proveedores.

result

{
  "result": {
    "merchantId": 18,
    "integrations": [
      {
        "type": "kount",
        "id": 42,
        "action": "created"
      }
    ]
  }
}

Si el cuerpo no trae la colección, result no incluye la clave integrations.

¿Qué sigue?

Medios de pago
Integraciones del sitio — la colección equivalente dentro de un sitio
Referencia de la API — las claves que admite cada tipo de integración
Actualizar un comercio