Kowal B2B API — documentación REST completa

Versión del contrato: V1 · Fuente de verdad: Kowal_B2BApi/etc/webapi.xml · Destinatarios: administradores de tiendas, partners de implementación y equipos que integran ERP, PIM, WMS o sistemas de compra.

1. Finalidad y límites de la API

Kowal B2B API expone datos y procesos B2B que funcionan en Magento 2: empresas, catálogo y precios individuales, compras rápidas, documentos, límite de crédito comercial, aprobaciones, RFQ y colas de integración. Es una REST API para integraciones de sistemas; no sustituye los endpoints estándar de Magento para catálogo, carrito, checkout y cuenta de cliente.

El documento describe únicamente los endpoints expuestos actualmente por el módulo. No promete operaciones que el contrato V1 no ofrece, por ejemplo creación de pedidos por REST, CRUD de tarifas o edición de configuración de website.

2. Obtención de acceso y normas de colaboración

2.1. Proceso de puesta en marcha de la integración

1. El integrador comunica al administrador de la tienda el objetivo de la integración, entorno (pruebas/producción), sistema fuente, alcance de datos y lista de áreas API requeridas.
2. El administrador crea o configura la integración Magento, le asigna permisos ACL mínimos y transmite por un canal seguro: baseUrl, token, websiteId, companyId cuando proceda, moneda y datos de prueba.
3. El integrador ejecuta la prueba GET /V1/kowal-b2b/websites/:websiteId/config y después pruebas funcionales en el entorno de pruebas.
4. Antes de producción, ambas partes acuerdan el calendario de sincronización, tamaño máximo de datos, retry, propietario de los datos y método de notificación de errores.
5. Los tokens se guardan únicamente en un vault de secretos; el administrador los rota o revoca ante un cambio de proveedor, usuario o alcance de integración.

2.2. Responsabilidades

No se debe usar el token de administrador en una aplicación cliente ni compartir un único token entre sistemas independientes. Cada integración debe tener su propio token y solo las ACL necesarias.

2.3. Permisos

Magento verifica el token Bearer y las ACL asignadas al usuario administrativo o a la integración. Los endpoints B2B requieren uno de los siguientes grupos de permisos:

El alcance debe derivarse de la finalidad de la integración. Ejemplo: un sistema de compra suele necesitar products, prices, catalog_permissions, quick_order y quotes; un ERP que gestiona documentos — documents y, si es propietario de la sincronización, system_integrations.

3. Convenciones técnicas

Dirección, cabeceras y parámetros

La dirección base tiene el formato https://b2b.example.com/rest/V1. Todas las rutas posteriores en el documento se indican desde /V1; la dirección completa del endpoint es BASE_URL + ruta.

Authorization: Bearer Accept: application/jsonContent-Type: application/json

La API usa JSON. Los nombres en URL son camelCase (websiteId, companyId) y los campos JSON corresponden a los nombres de parámetros de los contratos Magento. :companyId, :quoteId, :sku, etc. son parámetros de ruta. En los ejemplos, ? indica un parámetro opcional.

websiteId es obligatorio en operaciones dependientes del canal de venta. Debe indicar un website existente con B2B activado. companyId indica una empresa que debe tener una relación activa con ese website cuando la operación funciona en su contexto. La API no selecciona website ni empresa predeterminados.

Request body e idempotencia

Magento serializa el objeto DTO bajo el nombre del parámetro del método: la mayoría de escrituras acepta {'request': {...}}; la creación de empresa usa {'company': {...}}; el batch de empresas — {'companies': [...]}. Los endpoints con argumentos simples aceptan campos sin wrapper, por ejemplo {'websiteId': 1, 'currency': 'PLN', 'items': [...]}.

La cabecera Idempotency-Key (máx. 128 caracteres) actualmente está soportada por POST /companies: un reintento con la misma clave devolverá la empresa creada previamente. Para un job de integración usa el campo request.idempotencyKey. No asumas idempotencia automática de otros endpoints de escritura; reinténtalos solo después de determinar el estado de la operación.

Respuestas y errores

Las respuestas de éxito son objetos o arrays de contratos Magento. Los campos devueltos por los objetos pueden ampliarse de forma compatible; la integración debe ignorar campos desconocidos. Un error de negocio puede contener:

{ 'code': 'b2b.company.not_assigned_to_website', 'message': 'B2B company is not assigned to website.', 'website_id': 1, 'trace_id': 'request-correlation-id', 'details': {'company_id': 10}, 'field_errors': []}

No registres tokens, datos personales completos ni secretos de configuración. La incidencia al equipo de la tienda debe incluir hora, método, ruta sin secretos, estado HTTP, trace_id y payload anonimizado.

4. Esquemas de datos de entrada

Los siguientes esquemas son comunes para los endpoints de referencia. Un campo sin ? es obligatorio por contrato; ? indica un valor opcional. Los campos metadata, config, configuration y payload son objetos JSON.

5. Referencia de endpoints

En las tablas, ACL indica el recurso mínimo de permiso Magento. Resultado define el tipo de respuesta de éxito.

5.1. Websites y configuración

5.2. Empresas y usuarios de empresa

5.3. Productos, precio y visibilidad del catálogo

5.4. Importación y exportación de archivos

5.5. Pedido rápido y listas de compra

5.6. Documentos y archivos

5.7. Límite de crédito comercial y condiciones de pago

5.8. Workflow de aprobación

5.9. Contexto B2B de pedidos

5.10. RFQ y ofertas comerciales

5.11. Perfiles y jobs de integración

6. Ejemplos de llamadas

export BASE_URL='https://b2b.example.com/rest/V1'export TOKEN='token-przekazany-przez-administratora'export WEBSITE_ID=1 COMPANY_ID=10 SKU='B2B-SKU-001' CURRENCY='PLN'# Test dostępu i konfiguracji kanałucurl -sS '$BASE_URL/kowal-b2b/websites/$WEBSITE_ID/config' \ -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Cena kontraktowa firmy dla konkretnej ilościcurl -sS '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/products/$SKU/price?websiteId=$WEBSITE_ID&currency=$CURRENCY&qty=5' \ -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Walidacja koszyka po SKUcurl -sS -X POST '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/quick-order/validate' \ -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \ --data '{'websiteId':1,'currency':'PLN','items':[{'sku':'B2B-SKU-001','qty':5}]}'# Utworzenie RFQcurl -sS -X POST '$BASE_URL/kowal-b2b/quotes' \ -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \ --data '{'request':{'websiteId':1,'companyId':10,'customerId':25,'title':'Dostawa kwartalna','currency':'PLN','externalId':'ERP-RFQ-2026-001'}}'

7. Escenarios de integración recomendados

Compra por SKU

1. Lee la configuración del website y guarda el websiteId, companyId y la moneda proporcionados.
2. Usa quick order para la validación conjunta de SKU, cantidad, visibilidad y disponibilidad.
3. Para las posiciones aceptadas, obtiene el precio desde price con el qty correcto.
4. Crea un RFQ, añade posiciones y envíalas mediante submit si la compra requiere oferta.
5. Sigue el estado y el historial de RFQ; tras la aceptación, actúa según el proceso de pedido Magento acordado, porque V1 no expone endpoint de creación de order.

Documentos y liquidaciones

1. Obtén la lista de documentos de la empresa, filtrando opcionalmente por documentType.
2. Para el documento seleccionado, obtén los metadatos y la lista de archivos; la ruta del archivo no es automáticamente una URL pública — acuerda con el administrador de la tienda la forma de descargar el binario.
3. Consulta el estado del límite antes del proceso de compra; solo una integración con ACL credit_limits puede gestionarlo.

Operaciones asíncronas

1. Guarda el perfil de integración y los mapeos de identificadores.
2. Publica un job con idempotencyKey de negocio y conserva jobId.
3. Consulta el job y sus logs/errores; llama a retry solo tras analizar el error y eliminar su causa.

8. Lista de aceptación antes de producción

• El token tiene únicamente las ACL requeridas y no es el token de administrador utilizado por la UI.
• El integrador gestiona correctamente 401, 403, 404, validación 422, conflicto 409 y timeouts.
• Cada request en contexto B2B transmite el websiteId correcto, y los datos de empresa usan el companyId correcto.
• Precios, visibilidad y disponibilidad se comprueban antes de crear el proceso de compra.
• La creación de empresa usa Idempotency-Key; los jobs de integración tienen un idempotencyKey estable en el body.
• Los logs no contienen tokens ni datos sensibles, y el procedimiento de soporte transmite trace_id.
• Las pruebas se han realizado en el entorno de pruebas con una empresa que tiene relación activa con el website B2B.

9. Compatibilidad

El contrato se versiona mediante /V1. Ampliar la respuesta con nuevos campos es compatible; el integrador debe tolerar campos desconocidos. Un cambio que elimine un campo, significado de campo o endpoint requiere una nueva versión de API. En caso de discrepancia entre el documento y la instalación operativa, prevalece el contrato activo webapi.xml de la versión correspondiente del módulo.

Instalación y configuración de Kowal B2B Suite

Este manual está destinado a la persona que ha comprado Kowal B2B Suite y debe ponerlo en marcha en una instalación existente de Magento Open Source. Guía a través de dos etapas:

1. instalación técnica — realizada por un desarrollador o administrador del servidor;
2. configuración de negocio — realizada en el panel de Magento por el administrador de la tienda.

Antes de empezar, realiza una copia de la base de datos y de los archivos de Magento. Recomendamos hacer la primera puesta en marcha en un entorno de pruebas y solo después desplegar en producción.

1. Qué recibes y qué necesitas

Kowal B2B Suite se entrega como paquete Composer kowal/metapackage-b2b-suite. Contiene módulos B2B y el theme frontend/Kowal/b2b.

Requisitos

De Kowal recibirás:

• dirección del repositorio privado Composer — en adelante REPOSITORY_URL;
• nombre de usuario o identificador de acceso — USERNAME;
• token de acceso — ACCESS_TOKEN;
• rango permitido de versiones del paquete.

No guardes el token en el repositorio Git, en tickets ni en el historial de shell compartido con otras personas.

2. Instalación técnica

Ejecuta todos los comandos en el directorio raíz de la instalación existente de Magento, como usuario con acceso a los archivos y al comando bin/magento.

2.1. Preparación

1. Asegúrate de que Magento funciona correctamente antes del cambio.
2. Guarda el estado del despliegue y realiza backup de la base de datos y de los directorios app/etc, pub/media y var.
3. En producción, activa el modo maintenance durante la actualización:

bin/magento maintenance:enable

2.2. Añadir el repositorio privado

Añade el repositorio Composer de Kowal y configura los datos de acceso recibidos.

Recibirás por correo electrónico los datos de acceso al repositorio Composer, es decir, la dirección de e-mail del cliente y el token de licencia, después de la compra. También están disponibles en el panel del cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de e-mail de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

Composer suele guardar las credenciales en el auth.json local; no añadas este archivo a Git.

2.3. Instalación del paquete

Instala la versión entregada con la licencia. Para la línea actual del paquete, el comando de ejemplo es:

composer require kowal/metapackage-b2b-suite:^0.2 --with-all-dependencies

Después de descargar las dependencias, actualiza el esquema y la configuración de Magento:

bin/magento setup:upgradebin/magento cache:clean

En modo de producción, ejecuta además:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -f pl_PL en_USbin/magento cache:flush

Usa solo los locale que están activos en la tienda. Si la instalación utiliza otro proceso de deployment, incorpora los comandos anteriores a su procedimiento estándar.

2.4. Verificación de la instalación

bin/magento module:status | grep Kowalbin/magento indexer:status

En el panel de administración debería aparecer el menú B2B y la pestaña Stores > Configuration > Kowal > B2B. Si no aparecen, comprueba el resultado de setup:upgrade, la cache y los roles ACL del usuario administrador.

2.5. Permisos de archivos PDF

Los PDF generados por B2B utilizan mPDF y directorios bajo var/, incluidos var/tmp/kowal_b2b_mpdf y var/kowal_b2b_documents. El proceso PHP debe poder crearlos y escribir en ellos. La falta de estos permisos se manifiesta como un error al generar el documento o el PDF.

Tras finalizar el despliegue en producción, desactiva maintenance:

bin/magento maintenance:disable

3. Configuración de la estructura de la tienda B2B

3.1. Website y store view

La suite funciona en el ámbito de website, no de forma global. Puedes gestionar B2C y B2B en la misma instalación de Magento, pero B2B debería funcionar en un website independiente o en un website de venta empresarial elegido de forma consciente.

1. En Stores > Settings > All Stores, crea o selecciona el website B2B, su store y su store view.
2. Recuerda el website_id: lo utilizan empresas, precios, documentos, API e integraciones.
3. En Content > Design > Configuration, asigna el theme frontend/Kowal/b2b solo al B2B store view.
4. Comprueba que las monedas activas, impuestos, métodos de envío y métodos de pago estén configurados para el mismo scope.

No asignes el theme B2B al store view B2C si no quieres cambiar su capa de presentación. La mera instalación de los módulos no activa la lógica B2B para todos los website.

3.2. Activación de B2B

1. Abre Stores > Configuration > Kowal > B2B.
2. En el conmutador de scope, elige el Website correcto.
3. En la sección General, establece Enable B2B en Yes.
4. Durante la implementación puedes activar Debug Mode; desactívalo después de las pruebas.
5. En el scope Default Config, define el periodo de retención de logs.
6. Guarda la configuración y limpia la cache.

Tras la activación, todos los store view pertenecientes a ese website se tratan como B2B. Una empresa sin relación activa con ese website no obtendrá acceso a él.

3.3. Datos del vendedor

Completa los datos de la empresa vendedora en Stores > Configuration > General > Store Information: nombre, dirección, teléfono y NIF. Se utilizan en documentos y PDF RFQ. Completa también la dirección de e-mail general del remitente en la configuración de Sales Emails y el logo de e-mail si debe aparecer en los PDF.

4. Configuración del primer cliente B2B

Aplica el siguiente orden para cada empresa. Ayuda a evitar situaciones en las que el cliente tiene cuenta, pero no ve la oferta o no puede pasar por checkout.

4.1. Empresa, personas y direcciones

1. Abre B2B > Companies y crea una empresa.
2. Introduce el nombre, NIF, identificador externo si la empresa se sincroniza con ERP, estado Active y asignación al website B2B.
3. Añade un usuario de empresa o asigna un cliente Magento existente. Asígnale el rol correcto y activa la asignación.
4. En B2B > Company Addresses, añade las direcciones de la empresa; marca la dirección de facturación y envío predeterminada para el website B2B.
5. En B2B > Company Contacts, añade un contacto principal activo con e-mail y teléfono.

La dirección de facturación y el contacto principal también se utilizan en el PDF RFQ. La falta de datos no bloquea el PDF, pero el documento será menos completo.

4.2. Roles de empresa

Concede a los usuarios solo los permisos necesarios. Una división típica es:

Prueba la cuenta de cada tipo, especialmente el permiso para realizar pedidos y aprobaciones. No utilices una cuenta común para toda la empresa.

5. Oferta, precios y checkout

5.1. Catálogo y precios

1. Asegúrate de que los productos Magento estén asignados al website B2B, activos y tengan datos MSI correctos.
2. Configura tarifas o precios contractuales para la empresa en el área B2B > Pricing (Price Lists, Price List Assignments o Contract Prices).
3. Configura las reglas de visibilidad del catálogo para la empresa según el modelo de permisos implementado y después comprueba la visibilidad en la cuenta del cliente.
4. Prueba en la cuenta de empresa: búsqueda de SKU, visibilidad del producto y precio para la cantidad 1 y para el tramo por cantidad.

El precio B2B depende de la empresa, el website, la moneda y la cantidad. Un producto visible en B2C no tiene por qué estar disponible para el cliente B2B.

5.2. Envío y pago

1. Activa los métodos de envío y pago requeridos en la configuración estándar de Magento para el B2B store view.
2. En B2B > Checkout, añade reglas de métodos disponibles para empresa/website si quieres limitar la selección.
3. Realiza una prueba de carrito con las direcciones predeterminadas de la empresa.

Si la creación de pedidos desde RFQ debe funcionar automáticamente desde el lado del administrador, la empresa debe tener direcciones predeterminadas inequívocas y un método de pago y envío activo. De lo contrario, la suite cargará los datos en el Backend Order Create nativo, donde el administrador completa los elementos faltantes.

5.3. Límites y aprobaciones

Estas funciones son opcionales, pero deberían configurarse antes de activarlas para los clientes.

1. En B2B > Credit > Payment Terms, añade plazos de pago.
2. En B2B > Credit > Credit Limits, asigna a la empresa un límite, moneda, estado y plazo de pago.
3. En B2B > Approvals > Rules, crea una regla de umbral de importe para la empresa y el website.
4. En B2B > Approvals > Approvers, asigna las personas aprobadoras.
5. Prueba el carrito por debajo y por encima del umbral y comprueba si la decisión del aprobador cambia el proceso posterior.

6. Documentos, PDF y RFQ

6.1. Documentos Magento

En Stores > Configuration > Kowal > B2B > Documents, elige la fuente de documentos y decide qué documentos deben generarse automáticamente: confirmaciones de pedidos, facturas, albaranes y abonos. Define también el estado de destino del documento.

En B2B > Documents > PDF Templates:

1. comprueba la plantilla activa para cada tipo y website;
2. realiza una vista previa;
3. ajusta HTML/CSS solo si cuentas con una persona que conozca plantillas Magento y CSS mPDF;
4. genera una factura o confirmación de prueba y comprueba la descarga desde la cuenta de empresa.

6.2. RFQ y oferta PDF

1. En B2B > Quotes > RFQ, crea un RFQ de prueba para una empresa y usuario activos.
2. Añade SKU visibles para la empresa, cantidad y precio de oferta.
3. Define la fecha de validez, envía la oferta al cliente y genera el PDF.
4. Comprueba la variante del cliente: datos del vendedor/comprador, posiciones, precio, total y fecha de validez.
5. Comprueba la variante del administrador: además, notas comerciales, comentarios, historial e información interna de posiciones.

El PDF del cliente no puede contener notas del comercial ni historial interno de estados.

7. Pedidos rápidos, importaciones e integraciones

Pedidos rápidos

En B2B > Quick Order > Debug SKU, comprueba la lista SKU,qty para la empresa, website y moneda. Después crea una lista de compra y prueba su uso por el cliente en el storefront.

Importación y exportación

En B2B > Import/Export, define un perfil solo después de determinar la fuente de datos. La configuración del perfil es un objeto JSON y debe contener rutas de archivos disponibles en el servidor Magento. Primero ejecuta la importación en modo de prueba y analiza el job y los logs.

Integraciones API

Antes de crear un token de integración, define el alcance de datos y el propietario de la sincronización. Usa una integración Magento independiente para cada ERP, PIM, WMS o middleware y concédele únicamente las ACL B2B necesarias. La lista completa de endpoints, tokens y normas de seguridad se encuentra en la documentación API para integradores.

8. Checklist de aceptación

Antes del lanzamiento en producción, confirma:

• Los módulos Kowal están activos, cron funciona, y la cache y los índices son correctos.
• B2B está activado únicamente para el website correcto.
• El theme B2B está asignado únicamente al B2B store view.
• La empresa de prueba tiene estado Active, usuario, rol, contacto y direcciones predeterminadas.
• El producto de prueba está activo, asignado al website, visible para la empresa y tiene precio B2B correcto.
• El cliente puede iniciar sesión, buscar SKU, usar quick order y añadir el producto al carrito.
• Checkout muestra solo los métodos de envío y pago permitidos.
• El límite y la regla de aprobación funcionan conforme a la política de la empresa, si se utilizan estas funciones.
• El documento y el PDF RFQ se generan y están disponibles solo para la empresa correcta.
• El RFQ puede enviarse, aceptarse y pasar al proceso de creación del pedido.
• Las integraciones tienen tokens separados y ACL limitadas, si se utilizan.

9. Problemas más frecuentes

Al contactar con soporte, indica la versión de Magento, versión del paquete, pasos para reproducir, hora del evento, logs anonimizados de forma segura y posible trace_id. No envíes tokens ni contraseñas.

10. Actualización del paquete

1. Consulta la información de versión proporcionada por Kowal.
2. Realiza primero la actualización en el entorno de pruebas.
3. Haz backup, composer update kowal/metapackage-b2b-suite --with-all-dependencies, bin/magento setup:upgrade, y en producción también compilación DI y deployment de recursos estáticos.
4. Repite la checklist de aceptación, prestando especial atención a precios, checkout, documentos e integraciones.

No actualices el paquete copiando archivos manualmente a app/code; esto provoca problemas con Composer y dificulta el soporte posterior.