Index
- User-agent obligatoire
- Numéro de téléphone mobile obligatoire pour l'expéditeur
- Changement du code HTTP lors de la création d'un document avec succès
- Lors de la création d'un envoi (POST /envois)
- Documents Douaniers
User-agent obligatoire
Le paramètre User-agent doit obligatoirement être renseigné (pour plus d'information sur le User-agent, voir l'article suivant : //datatracker.ietf.org/doc/html/rfc7231#section-5.5.3).
POST //conso.mydelivengo.laposte.fr/api/v2.4/envois API-Authorization: Oono8eez7eez9NRZ3xaeFaeh8hee3u User-Agent: Guzzle/4.0 curl/7.21.4 PHP/5.5.7
Si le User-agent n'est pas défini, une erreur est retournée avec un code HTTP : 403
{
"error": {
"code": 403,
"message": "Forbidden",
"description": "User-agent absent.",
"details": null
}
}
Numéro de téléphone mobile obligatoire pour l'expéditeur
L'objet "EnvoiPli" comporte un nouveau champ : "expediteur_telephone". Ce champ est obligatoire et doit contenir un numéro de téléphone mobile, commençant par un préfixe (+336 / +337 / 00336 / 00337 / 06 / 07), suivi de 8 caractères numériques.
Exemple :
{
"plis": [
{
"expediteur": {
"raison_sociale": "UXEN",
"nom": "NICOLAS MARCHAND",
"complement_voie": "APPARTEMENT 21, ETAGE 3",
"voie": "26 RUE GEORGE SAND",
"boite_postale": "",
"code_postal_commune": "75016 PARIS"
},
"expediteur_telephone": "+33686424360"
}
Changement du code HTTP lors de la création d'un document avec succès
Pour plus de précisions dans les réponses API, les requêtes créant un document (support étiquette) retournent en cas de succès un code HTTP 201, au lieu d'un code 200. Ce changement ne concerne que les requêtes de type POST /envois.
Pour plus d'information sur la liste des codes HTTP, consulter la page suivante : //fr.wikipedia.org/wiki/Liste_des_codes_HTTP
Lors de la création d'un envoi (POST /envois)
Contrôle sur l'adresse expéditeur
Les supports d'étiquettes générés par MyDelivengo sont prévus pour des expéditions depuis la France uniquement. Aussi, si le système détecte une adresse expéditeur qui n'est pas en France, alors une erreur est retournée.
{
"error": {
"code": 400,
"message": "Bad Request",
"description": "Erreur lors de la création de l'envoi.",
"details": {
"data": {
"plis": {
"1": {
"expediteur": "L'adresse expéditeur n'est pas une adresse en France."
}
}
}
}
}
}Support étiquette et numéro de suivi du pli dans la même réponse
Il n'est plus nécessaire d'envoyer deux requêtes API pour obtenir successivement le document de l'étiquette d'expédition et le numéro de suivi du pli. Une seule requête suffit à présent.
Lors de la requête pour obtenir les étiquettes, avec l'entête HTTP définie en "Accept", le numéro de suivi de(s) pli(s) est directement accessible dans le corps de la réponse JSON, dans le champ "numero" de l'objet "plis".
{
"data": {
"id": 1,
"plis": [
{
"id": "1",
"numero": "LL123456789FR"
}
],
"documents_supports": "JVBERi0xLjQKJeLjz9MKMSAwIG9...",
"documents_douaniers": "JVBERi0xLjQKJeLjz9MKMSAwIG9...",
"factures": "JVBERi0xLjQKJeLjz9MKMSAwIG9...",
}
}Impression des références
Une référence est un texte court que l'on souhaite associer à un envoi ou à un pli, bien souvent pour faciliter son identification. L'API MyDelivengo permet d'ajouter 2 références :
- le descriptif de l'envoi (correspondant au champ "descriptif" dans les propriétés de la requête POST /envois)
- la référence du pli (correspondant au champ "reference" dans les propriétés de l'objet "EnvoiPli")
Il est possible à présent d'imprimer ces 2 références avec une seule commande. Lors d'une requête POST /envois, si l'URL contient le paramètre "imprimer_reference=1", la référence du pli et le descriptif de l'envoi sont tous deux imprimés sur l'étiquette. Ce paramètre équivaut dans l'ancienne version au paramètre "imprimer_reference=1&imprimer_descriptif=1"
Voici les différentes possibilités d'impression des références :
Paramètres d'URL | Action |
|---|---|
| imprimer_reference=1 | La référence du pli et le descriptif de l'envoi sont imprimés |
| imprimer_reference=1&imprimer_descriptif=1 | La référence du pli et le descriptif de l'envoi sont imprimés |
| imprimer_reference=1&imprimer_descriptif=0 | Seule la référence du pli est imprimée |
| imprimer_descriptif=1 | Seul le descriptif de l'envoi est imprimé |
Ajout du champ "Téléphone" du destinataire
L’objet "EnvoiPli" dispose d’un nouveau champ "destinataire_telephone", qui permet de renseigner le numéro de téléphone du destinataire.
Nouveaux champs obligatoires
Au moins l’un des champs suivants doit être renseigné :
Mots interdits
Plusieurs champs de l’étiquette d’expédition sont soumis à un contrôle qui refuse la saisie de certains termes. Dans le cas où l’un de ces mots interdits est renseigné, l’API renvoie le message d’erreur suivant :
{
"error": {
"code": 400,
"message": "Bad Request",
"description": "Erreur lors de la création de l'envoi.",
"details": {
"data": {
"plis": {
"1": {
"expediteur": {
"raison_sociale": {
"forbiddenWord": "'UNKNOWN' ne peut pas être utilisé."
}
}
}
}
}
}
}Il est possible de récupérer la liste des mots interdits pour un champ spécifique, en utilisant la requête GET /mots-interdits, avec la variable correspondant au champ concerné :
- expediteur.nom (correspondant au champ "nom" dans l'objet "AdresseNationale")
- expediteur.commune (correspondant au champ "code_postal_commune" dans l'objet "AdresseNationale")
- destinataire.nom (correspondant au champ "nom" dans l'objet "AdresseInternationale")
- destinataire.commune (correspondant au champ "code_postal_commune" dans l'objet "AdresseInternationale")
- description_detaillee (dans l'objet "Article")
Exemple de requête pour obtenir la liste des mots interdits pour le champ "nom" de l'expéditeur :
GET /mots-interdits?champ=expediteur.nom
Exemple de réponse :
{
"data" : {
"expediteur.nom" : ["N/A", "NAME", "NONE", "NOT ENTERED", "NUL", "NOT SPECIFIED", "UNK", "UNKNOWN", "NULL", "JANE DOE", "JOHN DOE", "MICKEY", "MOUSE", "RECIPIENT", "N A N A", "NON GIVEN", "MME", "FA GUO", "FRANKRIKE", "CONSIGNEE"]
}
}Ces listes de mots interdits sont susceptibles d'évoluer.
Messages d'erreur
L'API retourne à présent l'ensemble des erreurs bloquant la création d'un envoi, au lieu de retourner auparavant la première erreur rencontrée.
Exemple de réponse d'erreur sur les versions antérieures à 2.4 :
{
"error": {
"code": 400,
"message": "Bad Request",
"description": "Erreur lors de la création de l'envoi.",
"details": {
"data": {
"plis": {
"1": {
"documents_douaniers": {
"articles": {
"1": {
"description_detaillee": {
"isEmpty": "La description est obligatoire."
}
}
}
}
}
}
}
}
}
}Réponse d'erreur sur la version 2.4 :
{
"error": {
"code": 400,
"message": "Bad Request",
"description": "Erreur lors de la création de l'envoi.",
"details": {
"data": {
"plis": {
"1": {
"documents_douaniers": {
"articles": {
"1": {
"description_detaillee": {
"isEmpty": "La description est obligatoire."
}
}
}
},
"destinataire": {
"raison_sociale": {
"isEmpty": "Cette adresse ne contient pas de nom ni de société."
}
}
}
}
}
}
}
}Cette structure de réponse ne concerne que les erreurs liées à la création d'envoi (POST /envois).
Documents Douaniers
Dans le cas d'envoi de colis pour la zone 2 (hors Union européenne), il est nécessaire de produire des documents douaniers détaillant le contenu de la marchandise expédiée (pour en savoir plus, consulter la page "À quoi servent les documents douaniers ?"). MyDelivengo permet de générer les documents douaniers en même temps que les étiquettes d'envoi.
La création de ces documents douaniers requiert le remplissage de certains champs obligatoires.
Dans l'objet "Article" :
- Le champ "description_detaillee" devient obligatoire. Sa valeur ne doit pas dépasser 256 caractères.
- Le champ "quantite" doit être un nombre entier supérieur à 0.
- Le champ "poids" (valeur en kilogrammes) doit avoir une valeur supérieure à 0 et inférieure ou égale à 2.
- Le champ "num_tarifaire" devient obligatoire. Sa valeur doit contenir au minimum 6 caractères numériques et ne doit pas dépasser les 10 caractères. Le code saisi doit faire partie de la liste des codes SH existants (voir partie plus bas "Récupération de la liste des codes SH").
{
"description_detaillee": "Crème cosmétique",
"quantite": "1",
"poids": "0,20",
"valeur": "32",
"pays_origine": "FRANCE",
"num_tarifaire": "420234"
}Extension du nombre d'articles par pli
(à venir prochainement)
Il sera bientôt possible de renseigner plus de 4 articles dans l'objet "DocumentsDouaniers", jusqu’à 15 articles maximum. Si un pli contient plus de 4 articles, les documents douaniers générés seront de type CN23 (pour en savoir plus sur les différents types de documents douaniers, consulter la page "À quoi servent les documents douaniers ?")
Situation | Documents douaniers générés |
|---|---|
| Le pli contient 4 articles ou moins | Les documents douaniers générés par défaut sont de type CN22 (intégré à l'étiquette) |
| Le pli contient 5 articles ou plus | Les documents douaniers générés par défaut sont de type CN23 (au format A4, à part de l'étiquette) |
Récupération de la liste des codes SH (numéros tarifaires)
(à venir prochainement)
Il est obligatoire de renseigner le code SH (ou numéro tarifaire) dans les documents douaniers pour les envois vers des destinations hors Union européenne.
Il est possible de récupérer la liste des codes SH existants, avec la requête : GET /shcodes
Cette liste est susceptible d'évoluer.
Pays en exception
(à venir prochainement)
Certaines destinations disposent de réglementations douanières spéciales et peuvent être traitées différemment du pays dont elles dépendent.
Par exemple, certains territoires faisant partie d'un pays de l'Union européenne (Zone 1) peuvent requérir des formalités douanières. À l’inverse, il existe certaines destinations d'un pays de la zone 2 pour lesquelles il n’est pas nécessaire de renseigner les documents douaniers.
À partir du code pays et du code postal du destinataire, MyDelivengo générera automatiquement les documents douaniers, selon le statut du pays de destination du pli.
L’utilisateur a la possibilité de vérifier une adresse destinataire et de connaître la zone internationale à laquelle elle est rattachée, en utilisant la requête POST /address-compliancy
Exemple de requête envoyée :
{
"nom": "REBECCA FERNANDEZ",
"complement_voie": "PUERTA 7",
"voie": "AVENIDA VALDEFIERRO N. 27-2-E",
"code_postal_commune : "35290 San Bartolomé de Tirajana",
"code_pays" : "ES"
}Exemple de réponse :
# zone europe mais soumis à la déclaration douanière
{
"data" : {
"zone" : 1,
"formalites_douanieres" : true
}
}
Les différentes valeurs pour la zone sont :
- 1 : Union européenne
- 2 : Reste du monde (hors Union européenne)
Le champ "formalites_douanieres" ne peut indiquer que deux valeurs différentes :
- true : les documents douaniers sont obligatoires
- false : pas de documents douaniers nécessaires
De manière générale, nous vous recommandons de transmettre l’ensemble des informations douanières, quelle que soit la destination. MyDelivengo se charge d’utiliser ou non ces données selon si la destination nécessite la production de documents douaniers. Ainsi, si de nouvelles règles apparaissent pour certaines destinations, vous n’aurez rien à modifier dans votre application.
Numéro EORI
Le numéro EORI, déjà obligatoire pour les envois vers le Royaume-Uni, doit aussi être renseigné pour les destinations suivantes :
- Australie
- Nouvelle Zélande
- Norvège
Un nouveau paramètre "eori" a été ajouté pour pouvoir renseigner les numéros EORI des différents pays concernés. La propriété "uk_eori_number" est toujours active mais sera à terme dépréciée pour être remplacée par la propriété "eori" :
{
"eori": [
{
"code_pays": "NO",
"numero": "NO123456789MVA"
},
{
"code_pays": "GB",
"numero": "GB123456789012"
}
]
}