Créer une vente

L'API créer une vente permet aux utilisateurs de l'OD de créer une vente sans facture

Les ventes sans facture sont utilisées dans les cas de ventes B2B International, B2C et quelques autres cas particuliers

Les ventes sans facture ne donnent pas lieu à la génération ou à l'envoi de documents, mais sont utilisées uniquement pour générer les données de e-reporting correspondantes

Pré-requis

• Posséder un compte OD
• Avoir créé une connexion PDP ou PPF
• Avoir des données de facturation

Requête

Pour créer une vente on fait une requête POST sur le chemin d'accès suivant:

v1/ventes

On doit passer:

• L'identifiant utilisateur de l'OD dans l'en-tête X-OD-User-ID
• Au format JSON dans le corps de la requête :
  • Les données de vente
  • Les pièces jointes éventuelles

Par exemple:

cURL

Requête de création d'une vente

curl \
-X POST \
-H 'X-OD-User-ID: ${userId}' \
-H 'Content-Type: application/json; charset=utf-8' \
-d @vente.json \
http://<host>:<port>/v1/ventes

Typescript

Requête de création d'une vente

const url = 'http://<host>:<port>/v1/ventes'
const data: string = fs.readFileSync('vente.json');
const response: AxiosResponse = await axios.post(url, data, {
    headers: {
        'X-OD-User-ID': userId,
        'Content-Type': 'application/json; charset=utf-8',
    }
});
...
// récupération de l'URI de la nouvelle ressource
const uri: string = response.headers['location'];

Fichier vente.json

{
    "siren": "810319517",
    "description": "Imprimante Canon PIXMA MG3650",
    "dateRealisation": "2024-02-02T15:06:31.865Z",
    "codeDevise": "EUR",
    "codeDatePaiementTva": "29",
    "categorie": "TLB1",
    "montantTotalHt": 1234.56,
    "montantTotalTva": 246.91,
    "nombreTransactions": 1,
    "repartitionTva": [
        {
            "taux": 20.0,
            "baseImposition": 1234.56,
            "montantTva": 246.91
        }
    ],
    "piecesJointes": [
        {
          "nomFichier": "ticket_de_caisse.pdf",
          "contentType": "application/pdf",
          "base64": "PHN2ZyBoZWlnaHQ9IjI2IiB4bWxucz0iaHR0cDov..."
        }
    ]
}

Propriétés	Valeur	Requis
siren	Numéro SIREN de l'entreprise vendeuse	Non si l'utilisateur n'a qu'une entreprise
description	Description de la vente	Non (mais fortement conseillé)
dateRealisation	Date de réalisation de la prestation de service ou date de livraison des biens	Oui
codeDevise	Code ISO 4217	Non (par défaut EUR)
codeDatePaiementTva	Options de paiement	Oui
Catégorie	Catégorie de transaction	Oui
montantTotalHt	Montant total hors taxes	Oui
montantTotalTva	Montant total TVA	Oui
nombreTransactions	Nombre de transactions composant cette vente	Oui
repartitionTva[i].taux	Taux de TVA	Oui
repartitionTva[i].baseImposition	Base d'imposition	Oui
repartitionTva[i].montantTva	Montant TVA	Oui
piecesJointes[i].nomFichier	Nom de fichier	Oui
piecesJointes[i].contentType	Type du contenu	Oui
piecesJointes[i].base64	Fichier encodé en Base64	Oui

Réponse

Si tout s'est bien passé, la réponse de l'OD est 201 CREATED avec l'en-tête Location contenant l'emplacement de la ressource:

Réponse type de l'OD pour la création d'un compte utilisateur

HTTP/1.1 201 Created
X-Powered-By: Express
X-RateLimit-Limit: 12000
X-RateLimit-Remaining: 11998
X-RateLimit-Reset: 60
Content-Type: application/json; charset=utf-8
Content-Length: 45
ETag: W/"2d-SVoQrUQ9lw1spmQdDLKIlsOgr98"
Date: Thu, 11 Jan 2024 13:45:47 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Location: v1/ventes/26ad3a21-615e-40ea-a05a-2ac8e8a2f373

Erreurs

Si une erreur s'est produite, les codes et messages suivants peuvent être retournés:

Code	Message
400 Bad Request	Requête invalide - Voir messages d'erreur
401 Unauthorized	Informations d'authentification invalides
403 Forbidden	Droits insuffisants pour effectuer cette action

Impact

• Une vente sans facture a été créée dans l'OD
• Une déclaration de transaction a été ajoutée automatiquement aux données de e-reporting en attente de transmission
• A tout moment, il est possible de:
  • Retrouver cette vente via l'API parcourir les ventes
  • Consulter la vente via l'API consulter une vente