Documentation d'API
L'API permet d'envoyer des campagnes d'automatisation en quelques minutes et de connecter Manuscry à votre application.
L'envoi des cartes par API se fait directement à vos contacts : lors d'une commande par API, nous écrirons votre carte ainsi que votre enveloppe manuscrite, puis nous affranchirons et expédierons votre lettre.
Les réponses de l'API sont formatées en JSON, et il n'y a aucune limite en terme de nombre de requêtes. L'utilisation de l'API ne donne lieu à aucun frais supplémentaire.
L'envoi se fait en 4 étapes :
Création d'une campagne en automatisation sur Manuscry
Connexion à l'API avec le compte client utilisé
Récupération de l'identifiant de campagne
Récupération des champs personnalisés
Envoi d'une carte selon une campagne
Les actions possibles sont les suivantes :
- Ajout d'un contact à une liste
- Envoi d'une carte à un contact
- Récupération des campagnes
- Récupération des listes de contacts
Si vous souhaitez développer une intégration personnalisée, merci de nous contacter en amont pour obtenir la documentation API complète à l'adresse : contact@manuscry.com
L'url racine de l'API est la suivante : api.manuscry.com
Les appels à l'API sont illimités mais nécessitent une authentification.
L'API retourne les informations en format JSON.
Le format de base de retour est le suivant :
Vous pouvez activer un mode test, qui vous permettra d'interagir avec l'API sans pour autant déclencher l'envoi de carte. Vous pouvez l'activer depuis cette page : https://www.manuscry.com/mon-compte/test-api. Avec le mode test activé, vous pourrez utiliser toutes les routes d'API de Manuscry, mais les routes de création d'exemplaires ne donneront pas lieu à la création d'une nouvelle carte. Pensez à bien le désactiver après vos tests, car aucune carte ne sera envoyée pendant que vous serez en mode test.
Pour qu'une carte soit envoyée, certains champs doivent être présents. Si un champ est manquant ou mal renseigné, votre carte risque de ne pas être envoyée. Les champs requis sont les suivants :
- identifier - Identifiant unique du contact, utilisé pour dé-dupliquer les champs (deux contacts avec le même identifier ne peuvent être ajouté à la même campagne ou liste)
- address_name - Nom (ligne 0) de l'adresse (par exemple Jean Dupont or Super SARL)
- address_line1 - Ligne 1 de l'adresse (ex: 15 rue Victor Hugo)
- address_line2 - Ligne 2 de l'adresse (optionnel, ex: Appartement 15)
- address_zip - Code postal de l'adresse (ex: 75001)
- address_city - Ville de l'adresse (ex: Paris)
- address_country - Pays (optionnel, ex: Suisse), si aucun pays n'est renseigné "France" est utilisé par défaut
À cette liste s'ajoutent tous vos champs personnalisés ajoutés lors de la création de votre campagne.
La première étape consiste à créer un compte sur manuscry.com, et à créer une campagne de type "Scénario automatisé". Une fois cette campagne créée, vous obtiendrez une clé d'API à noter et à garder précieusement.
Cette route sert à vérifier vos informations d'authentification. Les champs suivants sont requis :
- api_key - Clé d'API liée à votre compte
Si vos informations sont correctes, vous obtiendrez ce retour :
Cette route sert à récupérer les informations de base sur vos campagnes en automatisation. Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
Si vos informations sont correctes, vous obtiendrez ce retour :
Cette route sert à récupérer les informations précises sur une campagne spécifique. Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
- {id} à remplacer dans l'URL - ID de votre campagne
Si vos informations sont correctes, vous obtiendrez ce retour :
Cette route sert à récupérer les champs nécessaires à la création d'un exemple d'une campagne, selon la configuration qui aura été faite lors de la création de cette campagne. Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
- {id} à remplacer dans l'URL - ID de votre campagne
Si vos informations sont correctes, vous obtiendrez ce retour :
Cette route sert à récupérer la liste des listes de contacts disponibles sur votre compte. Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
Si vos informations sont correctes, vous obtiendrez ce retour :
Cette route sert à ajouter un contact dans un dossier précis. Ce contact pourra ensuite servir dans le cadre d'une campagne ponctuelle, ou déclencher l'envoi d'une carte si vous avez paramétré la fonctionnalité "Calendrier".
Attention, cette route n'est pas la route servant à créer un exemplaire sur une campagne scénario. Elle ne fait que créer un contact et l'ajouter à une liste.
Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
- identifier - Identifiant du contact (champ unique)
- contact[] - Champ de contact format clé:valeur
- {id} à remplacer dans l'URL - ID de votre liste de contacts
Par exemple, la requête suivra ajoutera dans la liste d'id XXX un contact de prénom John et de nom Doe, avec l'identifiant john@doe.com.
/add-contact-to-folder/XXX?identifier=john@doe.com&contact[]=firstname:John&contact[]=lastname:Doe
Pour qu'un contact soit éligible à l'envoi d'une carte, il doit comporter tous les champs contacts nécessaires et listés dans la section "Champs contact" à savoir : identifier, address_name, address_line1, address_line2, address_zip, address_city, address_country + les champs personnalisés ajoutés lors de la création de votre campagne.
Si vos informations sont correctes, vous obtiendrez ce retour :
Si le contact existe déjà (identifier déjà présent dans cette liste), le détail de status retourné sera "updated" et non pas "created".
Cette route sert à ajouter un contact à une campagne. Une carte et une enveloppe manuscrite seront ajoutées à la liste d'attente et envoyées pour ce contact.
Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
- identifier - Identifiant du contact (champ unique)
- contact[] - Champ de contact format clé:valeur
- {id} à remplacer dans l'URL - ID de votre campagne
Par exemple, la requête suivra ajoutera dans la campagne d'id XXX un contact de prénom John et de nom Doe, avec l'identifiant john@doe.com, et l'adresse 15 rue Victor Hugo, 75001 Paris.
/create-card-instance/XXX?identifier=john@doe.com&contact[]=firstname:John&contact[]=lastname:Doe&contact[]=address_line1=15 rue Victor Hugo&contact[]=address_zip=75001&contact[]=address_city=Paris
Pour qu'un contact soit éligible à l'envoi d'une carte, il doit comporter tous les champs contacts nécessaires et listés dans la section "Champs contact" à savoir : identifier, address_name (ou firstname, lastname, companyname), address_line1, address_line2, address_zip, address_city, address_country + les champs personnalisés ajoutés lors de la création de votre campagne.
Si vos informations sont correctes, vous obtiendrez ce retour :
Si le contact existe déjà (identifier déjà présent dans cette liste), le status retourné sera "error".
Si vous créez une campagne automatisation avec l'option "calendrier", des cartes seront envoyées chaque année en fonction d'un champ spécifique de vos contacts contenant une date. Si vous souhaitez par exemple créer une campagne d'anniversaire, il vous suffit d'ajouter un champ nommé par exemple "anniversaire" dans vos contacts, contenu une date d'envoi.
Pour ajouter des contacts à cette automatisation par API, il faut utiliser la route GET /add-contact-to-folder, et non pas la route GET /create-card-instance. Il vous suffira d'envoyer les informations de votre contact, et nous nous chargerons d'envoyer la carte à la date prévue à votre contact : vous n'avez rien à faire à part remonter la date de votre contact.
L'identifiant du contact est un champ unique servant à dédupliquer les contacts. Deux contacts avec le même identifiant ne peuvent être ajoutés à la même liste ou campagne. Nous vous recommandons donc d'utiliser l'email, le numéro de téléphone, ou tout autre attribut unique afin de vous assurer que les cartes ne soient pas envoyées en double.
L'envoi des cartes par API se fait directement à vos contacts : lors d'une commande par API, nous écrirons votre carte ainsi que votre enveloppe manuscrite, puis nous affranchirons et expédierons votre lettre.
Les réponses de l'API sont formatées en JSON, et il n'y a aucune limite en terme de nombre de requêtes. L'utilisation de l'API ne donne lieu à aucun frais supplémentaire.
L'envoi se fait en 4 étapes :
Création d'une campagne en automatisation sur Manuscry
Connexion à l'API avec le compte client utilisé
Récupération de l'identifiant de campagne
Récupération des champs personnalisés
Envoi d'une carte selon une campagne
Les actions possibles sont les suivantes :
- Ajout d'un contact à une liste
- Envoi d'une carte à un contact
- Récupération des campagnes
- Récupération des listes de contacts
Si vous souhaitez développer une intégration personnalisée, merci de nous contacter en amont pour obtenir la documentation API complète à l'adresse : contact@manuscry.com
Informations génériques
L'url racine de l'API est la suivante : api.manuscry.com
Les appels à l'API sont illimités mais nécessitent une authentification.
L'API retourne les informations en format JSON.
Le format de base de retour est le suivant :
{
"status": "État de la requête (ex: created, success etc)",
"details": "Détails sur la requête (ex: not_authorized, already_exists etc)",
"hint": "Indice sur la résolution d'erreur (ex: Check your API key)"
}Mode test
Vous pouvez activer un mode test, qui vous permettra d'interagir avec l'API sans pour autant déclencher l'envoi de carte. Vous pouvez l'activer depuis cette page : https://www.manuscry.com/mon-compte/test-api. Avec le mode test activé, vous pourrez utiliser toutes les routes d'API de Manuscry, mais les routes de création d'exemplaires ne donneront pas lieu à la création d'une nouvelle carte. Pensez à bien le désactiver après vos tests, car aucune carte ne sera envoyée pendant que vous serez en mode test.
Champs contact
Pour qu'une carte soit envoyée, certains champs doivent être présents. Si un champ est manquant ou mal renseigné, votre carte risque de ne pas être envoyée. Les champs requis sont les suivants :
- identifier - Identifiant unique du contact, utilisé pour dé-dupliquer les champs (deux contacts avec le même identifier ne peuvent être ajouté à la même campagne ou liste)
- address_name - Nom (ligne 0) de l'adresse (par exemple Jean Dupont or Super SARL)
- address_line1 - Ligne 1 de l'adresse (ex: 15 rue Victor Hugo)
- address_line2 - Ligne 2 de l'adresse (optionnel, ex: Appartement 15)
- address_zip - Code postal de l'adresse (ex: 75001)
- address_city - Ville de l'adresse (ex: Paris)
- address_country - Pays (optionnel, ex: Suisse), si aucun pays n'est renseigné "France" est utilisé par défaut
À cette liste s'ajoutent tous vos champs personnalisés ajoutés lors de la création de votre campagne.
Routes d'API
La première étape consiste à créer un compte sur manuscry.com, et à créer une campagne de type "Scénario automatisé". Une fois cette campagne créée, vous obtiendrez une clé d'API à noter et à garder précieusement.
GET /test-auth
Cette route sert à vérifier vos informations d'authentification. Les champs suivants sont requis :
- api_key - Clé d'API liée à votre compte
Si vos informations sont correctes, vous obtiendrez ce retour :
{
"status": "success",
"email": "yourmail@gmail.com",
"api_key": "xxxxxxxxxxxxxxxxxxxxx"
}GET /get-layouts
Cette route sert à récupérer les informations de base sur vos campagnes en automatisation. Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
Si vos informations sont correctes, vous obtiendrez ce retour :
{
"status": "success",
"items": [
{
"id": "XXX",
"type": "auto",
"title": "Campagne",
"created": "21/09/2021 à 11:54",
"total_count": 50,
"waiting_count": 0,
"generating_count": 0,
"format": "a6",
"format_details": {
"width": 148,
"height": 105,
"orientation": "landscape"
}
}
]
}GET /get-layout/{id}
Cette route sert à récupérer les informations précises sur une campagne spécifique. Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
- {id} à remplacer dans l'URL - ID de votre campagne
Si vos informations sont correctes, vous obtiendrez ce retour :
{
"status": "success",
"id": "XXX",
"type": "auto",
"title": "Campagne",
"created": "21/09/2021 à 11:54",
"total_count": 50,
"waiting_count": 0,
"generating_count": 0,
"format": "a6",
"format_details": {
"width": 148,
"height": 105,
"orientation": "landscape"
}
}GET /get-fields/{id}
Cette route sert à récupérer les champs nécessaires à la création d'un exemple d'une campagne, selon la configuration qui aura été faite lors de la création de cette campagne. Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
- {id} à remplacer dans l'URL - ID de votre campagne
Si vos informations sont correctes, vous obtiendrez ce retour :
{
"status": "success",
"items": [
{
"key": "firstname",
"label": "Custom field - firstname",
"required": true,
"help_text": "Value of the custom field"
},
{
"key": "identifier",
"label": "Identifier",
"required": true,
"help_text": "Unique identifier of the contact (email recommended)"
},
{
"key": "address_name",
"label": "Address - Firstname Lastname",
"required": true,
"help_text": "Name of the address (ex: Jean Dupont or Super SARL)"
},
{
"key": "address_line1",
"label": "Address - Line 1",
"required": true,
"help_text": "Address line 1 (ex: 15 rue Victor Hugo)"
},
{
"key": "address_line2",
"label": "Address - Line 2",
"required": false,
"help_text": "Address line 2, optional (ex: Appartement 15)"
},
{
"key": "address_zip",
"label": "Address - Zip",
"required": false,
"help_text": "Zip of the address (ex: 75001)"
},
{
"key": "address_city",
"label": "Address - City",
"required": true,
"help_text": "City of the address (ex: Paris)"
},
{
"key": "address_country",
"label": "Address - Country",
"required": false,
"help_text": "Country of the address (ex: France)"
}
]
}GET /get-contacts-folders
Cette route sert à récupérer la liste des listes de contacts disponibles sur votre compte. Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
Si vos informations sont correctes, vous obtiendrez ce retour :
{
"status": "success",
"items": [
{
"id": "XXX",
"title": "Clients",
"contacts_count": 420
},
{
"id": "XXX",
"title": "Prospects à démarcher",
"contacts_count": 822
}
]
}GET /add-contact-to-folder/{id}
Cette route sert à ajouter un contact dans un dossier précis. Ce contact pourra ensuite servir dans le cadre d'une campagne ponctuelle, ou déclencher l'envoi d'une carte si vous avez paramétré la fonctionnalité "Calendrier".
Attention, cette route n'est pas la route servant à créer un exemplaire sur une campagne scénario. Elle ne fait que créer un contact et l'ajouter à une liste.
Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
- identifier - Identifiant du contact (champ unique)
- contact[] - Champ de contact format clé:valeur
- {id} à remplacer dans l'URL - ID de votre liste de contacts
Par exemple, la requête suivra ajoutera dans la liste d'id XXX un contact de prénom John et de nom Doe, avec l'identifiant john@doe.com.
/add-contact-to-folder/XXX?identifier=john@doe.com&contact[]=firstname:John&contact[]=lastname:Doe
Pour qu'un contact soit éligible à l'envoi d'une carte, il doit comporter tous les champs contacts nécessaires et listés dans la section "Champs contact" à savoir : identifier, address_name, address_line1, address_line2, address_zip, address_city, address_country + les champs personnalisés ajoutés lors de la création de votre campagne.
Si vos informations sont correctes, vous obtiendrez ce retour :
{
"status": "success",
"details": "created"
}Si le contact existe déjà (identifier déjà présent dans cette liste), le détail de status retourné sera "updated" et non pas "created".
GET /create-card-instance/{id}
Cette route sert à ajouter un contact à une campagne. Une carte et une enveloppe manuscrite seront ajoutées à la liste d'attente et envoyées pour ce contact.
Les champs requis sont les suivants :
- api_key - Clé d'API liée à votre compte
- identifier - Identifiant du contact (champ unique)
- contact[] - Champ de contact format clé:valeur
- {id} à remplacer dans l'URL - ID de votre campagne
Par exemple, la requête suivra ajoutera dans la campagne d'id XXX un contact de prénom John et de nom Doe, avec l'identifiant john@doe.com, et l'adresse 15 rue Victor Hugo, 75001 Paris.
/create-card-instance/XXX?identifier=john@doe.com&contact[]=firstname:John&contact[]=lastname:Doe&contact[]=address_line1=15 rue Victor Hugo&contact[]=address_zip=75001&contact[]=address_city=Paris
Pour qu'un contact soit éligible à l'envoi d'une carte, il doit comporter tous les champs contacts nécessaires et listés dans la section "Champs contact" à savoir : identifier, address_name (ou firstname, lastname, companyname), address_line1, address_line2, address_zip, address_city, address_country + les champs personnalisés ajoutés lors de la création de votre campagne.
Si vos informations sont correctes, vous obtiendrez ce retour :
{
"status": "success",
"type": "auto"
}Si le contact existe déjà (identifier déjà présent dans cette liste), le status retourné sera "error".
Informations supplémentaires
Campagne calendrier
Si vous créez une campagne automatisation avec l'option "calendrier", des cartes seront envoyées chaque année en fonction d'un champ spécifique de vos contacts contenant une date. Si vous souhaitez par exemple créer une campagne d'anniversaire, il vous suffit d'ajouter un champ nommé par exemple "anniversaire" dans vos contacts, contenu une date d'envoi.
Pour ajouter des contacts à cette automatisation par API, il faut utiliser la route GET /add-contact-to-folder, et non pas la route GET /create-card-instance. Il vous suffira d'envoyer les informations de votre contact, et nous nous chargerons d'envoyer la carte à la date prévue à votre contact : vous n'avez rien à faire à part remonter la date de votre contact.
Identifiant contact
L'identifiant du contact est un champ unique servant à dédupliquer les contacts. Deux contacts avec le même identifiant ne peuvent être ajoutés à la même liste ou campagne. Nous vous recommandons donc d'utiliser l'email, le numéro de téléphone, ou tout autre attribut unique afin de vous assurer que les cartes ne soient pas envoyées en double.
Mis à jour le : 01/06/2022
Merci !