Una tienda propia o un ERP es aquella en la que no hay un plug-in listo, de modo que su desarrollador conecta el configurador con el carrito. La regla que sustenta todo lo que sigue cabe en una frase: un precio que envió el navegador nunca debe convertirse en el precio del carrito. Su servidor lo verifica antes con CutOptim.

CutOptim no cobra ningún pago ni aloja ninguna tienda; el carrito, el pago en caja y el cobro siguen siendo suyos. Todavía no hay SDK. La referencia de la API del configurador enumera cada ruta, código de error y límite, con un documento OpenAPI 3.1; esta página, la página de pedidos y el código de referencia guían la integración paso a paso.

Dos claves

• La clave publicable está en su página para la integración. Solo puede hacer lo que hace un comprador, y solo desde los dominios que usted indicó para ella.
• La clave secreta es para su servidor y nunca se coloca en una página. Se envía como Authorization: Bearer <key> al servicio, por defecto https://cfg.cutoptim.com. Envíe siempre Content-Type: application/json en un POST.

Paso 1: verificar el presupuesto antes del carrito

Cuando el cliente hace el pedido, su página recibe un evento cutoptim:order con un token de presupuesto. Envíe el token a su servidor y, desde allí:

curl -X POST https://cfg.cutoptim.com/cfg/v1/quote/verify \
  -H "Authorization: Bearer $CFG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"quoteToken":"<token from the page>"}'

La respuesta es 200 con {"valid": true, "redeemed": false, "claims": {...}} o {"valid": false, "reason": "..."}. Un rechazo sigue siendo un 200, así que lea valid. Trate un tiempo de espera agotado, un 401, un 500 o un cuerpo ilegible como no verificado y rechace la línea. Después compare las claims con su línea de carrito: el tenant es el suyo, la moneda es la del carrito, la caducidad está en el futuro y el hash del presupuesto es igual al hash del presupuesto que mostró su página. El código de referencia incluye la función que calcula ese hash.

Una comprobación local de la forma, el tenant y la caducidad del token es más barata pero no puede probar la firma, porque la clave de firma no se entrega. Úsela solo como comprobación previa.

Paso 2: comprobar el pedido

Verificar el presupuesto demuestra que la promesa de precio es genuina. No demuestra a qué pedido se refiere el navegador. Antes de almacenar o servir según un id de pedido, consúltelo en su servidor con GET /cfg/v1/orders/{id} y su clave secreta. Devuelve el hash del plan, el hash del presupuesto, el estado, la moneda y los tres totales en unidades menores, y ningún dato personal. Compárelos con lo que verificó.

Paso 3: recibir el webhook

Configure un webhook como se describe en la página de pedidos. Su receptor:

1. lee el cuerpo sin procesar antes de analizarlo;
2. lee la cabecera CutOptim-Signature, t=<unix seconds>,v1=<hex> (puede haber dos valores v1 mientras se rota un secreto);
3. recalcula HMAC-SHA256(secret, "<t>.<raw body>"), compara en tiempo constante y rechaza una marca de tiempo a más de unos cinco minutos de distancia;
4. reclama el id de evento de CutOptim-Event-Id antes de hacer ningún trabajo e ignora un id que ya ha tratado;
5. ignora los tipos de evento que no conoce y responde 2xx, para que el emisor no reintente en vano.

Usted obtiene el secreto del receptor con POST /cfg/v1/admin/webhooks/{id}/secret y su clave secreta. Mantenga los secretos en su entorno, nunca en una página, un repositorio ni un registro.

Código de referencia

Dos ejemplos pequeños y sin dependencias muestran los tres pasos. Son código para leer y copiar, no un servicio alojado:

• Node 18 o posterior: cutoptim-verify.mjs y example-server.mjs.
• PHP 7.4 o posterior: CutOptimVerify.php y example-webhook.php.

Sus secretos son marcadores de posición. El almacén de duplicados en memoria de los ejemplos es un sustituto: en producción, conserve los id de evento tratados en su base de datos y reclame un id en la misma transacción que registra el pedido.

Los mismos pasos, con las solicitudes y respuestas exactas, están en la referencia: Tienda propia o ERP.

Rotación de claves

Una clave o un secreto de webhook puede rotarse con solapamiento, de modo que el antiguo siga funcionando durante un tiempo determinado mientras usted despliega el nuevo. Durante una rotación de webhook, una entrega lleva dos firmas v1 durante siete días, y aceptar cualquiera de ellas le permite cambiar sin tiempo de inactividad. Los botones de la consola para la rotación con solapamiento todavía no están construidos; la consola puede crear y revocar claves.

Otras formas de recibir pedidos

Para WooCommerce use el plug-in. Si solo necesita planes de corte dentro de su propio software, sin pantalla de cliente integrada, eso es el Engine API.