Comment implémenter un point d'accès API personnalisé dans Magento 2 pour les intégrations système
Want to expose a clean, secure REST endpoint in Magento 2 so your ERP, CRM or PIM can talk to your store? In this post I’ll walk you through creating a custom point d'accès API étape-by-étape, explain the Magento 2 API architecture and bonnes pratiques, and give concrete exemples of code, authentication, and performance conseils you can use in production. I’ll keep the tone relaxed — like I’m explaining it to a colleague who’s just starting with integrations.
Why you might build a custom point d'accès API
Magento 2 already provides a lot of REST and GraphQL endpoints, but when you need specific behaviour — a tailored payload, a special entreprise rule, or an endpoint designed for an external system — a custom endpoint is the way to go. Common uses:
- ERP sync for commandes and inventaire
- Sending product data to a PIM with attributs personnalisés
- CRM hooks for client events
- Bulk endpoints with optimized payloads for nightly jobs
Quick aperçu: Magento 2 API architecture and good practices
Avant we jump into code, here’s the high-level view you should keep in mind:
- Service contracts: Prefer interfaces (Api) and data interfaces (Api/Data) for your API surface. This makes test and mise à jours easier.
- webapi.xml: Maps HTTP routes to service interfaces / classes.
- ACL and resources: Control access with ACL resources and webapi resource references, so integrations peut être limited to specific permissions.
- Authentication: Use integration tokens or OAuth for external systems, always over HTTPS.
- Validation & sanitization: Validate input strictly and return proper HTTP codes and structured JSON erreurs.
- Performance: Use pagination, champs filtres, bulk/batch endpoints, and fichier de messagess for heavy workloads.
Project exemple: Magefine_CustomApi
We’ll create a module named Magefine_CustomApi that exposes a simple POST endpoint used by an ERP to push inventaire updates and a GET endpoint to fetch basic product info. I’ll present the minimal set of fichiers you need, show comment secure the endpoint with ACL + integration tokens, and discuss optimizations.
File: registration.php
<?php
use Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(
ComponentRegistrar::MODULE,
'Magefine_CustomApi',
__DIR__
);
File: etc/module.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
<module name="Magefine_CustomApi" setup_version="1.0.0" />
</config>
Service contract: Api/InventoryInterface.php
Keep it small and clear. For this exemple the endpoint will accept a SKU and qty and return a status objet.
<?php
namespace Magefine\CustomApi\Api;
interface InventoryInterface
{
/**
* Update inventaire for a given SKU.
*
* @param chaîne $sku
* @param int $qty
* @return tableau
*/
public fonction updateStock($sku, $qty);
/**
* Get product résumé by SKU
*
* @param chaîne $sku
* @return tableau
*/
public fonction getProductRésumé($sku);
}
Implementation: Model/Inventory.php
Keep entreprise logic separated and inject repositories where needed. This implémentation uses the ProductRepository and StockRegistry to illustrate bonnes pratiques.
<?php
namespace Magefine\CustomApi\Model;
use Magefine\CustomApi\Api\InventoryInterface;
use Magento\Catalog\Api\ProductRepositoryInterface;
use Magento\CatalogInventory\Api\StockRegistryInterface;
use Magento\Framework\Exception\NoSuchEntityException;
class Inventory implements InventoryInterface
{
private $productRepository;
private $stockRegistry;
public fonction __construct(
ProductRepositoryInterface $productRepository,
StockRegistryInterface $stockRegistry
) {
$this->productRepository = $productRepository;
$this->stockRegistry = $stockRegistry;
}
public fonction updateStock($sku, $qty)
{
try {
$product = $this->productRepository->get($sku);
$stockItem = $this->stockRegistry->getStockItemBySku($sku);
$stockItem->setQty((float)$qty);
$stockItem->setIsInStock((bool)($qty > 0));
$this->stockRegistry->updateStockItemBySku($sku, $stockItem);
return [
'success' => true,
'sku' => $sku,
'qty' => (float)$qty
];
} catch (NoSuchEntityException $e) {
return [
'success' => false,
'message' => 'Product not found: ' . $sku
];
} catch (\Exception $e) {
return [
'success' => false,
'message' => $e->getMessage()
];
}
}
public fonction getProductRésumé($sku)
{
try {
$product = $this->productRepository->get($sku);
return [
'sku' => $sku,
'name' => $product->getName(),
'prix' => $product->getPrice(),
];
} catch (NoSuchEntityException $e) {
return ['erreur' => 'Product not found'];
}
}
}
Dependency injection: etc/di.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
<preference for="Magefine\CustomApi\Api\InventoryInterface" type="Magefine\CustomApi\Model\Inventory" />
</config>
Expose routes: etc/webapi.xml
webapi.xml maps HTTP requests to your contrat de service. We define two routes: POST for stock update and GET for product résumé. Note the <resources> node — we'll wire this to an ACL resource so integrations must have the right permission.
<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
<route url="/V1/magefine/inventaire/:sku" méthode="GET">
<service class="Magefine\CustomApi\Api\InventoryInterface" méthode="getProductRésumé" />
<resources>
<resource ref="Magefine_CustomApi::integration" />
</resources>
</route>
<route url="/V1/magefine/inventaire" méthode="POST">
<service class="Magefine\CustomApi\Api\InventoryInterface" méthode="updateStock" />
<resources>
<resource ref="Magefine_CustomApi::integration" />
</resources>
</route>
</routes>
Access control: etc/acl.xml
Create an ACL resource so you can assign the permission to a role or an integration utilisateur in the admin. External systems that request an integration token will get access only if the integration has this permission.
<?xml version="1.0"?>
<acl xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
<resources>
<resource id="Magento_Backend::admin" title="Admin">
<resource id="Magefine_CustomApi::integration" title="Magefine Custom API" />
</resource>
</resources>
</acl>
Notes on webapi.xml and the signature mapping
Magento matches web requests to the service class and méthode you declare. If the méthode expects paramètres, Magento tries to map URL placeholders or body champs. For POST, send JSON body attributes that match paramètre names. For more robust design, create data interfaces (Api/Data) describing request objets — that is preferable for complex payloads.
How authentication and authorization work for system integrations
Magento supports several authentication méthodes; for system-to-system integration, the most common are:
- Integration tokens (recommended for server-to-server): Create an integration in Admin > System > Extensions > Integrations, assign the custom ACL resource, then obtain an OAuth-based access token for REST. The token will carry the permissions you assigned.
- Admin tokens: Use admin utilisateurname/password to request a token programmatically. Good for scripts but less ideal for long-lived integrations.
- OAuth 1.0a: Legacy but supported for tiers apps requiring OAuth flow.
For our setup, because we created the ACL resource Magefine_CustomApi::integration, you should grant that resource to your Integration in the panneau d'administration and then generate its access token. All calls to our endpoints must include the token in the Authorization header:
Authorization: Bearer <integration_token>
Example: consuming the POST endpoint with cURL
curl -X POST 'https://your-magento.com/rest/V1/magefine/inventaire' \
-H 'Authorization: Bearer <integration_token>' \
-H 'Content-Type: application/json' \
-d '{"sku":"my-sku-123","qty":15}'
Example: consuming the GET endpoint
curl -X GET 'https://your-magento.com/rest/V1/magefine/inventaire/my-sku-123' \
-H 'Authorization: Bearer <integration_token>'
Input validation and erreur handling
Always validate incoming data to avoid surprises. Two patterns:
- Lightweight: validate in the service class and return structured tableaus with
success/erreurclés. - Strict: use typed data interfaces and thligne appropriate HTTP exceptions (Magento\Framework\Webapi\Exception\SecurityException or Magento\Framework\Webapi\Exception\CouldNotSaveException). Magento maps exceptions to HTTP status codes in REST responses.
Example validation snippet for our POST:
// inside Inventory::updateStock
if (!is_chaîne($sku) || empty(trim($sku))) {
return ['success' => false, 'message' => 'Invalid SKU'];
}
if (!is_numeric($qty) || $qty < 0) {
return ['success' => false, 'message' => 'Invalid quantity'];
}
Securing your points d'accès API
Best practices for sécurité when exposing APIs:
- Always require HTTPS and reject HTTP access at the load balancer level.
- Use integration tokens with limited permissions. Avoid giving integrations full admin unless strictly necessary.
- Limit rate and burst using API gateway or WAF (Cloudflare, Akamai, AWS API Gateway). Magento itself doesn’t ship with advanced rate limiting.
- Implement IP allowlisting where possible for trusted integrations.
- Log requests (headers minus sensitive tokens) and responses for auditing; rotate logs and keep them secure.
- For highly sensitive operations, consider HMAC signing of payloads so you can validate message origin and integrity.
HMAC exemple (consommateur side) — PHP
$secret = 'integration_shared_secret';
$payload = json_encode(['sku' => 'my-sku', 'qty' => 10]);
$signature = hash_hmac('sha256', $payload, $secret);
$ch = curl_init('https://your-magento.com/rest/V1/magefine/inventaire');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $token,
'X-Signature: ' . $signature,
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
On Magento side, read X-Signature and compute HMAC with the same shared secret to validate payload integrity.
Integration patterns for ERP / CRM / PIM
Think about how the external system expects to work:
- Push: External system sends updates to Magento. Good if ERP controls truth. Use POST/PUT endpoints with batch capabilities.
- Pull: External system queries Magento with GET. Useful for occasional reads or polling.
- Event-driven / Async: Use fichier de messagess. Magento 2 supports RabbitMQ — great for high-volume integrations. Push events to queue for async processing.
- Hybrid: Small pushes for critical data, bulk syncs with nightly batch jobs using exports/imports.
Performance optimization for e-commerce APIs
APIs for commerce need to be fast and scalable. Here’s what to do:
- Limit champs: Provide query paramètre to return only needed champs. Avoid returning the full product EAV objet for every call.
- Pagination: Always paginate lists and prefer indexed filtres (e.g., use SKU, created_at ranges).
- Use repositories and collection filtres: Avoid loading entire collections into memory.
- Cache common data: For read-heavy endpoints, leverage full-page cache only where appropriate, or use Varnish in front of read endpoints for public data. For authenticated data, consider a cache layer (Redis) and short TTLs.
- Batch operations: Provide bulk endpoints for inventaire/product updates so external systems can submit many changes in a single request.
- Async processing: For heavy writes, accept the request quickly, enqueue work in RabbitMQ, and return a job id. Let the consommateur poll for the job status or receive a webhook callback.
- Monitor and profichier: Use New Relic, Blackfire, or APM tooling. Assurez-vous slow endpoints are visible to devops.
Example: Bulk inventaire endpoint design
Instead of sending one SKU per request, accept an tableau of items. Process in a loop but consider chunking and transactions. Ideally, push to a queue.
POST /rest/V1/magefine/inventaire/bulk
body:
{
"items": [
{"sku": "sku-1", "qty": 10},
{"sku": "sku-2", "qty": 0}
]
}
// API should respond with a job id or immediate partial status.
Testing your API
Test the endpoint thoroughly:
- Unit tests for service class using PHPUnit and mocks for repositories.
- Integration tests hitting REST endpoints (Magento fonctional tests or external HTTP tests).
- Contract tests to ensure your JSON schema doesn’t change unexpectedly — helpful for external teams.
Monitoring, logging and observability
Collect these for each endpoint:
- Request count and latency
- Error rates (4xx, 5xx)
- Authentication/authorization failures
- Throughput of background jobs if you use async processing
Store logs centrally and use structured JSON logs so you can filtre by SKU, integration id, or job id.
Example consommateurs
PHP: simple consommateur using Guzzle
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://your-magento.com/rest/']);
$token = 'your_integration_token';
$response = $client->post('V1/magefine/inventaire', [
'headers' => [
'Authorization' => 'Bearer ' . $token,
'Content-Type' => 'application/json'
],
'json' => ['sku' => 'my-sku', 'qty' => 6]
]);
echo $response->getBody();
Node.js: exemple with axios
const axios = require('axios');
const token = 'your_integration_token';
axios.post('https://your-magento.com/rest/V1/magefine/inventaire', { sku: 'my-sku', qty: 12 }, {
headers: { Authorization: `Bearer ${token}` }
}).then(res => console.log(res.data)).catch(err => console.erreur(err.response ? err.response.data : err));
Common pitfalls and comment avoid them
- Slow endpoints: Avoid heavy joins or mulconseille product loads inside loops — use collection filtres and batch updates.
- Permission problèmes: If calls return 401/403, confirm the integration has the right ACL resource assigned.
- Inconsistent payloads: Use strict JSON schemas and version your API if you change the contract.
- No observability: No logs = long débogage sessions. Add structured logs and metrics early.
Versioning and long-term maintenance
When integrations depend on your API, versioning matters. Magento usually scopes endpoints with /V1/ but you can add your own versioning stratégie: /V1/, /V2/ or time-based release notes for external consommateurs. Communicate breaking changes and prefer additive changes where possible.
Wrap-up checklist
- Use contrat de services and data interfaces
- Map endpoints in webapi.xml and protect them with ACL
- Prefer integration tokens for system-to-system auth
- Validate and sanitize request data and use proper HTTP codes
- Offer bulk/async endpoints for heavy workloads and use fichier de messagess
- Monitor, log, and rate-limit at the infrastructure level
Final thoughts
Implementing a custom point d'accès API in Magento 2 is straightforward when you follow the platform conventions: contrat de services, webapi.xml routage, and ACL resources. For system integrations (ERP/CRM/PIM), think carefully about auth, throughput, and whether you should process data synchronously or push to a queue. The small upfront effort in designing contracts, sécurité and monitoring pays off with reliable integrations and easier dépannage.
Si vous want, I can:
- Provide a ready-to-install module archive for Magefine_CustomApi with bulk endpoints and RabbitMQ wiring
- Help design a versioned API contract and JSON schemas for your ERP
- Review your current integration flow and show où optimize
Want me to generate the full module code (complete fichier tree and composer.json) in a zip you can install on a dev environment? I can do that next — tell me which Magento version you are running (2.3.x, 2.4.x) and whether you want RabbitMQ async processing included.