API para desarrolladores

Integra el desistimiento desde tu propio sistema: autenticación, endpoints, ejemplos con curl, idempotencia, webhooks y errores.

Esta parte es para el equipo técnico de tu tienda. Con la API puedes registrar desistimientos desde tu propio sistema (por ejemplo, desde el área de cliente de una tienda a medida) y consultar tus solicitudes para llevarlas a tu ERP o a tu back-office. Aquí solo documentamos lo que existe hoy.

Conceptos básicos

URL base
https://lexplans.com/desistimiento/api/v1/index.php
Rutas
El recurso va después de index.php: …/index.php/desistimiento, …/index.php/solicitudes, etc.
Formato
JSON en UTF-8, en la petición y en la respuesta. Todas las respuestas llevan "ok": true o "ok": false con un código en "error".
Fechas
En UTC, formato ISO 8601 (2026-11-16T10:24:51Z). El sello de tiempo legal lo pone siempre el servidor, nunca el cliente.
Plan
El registro de solicitudes (POST /desistimiento) funciona en todos los planes, porque es lo que usa el propio botón. La consulta de solicitudes y los webhooks son funciones de Pro.

Autenticación y claves

Cada tienda tiene un par de claves, que encontrarás en Instalación:

Clave pública pk_…

Identifica tu tienda. Es pública por diseño (va en el script de tu web). Se envía en la cabecera X-Public-Key.

Clave secreta sk_…

Solo para llamadas de servidor a servidor, en la cabecera X-Secret-Key. Se muestra una vez al crear la cuenta. Nunca la pongas en el navegador ni en una app.

En Instalación Claves de acceso puedes:

  • Regenerar la clave secreta: la anterior deja de valer al instante; la pública no cambia y tu botón sigue funcionando.
  • Rotar ambas claves: cambian la pública y la secreta. Tendrás que actualizar la clave en el script de tu web (o en el plugin), o el botón dejará de funcionar.

Cada regeneración queda registrada en la auditoría.

POST /desistimiento: registrar una solicitud

Registra la declaración de desistimiento de un cliente. Es el mismo endpoint que usan el botón y el plugin. En cuanto responde, la solicitud está registrada con su sello de tiempo, se ha intentado enviar el email de confirmación al cliente y se te ha avisado.

Cabeceras
Content-Type
application/json
X-Public-Key
Tu clave pública. También se admite como public_key en el cuerpo.
X-Idempotency-Key
Opcional, recomendada. Ver Idempotencia. También se admite como idempotency_key en el cuerpo.
Cuerpo (JSON)
numero_pedido
Obligatorio. Texto.
email_cliente
Obligatorio. Email válido. Ahí se envía el acuse.
tipo
total (por defecto) o parcial.
articulos
Obligatorio si el tipo es parcial. En total, si va vacío se guarda «Pedido completo».
motivo
Opcional, siempre. Nunca lo hagas obligatorio en tu formulario.
meta
Objeto opcional con datos de contexto. Solo se guardan estas claves: lang, moneda, pedido, email, origen, campania, ref, importe, plataforma, verificado y fecha_entrega. No forman parte de la declaración sellada.
Petición
curl -X POST "https://lexplans.com/desistimiento/api/v1/index.php/desistimiento" \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: pk_live_TU_CLAVE_PUBLICA" \
  -H "X-Idempotency-Key: 7f1c2a90-3b4d-4e5f-8a6b-1c2d3e4f5a6b" \
  -d '{
    "numero_pedido": "ORD-12345",
    "email_cliente": "cliente@correo.com",
    "tipo": "parcial",
    "articulos": "Zapatillas Trail XT Pro, talla 42",
    "motivo": null,
    "meta": { "plataforma": "api", "verificado": "1", "fecha_entrega": "2026-11-10" }
  }'
Respuesta 200
{
  "ok": true,
  "id": 1842,
  "referencia": "…",
  "numero_pedido": "ORD-12345",
  "tipo": "parcial",
  "timestamp_utc": "2026-11-16T10:24:51Z",
  "email_estado": "enviado",
  "idempotente": false,
  "token_seguimiento": "…"
}
  • timestamp_utc es la fecha y hora legal de presentación.
  • email_estado indica si el acuse al cliente se envió (enviado) o falló (fallido). Un fallo del email nunca anula el registro.
  • Con token_seguimiento el cliente puede consultar su solicitud en https://lexplans.com/desistimiento/seguimiento/index.php?t=TOKEN.

Idempotencia: reintentar sin duplicar

Si repites una petición con la misma clave de idempotencia, la API no crea una solicitud nueva: devuelve la original con "idempotente": true. Así puedes reintentar con tranquilidad ante un corte de red o un tiempo de espera agotado.

  • Genera la clave una vez por cada intento de desistimiento del cliente (por ejemplo, un UUID al mostrar el formulario) y reutilízala en los reintentos.
  • Si quieres que un mismo pedido y email no puedan duplicarse nunca, usa una clave estable derivada de ambos (por ejemplo, un hash del email y el número de pedido). Es lo que hace el plugin de WordPress.
  • La clave es única por tienda.

GET /solicitudes: consultar tus solicitudes

Devuelve las solicitudes de tu tienda, de la más reciente a la más antigua. Requiere las dos claves.

Parámetros (opcionales)
desde, hasta
Fechas AAAA-MM-DD de presentación.
grupo
abiertos (recibidas y en tramitación) o cerrados (reembolsadas y rechazadas).
limite
De 1 a 500. Por defecto, 100.
Petición
curl "https://lexplans.com/desistimiento/api/v1/index.php/solicitudes?desde=2026-11-01&hasta=2026-11-30&grupo=abiertos&limite=100" \
  -H "X-Public-Key: pk_live_TU_CLAVE_PUBLICA" \
  -H "X-Secret-Key: sk_live_TU_CLAVE_SECRETA"
Respuesta 200
{
  "ok": true,
  "total": 1,
  "solicitudes": [
    {
      "referencia": "…",
      "numero_pedido": "ORD-12345",
      "tipo": "parcial",
      "email_cliente": "cliente@correo.com",
      "articulos": "Zapatillas Trail XT Pro, talla 42",
      "motivo": null,
      "estado": "en_tramitacion",
      "timestamp_utc": "2026-11-16T10:24:51Z",
      "email_estado": "enviado",
      "fecha_reembolso": null,
      "motivo_rechazo": null,
      "token_seguimiento": "…",
      "meta": { "plataforma": "api", "verificado": "1" },
      "hash_actual": "…"
    }
  ]
}

Los estados posibles son recibida, en_tramitacion, reembolso_emitido y rechazada (los cambia el comercio desde el panel). hash_actual es el eslabón de la cadena de integridad de tus registros.

GET /config y GET /salud

GET /config?pk=TU_CLAVE&lang=es devuelve la configuración pública que usa el botón: nombre de la tienda, plazo en días, idioma efectivo e idiomas disponibles, personalización y textos legales. Solo la necesitas si construyes tu propio formulario y quieres reutilizar los textos. Cada llamada desde un navegador registra el dominio de origen (es como el panel detecta la instalación).

GET /salud responde si el servicio está operativo. Útil para tu monitorización.

Webhooks

Con Pro, LexPlans puede avisar a tu sistema en el momento en que ocurre algo. Configura la URL (solo HTTPS) en Ajustes Webhook; al guardarla verás el secreto de firma.

desistimiento.creado
Un cliente ha registrado una solicitud. Datos: id, referencia, numero_pedido, tipo, email_cliente, estado, timestamp_utc, token_seguimiento.
solicitud.actualizada
Ha cambiado el estado. Datos: id, referencia, numero_pedido, estado, motivo_rechazo, fecha_reembolso.
Ejemplo de envío
POST https://tuweb.com/webhooks/desistimiento
Content-Type: application/json
X-Desist-Event: desistimiento.creado
X-Desist-Signature: sha256=…

{
  "evento": "desistimiento.creado",
  "enviado_en": "2026-11-16T10:24:52+00:00",
  "tienda": "Mi Tienda",
  "datos": {
    "id": 1842, "referencia": "…", "numero_pedido": "ORD-12345", "tipo": "parcial",
    "email_cliente": "cliente@correo.com", "estado": "recibida",
    "timestamp_utc": "2026-11-16T10:24:51Z", "token_seguimiento": "…"
  }
}

Verifica siempre la firma de la cabecera X-Desist-Signature antes de fiarte del contenido: es sha256= seguido del HMAC-SHA256 del cuerpo crudo con tu secreto.

Verificación en PHP
<?php
$cuerpo  = file_get_contents('php://input');          // cuerpo CRUDO, sin decodificar
$secreto = 'EL_SECRETO_DE_FIRMA_DE_TU_PANEL';         // Ajustes > Webhook
$firma   = $_SERVER['HTTP_X_DESIST_SIGNATURE'] ?? '';
$esperada = 'sha256=' . hash_hmac('sha256', $cuerpo, $secreto);

if (!hash_equals($esperada, $firma)) { http_response_code(401); exit; }

$evento = json_decode($cuerpo, true);
// $evento['evento'] = 'desistimiento.creado' | 'solicitud.actualizada'
http_response_code(200);

Los webhooks se envían una sola vez, en el momento del evento, sin reintentos. Si tu servidor está caído, ese aviso se pierde. Usa GET /solicitudes de vez en cuando para conciliar.

Errores y límites

401 no_autorizado
Clave pública desconocida, o par de claves incorrecto en /solicitudes. Queda registrado como intento denegado.
404 no_encontrado
El recurso no existe (revisa la ruta tras index.php).
405 metodo_no_permitido
Método HTTP equivocado (por ejemplo, GET en /desistimiento).
422 validacion
Faltan datos o no son válidos. El objeto campos indica cuáles, por ejemplo {"email_cliente": "email válido requerido"}.
429 demasiadas_peticiones
Has superado el límite de peticiones por minuto. Espera lo que indique la cabecera Retry-After (en segundos) y reintenta con la misma clave de idempotencia.
500 interno
Error de nuestro lado. Reintenta con la misma clave de idempotencia y, si persiste, avísanos.

Los endpoints que usa el navegador (/desistimiento, /config, /salud) admiten llamadas desde cualquier origen (CORS). /solicitudes no: está pensado solo para tu servidor.

¿No encuentras lo que buscas? Escríbenos a hola@lexplans.com y te ayudamos.