> ## Agent Instructions > Utilisez l'API Maketou v1 décrite par la spécification OpenAPI de ce site. > Gardez la clé API côté serveur et ne l'exposez jamais dans du code client, des logs ou une réponse destinée au navigateur. > Ne livrez un produit et n'activez un accès que lorsque le statut du panier est `completed`. > N'inventez pas d'endpoint, de champ ou de webhook absent de la documentation. # Agent Skills Source: https://docs-api.maketou.com/ai/agent-skills Installez les règles d'intégration Maketou dans un assistant compatible avec les Agent Skills. Le skill Maketou apprend à votre assistant les étapes, contraintes et bonnes pratiques de l'API publique. ## Installer le skill Depuis votre projet, exécutez : ```bash theme={null} npx skills add https://docs-api.maketou.com ``` Vous pouvez consulter le fichier avant de l'installer : Ouvrez les instructions structurées fournies aux agents. ## Ce que le skill couvre * L'authentification avec une clé API liée à une boutique. * La création d'un panier et la redirection vers le paiement. * La vérification du statut avant la livraison du produit. * Les prix libres et les métadonnées. * Les erreurs et les limites de fréquence. * Les règles de sécurité pour protéger la clé API. ## Utiliser le skill Une fois installé, formulez directement votre objectif. ```text theme={null} Intègre le paiement Maketou dans mon backend. Crée le panier, conserve son identifiant et vérifie son statut avant d'activer l'accès au produit. ``` ## Skill ou MCP ? | Besoin | Choisissez | | - | - | | Donner des règles durables à l'agent dans votre projet | Agent Skill | | Rechercher la documentation publiée en temps réel | Serveur MCP | | Obtenir le contexte le plus fiable | Les deux | L'installation du skill n'ajoute aucune clé API. Continuez à stocker votre clé dans un gestionnaire de secrets côté serveur. # AGENTS.md Source: https://docs-api.maketou.com/ai/agents-md Ajoutez les règles essentielles de l'API Maketou aux instructions de votre projet. Un fichier `AGENTS.md` donne aux assistants IA des instructions propres à votre projet. Ajoutez l'extrait suivant à votre fichier `AGENTS.md` à la racine du projet. ```markdown theme={null} ## Intégration de l'API Maketou - Utilisez la documentation officielle : https://docs-api.maketou.com/llms.txt - Utilisez la spécification OpenAPI : https://docs-api.maketou.com/openapi.yaml - Utilisez l'URL de base `https://api.maketou.net`. - Effectuez toutes les requêtes Maketou depuis le backend. - Stockez la clé API dans un gestionnaire de secrets ou une variable d'environnement. - Ne placez jamais la clé API dans le frontend, les logs ou le dépôt Git. - Envoyez la clé avec `Authorization: Bearer YOUR_API_KEY`. - Créez un panier avec `POST /api/v1/stores/cart/checkout`. - Un panier Maketou contient actuellement un seul produit. - Conservez l'identifiant du panier et utilisez la `redirectUrl` retournée par l'API. - Vérifiez le panier avec `GET /api/v1/stores/cart/{cartId}`. - Livrez le produit ou activez l'accès uniquement si le statut est `completed`. - Gérez `waiting_payment`, `completed`, `abandoned` et `payment_failed`. - Gérez les réponses `400`, `401`, `404`, `422` et `429` selon l'endpoint. - En cas de réponse `429`, respectez le header `Retry-After`. - Utilisez `customerPrice` uniquement pour un produit configuré en prix libre. - N'inventez aucun endpoint, champ ou webhook absent de la documentation. ``` ## Pourquoi l'ajouter ? Ces règles restent disponibles pendant les tâches de développement. Elles réduisent les erreurs fréquentes, comme l'exposition d'une clé API ou la livraison d'un produit avant la confirmation du paiement. Combinez `AGENTS.md` avec le [serveur MCP](/ai/mcp-server) pour donner à l'assistant des règles locales et un accès à la documentation à jour. # LLMs.txt Source: https://docs-api.maketou.com/ai/llms-txt Donnez à un assistant IA un index ou une copie complète de la documentation Maketou. Maketou publie sa documentation dans des formats conçus pour les assistants IA. Utilisez `llms.txt` pour découvrir les pages et leurs descriptions. Utilisez `llms-full.txt` pour charger toute la documentation dans un seul fichier. ## Quel fichier utiliser ? | Fichier | Utilisation recommandée | | - | - | | `llms.txt` | Trouver rapidement la page pertinente avant de lire son contenu | | `llms-full.txt` | Fournir toute la documentation à un outil qui accepte un contexte long | Chaque page est également disponible en Markdown. Ajoutez `.md` à son URL. ```text theme={null} https://docs-api.maketou.com/guides/create-cart.md ``` ## Exemple de prompt ```text theme={null} Utilise la documentation Maketou disponible sur https://docs-api.maketou.com/llms.txt. Consulte les pages pertinentes avant de proposer du code. N'invente aucun endpoint ou champ absent de la documentation. ``` Mintlify met automatiquement à jour ces fichiers lorsque la documentation ou sa navigation change. # Serveur MCP Source: https://docs-api.maketou.com/ai/mcp-server Connectez votre assistant IA à la documentation Maketou avec le Model Context Protocol. Le serveur MCP Maketou permet à un assistant IA de rechercher la documentation et de lire les pages pertinentes pendant une conversation. ## URL du serveur ```text theme={null} https://docs-api.maketou.com/mcp ``` Ce serveur donne accès à la documentation. Il ne crée pas de panier, n'effectue pas de paiement et ne reçoit jamais votre clé API Maketou. ## Configurer votre outil Ajoutez le serveur dans `~/.codex/config.toml`. ```toml theme={null} [mcp_servers.maketou] url = "https://docs-api.maketou.com/mcp" ``` Exécutez cette commande dans votre terminal. ```bash theme={null} claude mcp add --transport http Maketou https://docs-api.maketou.com/mcp ``` Ajoutez le serveur dans `.cursor/mcp.json`. ```json theme={null} { "mcpServers": { "maketou": { "url": "https://docs-api.maketou.com/mcp" } } } ``` Ajoutez le serveur dans `.vscode/mcp.json`. ```json theme={null} { "servers": { "maketou": { "type": "http", "url": "https://docs-api.maketou.com/mcp" } } } ``` ## Vérifier la connexion Redémarrez votre outil si nécessaire, puis demandez : ```text theme={null} Recherche dans la documentation Maketou comment créer un panier, puis indique les champs obligatoires et les erreurs à gérer. ``` Votre assistant doit consulter la documentation Maketou et citer les pages utilisées. Vous pouvez aussi ouvrir le menu contextuel d'une page et sélectionner l'option MCP, Cursor ou VS Code. # API Reference Source: https://docs-api.maketou.com/api-reference/overview Testez les endpoints de Maketou directement depuis la documentation. L'API Reference contient les endpoints publics de Maketou et un playground interactif. ## Authentification Tous les endpoints nécessitent un token Bearer. ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` ## URL de base ```text theme={null} https://api.maketou.net ``` ## Endpoints disponibles Créez un panier et obtenez l'URL de redirection vers le paiement. Consultez le statut et les informations d'un panier existant. Ouvrez un endpoint, ajoutez votre clé API dans le playground, puis envoyez la requête depuis la documentation. # Créer un panier Source: https://docs-api.maketou.com/api-reference/paniers/créer-un-panier /openapi.yaml post /api/v1/stores/cart/checkout Crée un panier pour un produit Maketou et retourne une URL vers laquelle rediriger le client pour payer. # Récupérer la clé de signature des webhooks Source: https://docs-api.maketou.com/api-reference/paniers/récupérer-la-clé-de-signature-des-webhooks /openapi.yaml get /api/v1/stores/cart/webhook-signing-key Retourne la clé publique Ed25519 qui permet de vérifier le header `X-Cart-Signature` des webhooks de panier. Endpoint public, sans clé API. # Récupérer un panier Source: https://docs-api.maketou.com/api-reference/paniers/récupérer-un-panier /openapi.yaml get /api/v1/stores/cart/{cartId} Récupère un panier existant afin de vérifier son statut. # Passer en production Source: https://docs-api.maketou.com/going-live Publiez votre produit et vérifiez votre intégration avant d'envoyer des clients vers le paiement. Avant d'envoyer vos clients vers un paiement réel, publiez votre produit dans Maketou, puis vérifiez votre intégration de bout en bout. ## Checklist * Utilisez une clé API de la bonne boutique. * Publiez le produit dans Maketou afin qu'il soit disponible à la vente. * Confirmez que le `productDocumentId` correspond au produit publié. * Assurez-vous que votre application redirige correctement le client vers la page de paiement Maketou avec la `redirectUrl` retournée par l'API. * Gérez les statuts `waiting_payment`, `completed`, `abandoned` et `payment_failed`. * Enregistrez l'identifiant du panier retourné par l'API dans votre base de données. * Ajoutez une `redirectURL` si vous voulez ramener le client vers votre application après paiement. ## Erreurs à gérer Votre backend doit gérer au minimum les réponses `400`, `401`, `404` et `422`. Utilisez la page [Codes d'erreur](/resources/error-codes) pour préparer vos messages côté application. # Authentification Source: https://docs-api.maketou.com/guides/authentication Authentifiez vos requêtes avec une clé API de Maketou. Toutes les requêtes vers l'API publique de Maketou nécessitent une clé API. ## Obtenir une clé API 1. Connectez-vous au [dashboard Maketou](https://app.maketou.com). 2. Ouvrez la boutique concernée. 3. Cliquez sur **Autres**. 4. Cliquez sur **Clés API**. 5. Cliquez sur **Ajouter une clé API**. 6. Copiez la clé générée. La clé API vous sera affichée une seule fois. Copiez-la et stockez-la dans un gestionnaire de secrets. ## Utiliser la clé API Ajoutez la clé dans le header `Authorization`. ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` ## Exemple avec cURL ```bash theme={null} curl https://api.maketou.net/api/v1/stores/cart/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer YOUR_API_KEY" ``` Une clé API est rattachée à une boutique, pas à votre compte utilisateur. # Créer un panier Source: https://docs-api.maketou.com/guides/create-cart Créez un panier Maketou et redirigez votre client vers le paiement. Cet endpoint crée un panier et initie le processus de paiement. La réponse fournit une `redirectUrl`. Redirigez votre client vers cette URL pour qu'il procède au paiement. ## Endpoint ```http theme={null} POST https://api.maketou.net/api/v1/stores/cart/checkout ``` ## Body | Paramètre | Type | Requis | Description | | - | - | - | - | | `productDocumentId` | `string` | Oui | Identifiant public du produit | | `email` | `string` | Oui | Adresse email du client | | `firstName` | `string` | Oui | Prénom du client | | `lastName` | `string` | Oui | Nom du client | | `phone` | `string` | Non | Numéro de téléphone du client | | `redirectURL` | `string` | Non | URL de retour après paiement | | `webhookUrl` | `string` | Non | URL notifiée lorsque le paiement aboutit ou échoue. Voir [Webhooks de panier](/guides/webhooks) | | `meta` | `object` | Non | Métadonnées personnalisées | | `customerPrice` | `number` | Non | Montant à payer défini à la volée pour un produit en prix libre. Il doit être supérieur ou égal au prix minimum du produit | ## Exemple de payload ```json theme={null} { "productDocumentId": "550e8400-e29b-41d4-a716-446655440000", "email": "client@example.com", "firstName": "Jean", "lastName": "Dupont", "phone": "+33612345678", "redirectURL": "https://monsite.com/confirmation", "meta": { "userId": "12345", "source": "website" } } ``` ## Réponse ```json theme={null} { "cart": { "id": "fd2d91d7-20d2-4b86-b067-d474fb0d1e60", "createdAt": "2025-11-28T14:27:00.805Z", "updatedAt": "2025-11-28T14:27:00.805Z", "status": "waiting_payment", "customerInfo": { "firstName": "John", "lastName": "Doe", "email": "customer@example.com", "phone": "+33612345678", "lang": "fr-FR" } }, "redirectUrl": "https://checkout.moneroo.io/py_mj2m7m6gfro8" } ``` ## Erreurs | Code HTTP | Description | | - | - | | `400` | Produit invalide ou indisponible — Code : `INVALID_PRODUCT` | | `401` | Clé API invalide ou manquante — Code : `INVALID_API_KEY` | | `422` | Payload invalide ou `customerPrice` inférieur au minimum — Codes : `VALIDATION_ERROR`, `CUSTOMER_PRICE_BELOW_MINIMUM` | ## Tester l'endpoint Ouvrez [Créer un panier dans l'API Reference](/api-reference/overview), ajoutez votre clé API, puis envoyez une requête depuis le playground. # Prix libre Source: https://docs-api.maketou.com/guides/free-pricing Définissez à la volée le montant que votre client doit payer, sans descendre sous le prix minimum du produit. La fonctionnalité de prix libre vous permet de définir à la volée le montant que votre client doit payer lors de la création du panier. Pour un produit configuré en **Prix libre** dans Maketou, envoyez ce montant dans la propriété `customerPrice`. Il peut être supérieur au prix minimum configuré sur le produit, mais jamais inférieur. ## Exemple de payload ```json theme={null} { "productDocumentId": "7b63442b-200f-445c-89c6-cd4b3b001bf7", "email": "customer@example.com", "firstName": "John", "lastName": "Doe", "phone": "+33612345678", "redirectURL": "https://my.app/post-paiement", "customerPrice": 2000 } ``` Dans cet exemple, l'API crée le panier avec un montant à payer de `2000`. Si le prix minimum du produit est `1000`, cette valeur est acceptée. Une valeur inférieure à `1000` est refusée. La requête utilise le même endpoint que la création de panier : `POST /api/v1/stores/cart/checkout`. Pour que cela fonctionne, le produit doit utiliser le type de tarification **Prix libre** dans le dashboard Maketou. Si `customerPrice` est inférieur au prix minimum du produit, l'API retourne une erreur HTTP `422` avec le code `CUSTOMER_PRICE_BELOW_MINIMUM`. # Métadonnées Source: https://docs-api.maketou.com/guides/metadata Associez des données personnalisées à un panier Maketou. La propriété `meta` vous permet d'associer des métadonnées personnalisées à un panier. Ces données sont stockées avec le panier et peuvent être récupérées lors de la consultation du panier. ## Cas d'usage * Associer un identifiant utilisateur de votre système. * Tracer la source de la commande. * Stocker des informations de campagne marketing. * Ajouter une donnée contextuelle utile pour votre application. ## Exemple ```json theme={null} { "productDocumentId": "550e8400-e29b-41d4-a716-446655440000", "email": "client@example.com", "firstName": "Jean", "lastName": "Dupont", "meta": { "userId": "12345", "source": "website", "campaign": "summer-launch" } } ``` Gardez les métadonnées simples. Utilisez des paires clé-valeur faciles à lire et à exploiter côté backend. # Vérifier un panier Source: https://docs-api.maketou.com/guides/retrieve-cart Récupérez un panier pour connaître son statut de paiement. Vous pouvez récupérer un panier existant pour vérifier son statut. Cet endpoint est soumis aux [limites de fréquence](/resources/rate-limits). Consultez les headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` et `X-RateLimit-Reset` dans chaque réponse. En cas de dépassement, l'API retourne `429` avec le header `Retry-After`. ## Endpoint ```http theme={null} GET https://api.maketou.net/api/v1/stores/cart/{cartId} ``` ## Paramètres d'URL | Paramètre | Type | Description | | - | - | - | | `cartId` | `string` | Identifiant du panier | ## Exemple de requête ```bash theme={null} curl https://api.maketou.net/api/v1/stores/cart/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Réponse ```json theme={null} { "id": "fd2d91d7-20d2-4b86-b067-d474fb0d1e60", "createdAt": "2025-11-28T14:27:00.805Z", "updatedAt": "2025-11-28T14:27:00.805Z", "paymentId": "4d729bf5-ef1e-4f7f-bf10-e63bd3db9b04", "status": "waiting_payment", "customerInfo": { "lang": "fr-FR", "email": "customer@example.com", "phone": "+33612345678", "lastName": "Doe", "firstName": "John" }, "meta": { "userId": "ok" } } ``` ## Erreurs | Code HTTP | Description | | - | - | | `401` | Clé API invalide ou manquante | | `404` | Panier introuvable | | `429` | Limite de fréquence dépassée — Code : `RATE_LIMITED`. Voir [Limites de fréquence](/resources/rate-limits) | Pour éviter d'interroger cet endpoint en boucle, fournissez une `webhookUrl` à la création du panier. Voir [Webhooks de panier](/guides/webhooks). Stockez l'`id` du panier dès sa création. Vous en aurez besoin pour consulter son statut. # Webhooks de panier Source: https://docs-api.maketou.com/guides/webhooks Recevez une notification sur votre serveur lorsque le paiement d'un panier aboutit ou échoue. Au lieu d'interroger régulièrement l'API pour connaître le statut d'un panier, vous pouvez fournir une `webhookUrl` lors de sa création. Maketou envoie alors une requête `POST` vers cette URL lorsque le statut du panier change. ## Activer le webhook Ajoutez le champ `webhookUrl` dans le body de la [création de panier](/guides/create-cart) : ```json theme={null} { "productDocumentId": "550e8400-e29b-41d4-a716-446655440000", "email": "client@example.com", "firstName": "Jean", "lastName": "Dupont", "redirectURL": "https://monsite.com/confirmation", "webhookUrl": "https://monsite.com/webhooks/maketou-cart" } ``` L'URL doit être absolue et utiliser le protocole `http` ou `https`. Utilisez une URL `https` accessible publiquement. La `webhookUrl` est propre à chaque panier. Vous pouvez donc utiliser une URL différente selon le panier, par exemple pour transmettre un identifiant dans la query string. ## Événements notifiés | Statut du panier | Quand | | - | - | | `completed` | Le paiement est confirmé. Pour un produit gratuit, la notification est envoyée dès la création du panier | | `payment_failed` | Le paiement a échoué | Un panier en `payment_failed` peut ensuite passer en `completed`, par exemple lorsque le prestataire de paiement confirme le paiement en retard. Vous recevez alors une nouvelle notification avec le statut `completed`. Les paniers `abandoned` ne sont pas notifiés. ## Body de la requête Le body est identique à la réponse de [Vérifier un panier](/guides/retrieve-cart) (`GET /api/v1/stores/cart/{cartId}`) : ```http theme={null} POST /webhooks/maketou-cart HTTP/1.1 Content-Type: application/json X-Cart-Signature: t=1760004300,v1=ZmFrZS1zaWduYXR1cmUtZXhhbXBsZQ== ``` ```json theme={null} { "id": "fd2d91d7-20d2-4b86-b067-d474fb0d1e60", "createdAt": "2025-11-28T14:27:00.805Z", "updatedAt": "2025-11-28T14:29:12.341Z", "paymentId": "4d729bf5-ef1e-4f7f-bf10-e63bd3db9b04", "status": "completed", "customerInfo": { "lang": "fr-FR", "email": "customer@example.com", "phone": "+33612345678", "lastName": "Doe", "firstName": "John" }, "meta": { "userId": "12345" } } ``` Le body reflète l'état du panier au moment de l'envoi. Utilisez le champ `status` pour décider de l'action à mener, et `meta` pour retrouver la commande correspondante dans votre système (voir [Métadonnées](/guides/metadata)). ## Répondre à la notification Répondez avec un code HTTP `2xx` dès réception. Traitez la notification de manière asynchrone si votre traitement est long. Si votre serveur ne répond pas en `2xx`, Maketou renvoie la notification jusqu'à 2 fois, après environ 30 secondes puis 60 secondes. Au-delà, la notification est abandonnée. Vous pouvez toujours récupérer le statut avec [Vérifier un panier](/guides/retrieve-cart). Vous pouvez recevoir plusieurs notifications pour un même panier. Rendez votre traitement idempotent : ne livrez le produit qu'une seule fois, même si vous recevez `completed` plusieurs fois. ## Vérifier la signature Chaque notification est signée par Maketou. Vérifiez la signature avant de traiter la notification, pour vous assurer qu'elle provient bien de Maketou et que son contenu n'a pas été modifié. ### Header de signature ``` X-Cart-Signature: t=1760004300,v1=ZmFrZS1zaWduYXR1cmUtZXhhbXBsZQ== ``` * `t` : timestamp Unix (en secondes) au moment de l'envoi. * `v1` : signature Ed25519, encodée en base64. ### Récupérer la clé publique ```http theme={null} GET https://api.maketou.net/api/v1/stores/cart/webhook-signing-key ``` Cet endpoint est public et ne nécessite pas de clé API. La clé est la même pour toutes les boutiques : vous pouvez la récupérer une fois et la stocker dans votre configuration. ```bash theme={null} curl https://api.maketou.net/api/v1/stores/cart/webhook-signing-key ``` ```json theme={null} { "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA...\n-----END PUBLIC KEY-----\n", "algorithm": "ed25519", "header": "X-Cart-Signature: t=,v1=. Signed string: '.' (object keys sorted, no whitespace)." } ``` ### Reconstruire le message signé Le message signé est `.` : * `` est la valeur `t` du header ; * le JSON canonique est le body sérialisé avec les clés de chaque objet triées par ordre alphabétique, sans espaces ni retours à la ligne. Parsez le body JSON reçu, puis sérialisez-le de nouveau en JSON canonique. Ne signez pas le body brut tel que reçu : son formatage peut différer. ### Exemple en Node.js ```js theme={null} import crypto from 'node:crypto'; function canonicalJson(value) { if (value === null || typeof value !== 'object') { return JSON.stringify(value); } if (Array.isArray(value)) { return `[${value.map(canonicalJson).join(',')}]`; } const entries = Object.entries(value) .filter(([, entryValue]) => entryValue !== undefined) .sort(([left], [right]) => left.localeCompare(right)); return `{${entries .map(([key, entryValue]) => `${JSON.stringify(key)}:${canonicalJson(entryValue)}`) .join(',')}}`; } export function verifyCartWebhook(body, signatureHeader, publicKeyPem) { const timestamp = signatureHeader.match(/t=(\d+)/)?.[1]; const signature = signatureHeader.match(/v1=([^,]+)/)?.[1]; if (!timestamp || !signature) { return false; } const ageInSeconds = Math.floor(Date.now() / 1000) - Number(timestamp); if (ageInSeconds > 300) { return false; } return crypto.verify( null, Buffer.from(`${timestamp}.${canonicalJson(body)}`), crypto.createPublicKey(publicKeyPem), Buffer.from(signature, 'base64'), ); } ``` Ici, `body` est le body JSON déjà parsé, par exemple `req.body` avec Express et `express.json()`. Le timestamp `t` fait partie du message signé. Rejetez les notifications trop anciennes (par exemple plus de 5 minutes) pour vous protéger contre le rejeu d'une requête interceptée. ## Bonnes pratiques * **Vérifiez toujours la signature** avant de traiter une notification. * **Ne livrez le produit que sur `completed`**, comme pour la vérification par l'API. * **Rendez votre traitement idempotent** : un même panier peut être notifié plusieurs fois. * **Gardez une solution de repli** : si vous n'avez pas reçu de notification, vérifiez le statut avec [Vérifier un panier](/guides/retrieve-cart), en respectant les [limites de fréquence](/resources/rate-limits). # Comment démarrer Source: https://docs-api.maketou.com/how-to-start Préparez votre boutique, votre clé API et votre première requête. Suivez ces étapes pour créer votre premier panier avec l'API de Maketou. Connectez-vous au [dashboard Maketou](https://app.maketou.com), puis ouvrez la boutique qui vendra le produit. Dans votre boutique, ouvrez **Autres** puis **Clés API**. Cliquez sur **Ajouter une clé API** et copiez la clé générée. Ouvrez la page détail du produit, cliquez sur **Partager**, puis copiez l'**Identifiant public du produit**. Envoyez une requête `POST` vers `/api/v1/stores/cart/checkout` avec votre clé API et les informations client. ## URL de base ```text theme={null} https://api.maketou.net ``` ## Header d'authentification ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` La clé API s'affiche une seule fois. Stockez-la dans un endroit sûr avant de fermer la fenêtre. # Bienvenue Source: https://docs-api.maketou.com/index Découvrez l'API publique de Maketou et les guides pour créer un parcours de paiement. L'API de Maketou vous permet de créer des paniers, d'initier un paiement et de suivre le statut d'un achat depuis votre application. ## Limites d'usage L'API publique applique des limites de fréquence sur certains endpoints afin de garantir sa stabilité. | Endpoint | Rate limité ? | | - | - | | `POST /api/v1/stores/cart/checkout` | Non | | `GET /api/v1/stores/cart/{cartId}` | Oui | Les endpoints limités retournent les headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` et `X-RateLimit-Reset`. En cas de dépassement, ils répondent avec `429` et le header `Retry-After`. Consultez les [limites de fréquence](/resources/rate-limits) pour les seuils, les headers et les bonnes pratiques. ## En savoir plus Découvrez comment Maketou vous aide à vendre des produits numériques et à encaisser vos clients. Comprenez les points importants avant d'intégrer l'API : authentification, paniers et statut de paiement. Obtenez votre clé API, configurez votre boutique et préparez votre première requête. Vérifiez les éléments à contrôler avant d'envoyer de vrais clients vers le paiement. ## Puis passez à l'intégration Nous avons préparé des guides courts pour vous aider à intégrer les flux de paiement Maketou. Ajoutez votre clé API dans le header `Authorization` de chaque requête. Créez un panier et récupérez l'URL de redirection vers le paiement. Récupérez un panier existant pour vérifier son statut de paiement. Définissez à la volée le montant à payer, sans descendre sous le prix minimum du produit. Ajoutez vos propres données de suivi à un panier via la propriété `meta`. Testez les endpoints depuis la documentation avec le playground interactif. # Statuts des paniers Source: https://docs-api.maketou.com/resources/cart-statuses Comprenez les statuts retournés par l'API de Maketou. Un panier peut changer de statut après sa création. | Statut | Description | | - | - | | `waiting_payment` | Le panier est en attente de paiement | | `completed` | Le paiement est effectué | | `abandoned` | Le panier est abandonné | | `payment_failed` | Le paiement a échoué | ## Recommandation Votre application doit enregistrer l'identifiant du panier et vérifier son statut avant de livrer le produit ou d'activer l'accès client. Les statuts `completed` et `payment_failed` peuvent aussi vous être notifiés par [webhook](/guides/webhooks). # Codes d'erreur Source: https://docs-api.maketou.com/resources/error-codes Gérez les erreurs retournées par l'API de Maketou. L'API retourne un code HTTP et, dans certains cas, un corps JSON avec un `code` et un `message`. ## Création de panier | Code HTTP | Code API | Description | | - | - | - | | `400` | `INVALID_PRODUCT` | Le produit est invalide, indisponible ou n'appartient pas à la boutique | | `401` | `INVALID_API_KEY` | La clé API est invalide ou manquante | | `422` | `VALIDATION_ERROR` | Le format attendu pour la payload n'est pas respecté | ## Consultation de panier | Code HTTP | Code API | Description | | - | - | - | | `401` | `INVALID_API_KEY` | La clé API est invalide ou manquante | | `404` | — | Le panier est introuvable | | `429` | `RATE_LIMITED` | La limite de fréquence est dépassée | ## Exemple ```json theme={null} { "code": "RATE_LIMITED", "message": "Too many requests. Please retry later." } ``` Une réponse `429` inclut un header `Retry-After`. Consultez les [limites de fréquence](/resources/rate-limits) pour savoir quand réessayer. # Tarification Source: https://docs-api.maketou.com/resources/pricing Comprenez les frais appliqués aux paniers créés via l'API de Maketou. Les frais de gestion de l'API sont de 8% sur le montant de la transaction. Ce taux est appliqué uniquement aux paniers créés via l'API. Les paniers créés via le flux normal de Maketou sont soumis aux taux standards de Maketou. Vérifiez vos conditions commerciales dans le dashboard ou auprès de l'équipe Maketou avant de lancer une intégration en production. # Identifiant public du produit Source: https://docs-api.maketou.com/resources/product-document-id Trouvez le productDocumentId à utiliser dans vos requêtes API. Le `productDocumentId` correspond à l'identifiant public du produit dans votre espace Maketou. Vous devez l'envoyer lorsque vous créez un panier. ## Trouver le productDocumentId Ouvrez le [dashboard Maketou](https://app.maketou.com) et connectez-vous à votre compte. Accédez à l'espace de la boutique qui contient le produit. Allez sur la page détail du produit souhaité. Cliquez sur **Partager**, puis copiez l'**Identifiant public du produit**. L'API supporte actuellement un seul produit par panier. # Limites de fréquence Source: https://docs-api.maketou.com/resources/rate-limits Comprenez les limites de requêtes de l'API Maketou et gérez les réponses 429. Pour garantir la stabilité et la disponibilité de l'API pour l'ensemble des marchands, l'API publique de Maketou applique des **limites de fréquence (rate limiting)** sur certains endpoints. | Endpoint | Rate limité ? | | - | - | | `POST /api/v1/stores/cart/checkout` | Non | | `GET /api/v1/stores/cart/{cartId}` | Oui | La création de panier n'est pas soumise aux limites de fréquence. Cet endpoint ne retourne pas les headers `X-RateLimit-*`, `Retry-After` ni le code HTTP `429`. ## Les limites Les limites s'appliquent **par clé API** selon deux fenêtres complémentaires, auxquelles s'ajoute une protection par adresse IP : | Limite | Périmètre | Seuil | Fenêtre | | - | - | - | - | | Rafale (burst) | Par clé API | 60 requêtes | 10 secondes | | Soutenue (sustained) | Par clé API | 600 requêtes | 60 secondes | | Protection IP | Par adresse IP | 300 requêtes | 60 secondes | Une requête est rejetée dès qu'**une seule** de ces limites est atteinte. La limite de rafale protège contre les pics de requêtes ; la limite soutenue plafonne le volume sur une minute. ## Headers de réponse Les réponses des endpoints soumis aux limites incluent des headers qui indiquent l'état du quota par clé API sur la fenêtre de 60 secondes : ```http theme={null} X-RateLimit-Limit: 600 X-RateLimit-Remaining: 587 X-RateLimit-Reset: 1757606400 ``` | Header | Description | | - | - | | `X-RateLimit-Limit` | Nombre maximal de requêtes autorisées sur la fenêtre | | `X-RateLimit-Remaining` | Nombre de requêtes restantes sur la fenêtre en cours | | `X-RateLimit-Reset` | Date de réinitialisation de la fenêtre (timestamp Unix, en secondes) | | `Retry-After` | Présent uniquement sur une réponse `429`. Nombre de secondes à attendre avant de réessayer | ## Réponse en cas de dépassement Lorsqu'une limite est dépassée, l'API répond avec le code HTTP `429 Too Many Requests` et le header `Retry-After` : ```http theme={null} HTTP/1.1 429 Too Many Requests Retry-After: 7 { "code": "RATE_LIMITED", "message": "Too many requests. Please retry later." } ``` `Retry-After` indique le délai (en secondes) à respecter avant de renvoyer une requête. ## Bonnes pratiques * **Respectez le header `Retry-After`** : en cas de `429`, attendez le délai indiqué avant de réessayer. * **Mettez en place un backoff** : espacez vos tentatives plutôt que de boucler immédiatement après un `429`. * **Surveillez `X-RateLimit-Remaining`** : anticipez l'atteinte de la limite pour lisser votre trafic. * **Évitez le polling agressif** : pour vérifier le statut d'un panier, espacez vos appels (par exemple, toutes les quelques secondes) plutôt que de manière continue, ou privilégiez les [webhooks de panier](/guides/webhooks). * **Ne limitez pas votre tunnel de paiement à cause du checkout** : la création de panier n'est pas limitée, même pour un trafic élevé. # Accepter des paiements dans votre SaaS Source: https://docs-api.maketou.com/use-cases/accept-payments-in-your-saas Configurez Maketou, créez un parcours de paiement et confirmez le statut avant d'activer une offre SaaS. Ce guide montre comment utiliser Maketou pour accepter le paiement d'une offre vendue depuis votre SaaS. Vous configurez le produit et l'accès API dans Maketou. Vous reliez ensuite ce produit à votre propre parcours d'achat. ```text theme={null} Offre SaaS → Panier Maketou → Paiement → Confirmation → Accès activé ``` ## Préparez votre offre dans Maketou Créez dans Maketou le produit qui représente l'offre vendue par votre SaaS. Assurez-vous qu'il est publié avant de commencer l'intégration. Liste des produits dans Maketou avec le bouton Nouveau produit Ouvrez le produit, cliquez sur **Partager**, puis copiez son `productDocumentId`. Votre application utilisera cet identifiant pour créer un panier pour cette offre. Fiche d'un produit Maketou avec le bouton Partager Panneau Partager avec l'identifiant public du produit Dans votre boutique, ouvrez **Autres**, puis **Clés API**. Créez une clé et conservez-la dans le système de secrets de votre application. Page Autres de Maketou avec l'option Clés API Page des clés API avec le bouton Créer une clé API Formulaire de création d'une clé API N'exposez jamais votre clé API dans une application web ou mobile. Votre backend doit être le seul à l'utiliser. ## Reliez votre application à Maketou Vous devez associer chaque offre SaaS vendue à son `productDocumentId` Maketou. Lorsqu'un client choisit une offre, votre backend crée le panier correspondant avec l'API Maketou. Lors de cette création, transmettez les informations du client, une URL de retour vers votre application et les données qui permettent de relier le paiement à votre système, par exemple l'utilisateur, le workspace ou l'offre choisie. L'API supporte actuellement un seul produit par panier. Ce guide concerne les offres SaaS payantes : un produit gratuit ne retourne pas nécessairement d'URL de paiement. ## Redirigez le client vers le paiement Après la création du panier, Maketou retourne une URL de paiement. Redirigez votre client vers cette URL pour qu'il finalise son paiement sur la page de checkout Maketou. Enregistrez l'identifiant du panier retourné par Maketou dans votre système. Associez-le à l'utilisateur, au workspace ou à l'offre concernée avant de rediriger le client. ## Confirmez le paiement avant d'activer l'offre Si vous fournissez une `redirectURL`, Maketou y ajoute automatiquement le `cartId` du panier. Au retour du client, votre backend doit consulter le statut de ce panier avec l'API Maketou. Ne considérez pas le retour du navigateur comme une confirmation de paiement. Activez l'offre uniquement après avoir vérifié que le statut du panier est `completed`. La requête de vérification et sa réponse sont décrites dans [Vérifier un panier](/guides/retrieve-cart). La signification de chaque statut est détaillée dans [Statuts des paniers](/resources/cart-statuses). | Statut Maketou | Action attendue dans votre SaaS | | - | - | | `completed` | Activez l'offre ou la fonctionnalité achetée. | | `waiting_payment` | Informez le client que le paiement est en cours de confirmation. | | `payment_failed` | Informez le client que le paiement a échoué et proposez-lui de recommencer. | | `abandoned` | Laissez l'accès inactif et proposez au client de reprendre le paiement. | Vérifiez le statut avant chaque activation et assurez-vous qu'une même confirmation n'accorde pas plusieurs fois le même accès. ## Continuez avec l'API Reference Consultez les données à transmettre pour créer un panier et initier le paiement. Consultez le statut d'un panier avant d'activer une offre. # Qu'est-ce que Maketou ? Source: https://docs-api.maketou.com/what-is-maketou Comprenez le rôle de Maketou dans un parcours de vente et de paiement. Maketou aide les créateurs et les entreprises à vendre des produits numériques en ligne. Avec l'API publique, vous pouvez connecter votre propre application à Maketou. Vous créez un panier depuis votre backend, puis vous redirigez votre client vers une page de paiement. ## Ce que l'API permet * Créer un panier pour un produit Maketou. * Initier le paiement du panier. * Rediriger le client vers une page de paiement. * Vérifier le statut du panier après le paiement. * Associer des métadonnées à un panier. ## Quand utiliser l'API Utilisez l'API quand vous voulez vendre depuis votre propre site, application ou tunnel de vente, tout en gardant Maketou pour la gestion du produit et du paiement. Si vous utilisez uniquement les pages de vente Maketou, vous n'avez pas besoin de l'API pour créer un panier. # Ce qu'il faut savoir Source: https://docs-api.maketou.com/what-you-should-know Les concepts importants avant d'intégrer l'API de Maketou. Avant d'écrire votre intégration, gardez ces points en tête. ## Une clé API est liée à une boutique Une clé API n'est pas liée à votre compte personnel. Elle est liée à une boutique Maketou. Cela vous permet de gérer des accès séparés si vous travaillez avec plusieurs boutiques. ## Un panier contient un produit Pour le moment, l'API supporte un seul produit par panier. Vous devez fournir le `productDocumentId` du produit que vous voulez vendre. ## Le paiement est redirigé Quand vous créez un panier, l'API retourne une `redirectUrl`. Redirigez votre client vers cette URL pour finaliser le paiement. ## Les statuts évoluent après la création Un panier est créé avec le statut `waiting_payment`. Vous pouvez ensuite vérifier son statut avec l'endpoint de consultation. Les frais de gestion de l'API sont de 8% sur le montant de la transaction. Ce taux s'applique uniquement aux paniers créés via l'API.