Développeurs & intégrations

API publique CartePostale (v1)

Une API HTTP **JSON** pensée pour les **appels serveur à serveur** : créez des cartes postales numériques, enrichissez-les (texte, lieu, thème) et faites partir des **e-mails** avec liens de consultation et de tracking — depuis votre stack e-commerce, votre CRM ou vos scripts internes.

Clés API & journal

Les clés se créent dans l’espace **Manager → API publique** (comptes autorisés). Chaque requête authentifiée peut être **journalisée** (endpoint, code HTTP, durée, envois).

Que pouvez-vous en faire ?

  • E-commerce & WooCommerce

    Après achat ou livraison, déclenchez une carte de remerciement avec message et visuel de marque. Notre extension WordPress s’appuie sur cette même API.

  • Automatisation & no-code

    Reliez Make, Zapier (via webhooks vers votre backend), n8n ou scripts cron : tout scénario qui peut appeler une URL en POST avec JSON.

  • CRM & fidélisation

    Envoyez une carte personnalisée à un contact après une étape du pipeline, un anniversaire client ou une réactivation.

  • Outils internes

    Back-offices, extranets ou applications métier : générez des cartes publiées et des liens de suivi sans passer par l’éditeur web.

Deux endpoints

POST /api/v1/postcards/create-and-send

Crée la carte (recto via URL + contenu verso) puis, si vous fournissez des destinataires, envoie les e-mails. Réponse typique : identifiant public, URL de la carte, nombre d’e-mails partis.

POST /api/v1/postcards/send-invites

Pour une carte **déjà créée** : envoi (ou renvoi) des invitations uniquement, comme depuis l’éditeur — utile si la création a réussi mais pas l’envoi, ou pour une campagne ultérieure.

Remplacez l’origine par votre domaine CartePostale, ex. https://www.cartepostale.cool.

Authentification

Chaque requête inclut un en-tête Authorization: Bearer <clé> au format cpk_… affiché une seule fois à la création. **N’exposez pas** cette clé dans le navigateur : réservé au backend.

  • Réponses 401 / 403 si clé absente, invalide ou désactivée.

Fonctionnalités côté API

  • •Création d’une carte déjà publiée (prête à être consultée et partagée).
  • •Recto : URL d’image (https), stockée telle quelle — idéal pour visuels hébergés sur votre CDN ou CMS.
  • •Verso : message long (jusqu’à 20 000 car.), signature, lieu, coordonnées GPS, légende et emoji sur le recto.
  • •Personnalisation timbre / cachet : styles classic, modern, airmail, textes, année, thème visuel eventType.
  • •Envoi d’e-mails d’invitation : jusqu’à 50 destinataires par appel, chacun reçoit un lien de suivi unique /v/….
  • •Création sans envoi : omettez recipients ou passez un tableau vide pour ne créer que la carte.
  • •Carte existante ? Endpoint send-invites pour renvoyer ou compléter les invitations sans recréer la carte.
Exemple (create-and-send)
curl -sS -X POST 'https://www.cartepostale.cool/api/v1/postcards/create-and-send' \
  -H 'Authorization: Bearer VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  -d '{
    "frontImageUrl": "https://cdn.example.com/visuel.jpg",
    "message": "Merci pour votre confiance !",
    "senderName": "Mon entreprise",
    "recipients": [
      { "email": "client@example.com", "firstName": "Camille" }
    ],
    "emailSubject": "Une carte pour vous"
  }'

Bonnes pratiques

  • Image recto : URL **HTTPS stable** (évitez les liens très courts si la carte doit rester lisible).
  • **RGPD** : vous traitez des e-mails de tiers — base légale et information des personnes à votre charge.
  • Rotation des clés, désactivation en cas de fuite, monitoring via le journal Manager.

Documentation technique complète

Tableau des champs JSON, codes d’erreur détaillés, valeurs eventType et exemples supplémentaires : voir le fichier docs/public-api.md dans le dépôt source du projet CartePostale.