REST API

REST API en el namespace polski/v1/. Gestione ajustes, casillas legales, páginas legales y la búsqueda de productos.

Autenticación

La API requiere autenticación para los endpoints que modifican datos (POST, PUT, DELETE). El endpoint de búsqueda (/search) es de acceso público.

Métodos de autenticación admitidos:

Application Passwords (WordPress 5.6+) - recomendado
Cookie + nonce - para solicitudes desde el panel de administración
Basic Auth (con el plugin Basic Auth) - solo para desarrollo

Permiso requerido: manage_woocommerce (por defecto, los roles Administrador y Gestor de tienda).

Endpoints

GET /polski/v1/settings

Obtiene todos los grupos de ajustes del plugin.

Permisos: manage_woocommerce

Ejemplo de solicitud:

curl -u admin:XXXX-XXXX-XXXX-XXXX \
  "https://yourstore.com/wp-json/polski/v1/settings"

Ejemplo de respuesta:

{
  "groups": [
    {
      "id": "general",
      "label": "General settings",
      "description": "Basic plugin configuration"
    },
    {
      "id": "compliance",
      "label": "Legal requirements",
      "description": "EU and Polish law requirements settings"
    },
    {
      "id": "storefront",
      "label": "Storefront modules",
      "description": "Store extension modules"
    },
    {
      "id": "checkout",
      "label": "Checkout and orders",
      "description": "Checkout and order process settings"
    }
  ]
}

GET /polski/v1/settings/{group}

Obtiene los ajustes de un grupo seleccionado.

Parámetros de URL:

Parámetro	Tipo	Descripción
`group`	string	ID del grupo de ajustes

Permisos: manage_woocommerce

Ejemplo de solicitud:

curl -u admin:XXXX-XXXX-XXXX-XXXX \
  "https://yourstore.com/wp-json/polski/v1/settings/compliance"

Ejemplo de respuesta:

{
  "group": "compliance",
  "settings": {
    "omnibus_enabled": true,
    "omnibus_days": 30,
    "gpsr_enabled": true,
    "withdrawal_enabled": true,
    "withdrawal_days": 14,
    "dsa_enabled": true,
    "ksef_enabled": false,
    "greenwashing_enabled": true
  }
}

POST /polski/v1/settings/{group}

Actualiza los ajustes de un grupo seleccionado.

Permisos: manage_woocommerce

Ejemplo de solicitud:

curl -X POST \
  -u admin:XXXX-XXXX-XXXX-XXXX \
  -H "Content-Type: application/json" \
  -d '{"omnibus_days": 30, "withdrawal_days": 14}' \
  "https://yourstore.com/wp-json/polski/v1/settings/compliance"

Ejemplo de respuesta:

{
  "updated": true,
  "group": "compliance",
  "changes": {
    "omnibus_days": 30,
    "withdrawal_days": 14
  }
}

GET /polski/v1/checkboxes

Obtiene una lista de todas las casillas legales (finalización de compra, registro, contacto).

Permisos: manage_woocommerce

Ejemplo de respuesta:

{
  "checkboxes": [
    {
      "id": 1,
      "label": "I accept the store terms and conditions",
      "required": true,
      "location": "checkout",
      "enabled": true,
      "position": 10,
      "legal_page_id": 45
    },
    {
      "id": 2,
      "label": "I have read the privacy policy",
      "required": true,
      "location": "checkout",
      "enabled": true,
      "position": 20,
      "legal_page_id": 47
    }
  ],
  "total": 2
}

GET /polski/v1/checkboxes/stats

Obtiene estadísticas de aceptación de las casillas.

Permisos: manage_woocommerce

Ejemplo de respuesta:

{
  "stats": [
    {
      "checkbox_id": 1,
      "label": "I accept the store terms and conditions",
      "total_shown": 1250,
      "total_accepted": 1180,
      "acceptance_rate": 94.4
    }
  ]
}

GET /polski/v1/checkboxes/{id}

Obtiene los detalles de una casilla individual.

Parámetros de URL:

Parámetro	Tipo	Descripción
`id`	int	ID de la casilla

Permisos: manage_woocommerce

Ejemplo de respuesta:

{
  "id": 1,
  "label": "I accept the store terms and conditions",
  "required": true,
  "location": "checkout",
  "enabled": true,
  "position": 10,
  "legal_page_id": 45,
  "created_at": "2025-01-15T10:30:00",
  "updated_at": "2025-06-01T14:22:00",
  "stats": {
    "total_shown": 1250,
    "total_accepted": 1180,
    "acceptance_rate": 94.4
  }
}

PUT /polski/v1/checkboxes/{id}

Actualiza una casilla.

Permisos: manage_woocommerce

Ejemplo de solicitud:

curl -X PUT \
  -u admin:XXXX-XXXX-XXXX-XXXX \
  -H "Content-Type: application/json" \
  -d '{"label": "I accept the terms", "required": true}' \
  "https://yourstore.com/wp-json/polski/v1/checkboxes/1"

GET /polski/v1/legal-pages

Obtiene una lista de las páginas legales (términos y condiciones, política de privacidad, etc.).

Permisos: manage_woocommerce

Ejemplo de respuesta:

{
  "pages": [
    {
      "id": 45,
      "type": "terms",
      "title": "Store terms and conditions",
      "status": "publish",
      "url": "https://yourstore.com/terms/",
      "last_modified": "2025-06-01T14:00:00",
      "word_count": 3200
    },
    {
      "id": 47,
      "type": "privacy",
      "title": "Privacy policy",
      "status": "publish",
      "url": "https://yourstore.com/privacy-policy/",
      "last_modified": "2025-05-15T09:30:00",
      "word_count": 2800
    }
  ],
  "total": 2
}

POST /polski/v1/legal-pages/generate

Crea las cuatro páginas legales (términos, privacidad, devoluciones, reclamaciones) como borradores vacíos. Una página que ya existe se reutiliza, nunca se duplica ni se sobrescribe. Los borradores no contienen texto legal. La petición no admite parámetros y no hace nada mientras el módulo Páginas legales está desactivado.

Permisos: manage_woocommerce

Ejemplo de petición:

curl -X POST \
  -u admin:XXXX-XXXX-XXXX-XXXX \
  "https://yourstore.com/wp-json/polski/v1/legal-pages/generate"

Respuesta: la misma lista que GET /polski/v1/legal-pages, con las páginas nuevas en estado draft.

GET /polski/v1/search

Búsqueda de productos (endpoint público).

Parámetros de query:

Parámetro	Tipo	Requerido	Descripción
`q`	string	Sí	Frase de búsqueda
`limit`	int	No	Límite de resultados (por defecto 8)
`cat`	int	No	ID de categoría

Permisos: público (no requiere autenticación)

Ejemplo de solicitud:

curl "https://yourstore.com/wp-json/polski/v1/search?q=shoes&limit=5"

Ejemplo de respuesta:

{
  "results": [
    {
      "id": 456,
      "title": "Nike Sports Shoes",
      "url": "https://yourstore.com/product/nike-sports-shoes/",
      "image": "https://yourstore.com/wp-content/uploads/nike-shoes.jpg",
      "price_html": "<span class=\"amount\">299.00&nbsp;PLN</span>",
      "category": "Footwear",
      "in_stock": true,
      "rating": 4.8
    }
  ],
  "total": 1,
  "query": "shoes"
}

POST /polski/v1/wizard/complete

Marca el asistente de configuración como completado.

Permisos: manage_woocommerce

Parámetros del body:

Parámetro	Tipo	Requerido	Descripción
`steps_completed`	array	Sí	Lista de pasos completados

Ejemplo de solicitud:

curl -X POST \
  -u admin:XXXX-XXXX-XXXX-XXXX \
  -H "Content-Type: application/json" \
  -d '{"steps_completed": ["company_info", "legal_pages", "checkboxes", "compliance"]}' \
  "https://yourstore.com/wp-json/polski/v1/wizard/complete"

Ejemplo de respuesta:

{
  "completed": true,
  "completed_at": "2025-06-15T12:00:00",
  "steps": {
    "company_info": true,
    "legal_pages": true,
    "checkboxes": true,
    "compliance": true
  }
}

Códigos de respuesta HTTP

Código	Descripción
200	Éxito
201	Recurso creado (POST)
400	Solicitud incorrecta (parámetros faltantes)
401	No autenticado
403	Permisos insuficientes
404	Recurso no encontrado
500	Error del servidor

Filtrado de respuestas

Cada endpoint admite un filtro de WordPress que permite modificar la respuesta:

add_filter('polski/rest/settings_response', function (array $response, WP_REST_Request $request): array {
    // Modificar la respuesta
    return $response;
}, 10, 2);

Rate limiting

La API no implementa su propio rate limiting. Para los endpoints públicos se recomienda usar un plugin o una configuración del servidor (por ejemplo, Cloudflare, rate limiting de Nginx).

Reportar problemas: github.com/wppoland/polski/issues

Esta página tiene únicamente carácter informativo y no constituye asesoramiento legal. Consulte a un abogado antes de la implementación. Polski for WooCommerce es software de código abierto (GPLv2) proporcionado sin garantía.