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

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 :

jsx
{
"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)"
}


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 :

- email - Adresse email de votre compte
- api_key - Clé d'API liée à votre compte

Si vos informations sont correctes, vous obtiendrez ce retour :

php
{
"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 :

- email - Adresse email de votre compte
- api_key - Clé d'API liée à votre compte

Si vos informations sont correctes, vous obtiendrez ce retour :

jsx
{
"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 :

- email - Adresse email de votre compte
- 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 :

jsx
{
"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 :

- email - Adresse email de votre compte
- 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 :

jsx
{
"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 :

- email - Adresse email de votre compte
- api_key - Clé d'API liée à votre compte

Si vos informations sont correctes, vous obtiendrez ce retour :

jsx
{
"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 :

- email - Adresse email de votre compte
- 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 :

jsx
{
"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 :

- email - Adresse email de votre compte
- 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 :

jsx
{
"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.
Cet article a-t-il répondu à vos questions ?
Annuler
Merci !