IPS Diffusion API

API REST pour la gestion de distribution de magazines

URL de base : https://your-domain/api/

Format : application/ld+json et application/json

Authentification : JWT Bearer Token

S'authentifier

Obtenir un token JWT pour acceder a l'API

Lister les clients

Recuperer la liste paginee des clients

Creer un bon de livraison

Generer un BL pour un client

Authentification

L'API utilise l'authentification JWT (JSON Web Token). Obtenez un token via le endpoint de connexion, puis incluez-le dans chaque requete.

Connexion

POST /api/login

curl -X POST https://your-domain/api/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "your-password"}'

Reponse :

{
  "token": "eyJhbGci...",
  "refresh_token": "abc123...",
  "user": {
    "id": 1,
    "email": "admin@example.com",
    "roles": ["ROLE_ADMIN"]
  }
}

Utilisation du token

Incluez le token dans l'en-tete Authorization de chaque requete :

Authorization: Bearer eyJhbGci...

Rafraichir le token

POST /api/token/refresh

{
  "refresh_token": "abc123..."
}

Duree de validite

Access token : 2 heures
Refresh token : 30 jours

Reinitialisation du mot de passe

Methode	URL	Description
POST	/api/forgot-password	Demande de reinitialisation
POST	/api/reset-password	Reinitialisation avec token

Clients

Gestion des boutiques et points de vente. Chaque client peut etre de type direct (facture a la livraison) ou depot_vente (facture apres validation des invendus).

Methode	URL	Description
GET	/api/clients	Liste paginee
GET	/api/clients/{id}	Detail d'un client
POST	/api/clients	Creation
PUT	/api/clients/{id}	Mise a jour complete
PATCH	/api/clients/{id}	Mise a jour partielle
DELETE	/api/clients/{id}	Suppression (ADMIN)

Filtres disponibles

Parametre	Type	Description
companyName	ipartial	Recherche partielle sur le nom
ipsRef	ipartial	Recherche par reference IPS
email	ipartial	Recherche par email
status	exact	Filtrer par statut (active, inactive)
clientType	exact	Filtrer par type (direct, depot_vente)
deliveryZone	exact	Filtrer par zone de livraison

Exemple de requete

GET /api/clients?page=1&companyName=paris&status=active

curl -X GET "https://your-domain/api/clients?page=1&companyName=paris&status=active" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Accept: application/ld+json"

Reponse (JSON-LD) :

{
  "@context": "/api/contexts/Client",
  "@id": "/api/clients",
  "@type": "hydra:Collection",
  "hydra:totalItems": 42,
  "hydra:member": [
    {
      "@id": "/api/clients/1",
      "@type": "Client",
      "id": 1,
      "companyName": "Tabac Presse Paris 9e",
      "ipsRef": "CLI-001",
      "email": "contact@tabac-paris9.fr",
      "clientType": "direct",
      "status": "active"
    }
  ],
  "hydra:view": {
    "@id": "/api/clients?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/api/clients?page=1",
    "hydra:last": "/api/clients?page=3",
    "hydra:next": "/api/clients?page=2"
  }
}

Creer un client

POST /api/clients

curl -X POST https://your-domain/api/clients \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/ld+json" \
  -d '{
    "companyName": "Maison de la Presse Lyon",
    "email": "contact@mdp-lyon.fr",
    "phone": "04 72 00 00 00",
    "clientType": "direct",
    "status": "active",
    "billingAddress": {
      "street": "15 rue de la Republique",
      "postalCode": "69001",
      "city": "Lyon",
      "country": "FR"
    }
  }'

Fournisseurs

Editeurs et fournisseurs de magazines. Chaque fournisseur est lie a un ou plusieurs titres de presse.

Methode	URL	Description
GET	/api/suppliers	Liste paginee
GET	/api/suppliers/{id}	Detail d'un fournisseur
POST	/api/suppliers	Creation
PUT	/api/suppliers/{id}	Mise a jour complete
PATCH	/api/suppliers/{id}	Mise a jour partielle
DELETE	/api/suppliers/{id}	Suppression (ADMIN)

Filtres disponibles

Parametre	Type	Description
companyName	ipartial	Recherche partielle sur le nom
email	ipartial	Recherche par email

Magazines

Titres de presse et publications. Chaque magazine est lie a un fournisseur et possede un taux de TVA par defaut.

Methode	URL	Description
GET	/api/magazines	Liste paginee
GET	/api/magazines/{id}	Detail d'un magazine
POST	/api/magazines	Creation
PUT	/api/magazines/{id}	Mise a jour complete
PATCH	/api/magazines/{id}	Mise a jour partielle
DELETE	/api/magazines/{id}	Suppression (ADMIN)

Filtres disponibles

Parametre	Type	Description
title	ipartial	Recherche par titre
ipsRef	ipartial	Recherche par reference IPS
supplier.companyName	ipartial	Recherche par nom de fournisseur
status	exact	Filtrer par statut

Parutions

Numeros et editions de magazines. Chaque parution est liee a un magazine et gere le stock via les quantites livrees, retournees et vendues.

Methode	URL	Description
GET	/api/issues	Liste paginee
GET	/api/issues/{id}	Detail d'une parution
POST	/api/issues	Creation
PUT	/api/issues/{id}	Mise a jour complete
PATCH	/api/issues/{id}	Mise a jour partielle
DELETE	/api/issues/{id}	Suppression (ADMIN)

Filtres disponibles

Parametre	Type	Description
issueNumber	ipartial	Recherche par numero
magazine.id	exact	Filtrer par magazine
status	exact	Filtrer par statut

Abonnements

Liens entre clients et magazines avec quantites et dates de validite. Un abonnement est actif s'il n'a pas de date de fin ou si la date de fin est superieure ou egale a aujourd'hui.

Methode	URL	Description
GET	/api/subscriptions	Liste paginee
GET	/api/subscriptions/{id}	Detail d'un abonnement
POST	/api/subscriptions	Creation
PUT	/api/subscriptions/{id}	Mise a jour complete
DELETE	/api/subscriptions/{id}	Suppression

Filtres disponibles

Parametre	Type	Description
client.id	exact	Filtrer par client
magazine.id	exact	Filtrer par magazine

Livraisons

Bons de livraison (BL). Chaque client recoit un BL par date de livraison. La validation d'un BL declenche automatiquement la creation des bordereaux d'invendus (BI) correspondants.

Methode	URL	Description
GET	/api/delivery_orders	Liste paginee
GET	/api/delivery_orders/{id}	Detail d'un bon de livraison
POST	/api/delivery_orders	Creation
PATCH	/api/delivery_orders/{id}	Mise a jour partielle
DELETE	/api/delivery_orders/{id}	Suppression (brouillon uniquement)
POST	/api/delivery_orders/generate	Generation automatique depuis les abonnements

Filtres disponibles

Parametre	Type	Description
client.id	exact	Filtrer par client
client.companyName	ipartial	Recherche par nom de client
status	exact	Filtrer par statut (draft, validated, cancelled)

Regle metier importante

Lorsqu'un bon de livraison passe au statut validated, le systeme cree automatiquement les bordereaux d'invendus (BI) correspondants, groupes par mois/annee de la date d'invendu des parutions.

Invendus

Bordereaux d'invendus (BI) et periodes de retour. Les periodes de retour sont creees automatiquement (par mois/annee). Chaque client a un BI par periode.

Periodes de retour

Methode	URL	Description
GET	/api/return_periods	Liste des periodes (auto-crees)
GET	/api/return_periods/{id}	Detail d'une periode

Bordereaux d'invendus

Methode	URL	Description
GET	/api/return_orders	Liste paginee
GET	/api/return_orders/{id}	Detail d'un bordereau
POST	/api/return_orders	Creation
PATCH	/api/return_orders/{id}	Mise a jour partielle
DELETE	/api/return_orders/{id}	Suppression (brouillon uniquement)

Filtres disponibles

Parametre	Type	Description
returnPeriod.id	exact	Filtrer par periode de retour
returnPeriod.month	exact	Filtrer par mois
returnPeriod.year	exact	Filtrer par annee
client.id	exact	Filtrer par client
status	exact	Filtrer par statut

Facturation

Factures et avoirs. Les factures sont generees a partir des bons de livraison, les avoirs a partir des bordereaux d'invendus. Les montants sont ventiles par taux de TVA (2.10%, 5.50%, 20%).

Factures

Methode	URL	Description
GET	/api/invoices	Liste paginee
GET	/api/invoices/{id}	Detail d'une facture
POST	/api/invoices	Creation
PATCH	/api/invoices/{id}	Mise a jour partielle
DELETE	/api/invoices/{id}	Suppression (brouillon uniquement)

Avoirs

Methode	URL	Description
GET	/api/credit_notes	Liste paginee
GET	/api/credit_notes/{id}	Detail d'un avoir
POST	/api/credit_notes	Creation
PATCH	/api/credit_notes/{id}	Mise a jour partielle
DELETE	/api/credit_notes/{id}	Suppression (brouillon uniquement)

Rapports & Exports

Rapports de distribution, ventes et chiffre d'affaires. Tous les rapports sont exportables au format Excel (PhpSpreadsheet).

Rapport de distribution

Methode	URL	Description
GET	/api/reports/distribution?week={n}&year={n}	Rapport hebdomadaire par titre
GET	/api/reports/distribution/export?week={n}&year={n}	Export Excel

Rapport de ventes

Methode	URL	Description
GET	/api/reports/sales?type={type}&startDate={}&endDate={}	Ventes par fournisseur, client ou titre
GET	/api/reports/sales/export?type={type}&startDate={}&endDate={}	Export Excel

Valeurs possibles pour type :

by_supplier by_client by_title

Chiffre d'affaires

Methode	URL	Description
GET	/api/reports/revenue?startDate={}&endDate={}	CA par client, ventile par TVA
GET	/api/reports/revenue/export?startDate={}&endDate={}	Export Excel

Export d'entites

Methode	URL	Description
GET	/api/export/clients	Export clients (Excel)
GET	/api/export/magazines	Export magazines (Excel)
GET	/api/export/suppliers	Export fournisseurs (Excel)

Emails & PDF

Generation de PDF et envoi par email. Les PDF sont generes via DomPDF et archives sur le serveur. La reimpression renvoie le fichier archive sans recalcul.

Envoi par email

Methode	URL	Description
POST	/api/delivery-orders/{id}/send-email	Envoyer un bon de livraison
POST	/api/return-orders/{id}/send-email	Envoyer un bordereau d'invendus
POST	/api/invoices/{id}/send-email	Envoyer une facture
POST	/api/credit-notes/{id}/send-email	Envoyer un avoir

Generation PDF

Methode	URL	Description
GET	/api/delivery-orders/{id}/pdf	PDF bon de livraison
GET	/api/return-orders/{id}/pdf	PDF bordereau d'invendus
GET	/api/invoices/{id}/pdf	PDF facture
GET	/api/credit-notes/{id}/pdf	PDF avoir

Exemple d'envoi par email

curl -X POST https://your-domain/api/invoices/42/send-email \
  -H "Authorization: Bearer eyJhbGci..."

Reponse :

{
  "message": "Email envoyé avec succès",
  "emailSentAt": "2026-04-17T10:30:00+02:00"
}

Journal d'activite

Journal en lecture seule des modifications d'entites. Le suivi est automatique via le ActivityLogListener (Doctrine). 10 elements par page.

Methode	URL	Description
GET	/api/activity_logs	Liste paginee (10 par page)
GET	/api/activity_logs/{id}	Detail d'une entree

Entites suivies

Client Supplier Magazine DeliveryOrder ReturnOrder Invoice CreditNote Subscription

Exemple de reponse :

{
  "@type": "ActivityLog",
  "id": 156,
  "entityType": "Client",
  "entityId": 42,
  "action": "update",
  "changes": {
    "status": ["active", "inactive"]
  },
  "createdAt": "2026-04-17T09:15:00+02:00"
}

Utilisateurs

Gestion des utilisateurs du systeme. Toutes les operations de gestion (sauf /api/me) requierent le role ROLE_ADMIN.

Methode	URL	Description
GET	/api/me	Utilisateur connecte (ROLE_USER)
GET	/api/users	Liste des utilisateurs (ADMIN)
GET	/api/users/{id}	Detail d'un utilisateur (ADMIN)
POST	/api/users	Creation (ADMIN)
PATCH	/api/users/{id}	Mise a jour (ADMIN)
DELETE	/api/users/{id}	Suppression (ADMIN)

Codes de reponse

L'API utilise les codes HTTP standards. Voici les codes les plus courants :

Code	Nom	Description
200	OK	Requete reussie
201	Created	Ressource creee avec succes
204	No Content	Suppression reussie (pas de corps de reponse)
400	Bad Request	Requete invalide (syntaxe, parametres manquants)
401	Unauthorized	Token manquant ou invalide
403	Forbidden	Droits insuffisants (role manquant)
404	Not Found	Ressource introuvable
422	Unprocessable Entity	Erreur de validation des donnees
429	Too Many Requests	Limite de requetes atteinte
500	Internal Server Error	Erreur interne du serveur

Exemple de reponse d'erreur

{
  "@context": "/api/contexts/ConstraintViolationList",
  "@type": "ConstraintViolationList",
  "hydra:title": "An error occurred",
  "hydra:description": "companyName: Cette valeur ne doit pas être vide.",
  "violations": [
    {
      "propertyPath": "companyName",
      "message": "Cette valeur ne doit pas être vide.",
      "code": "c1051bb4-d103-4f74-8988-acbcafc7fdc3"
    }
  ]
}

Pagination & Filtrage

Toutes les collections sont paginées par defaut (20 elements par page). Utilisez les parametres de requete pour naviguer et filtrer les resultats.

Parametres de pagination

Parametre	Defaut	Description
page	1	Numero de page
itemsPerPage	20	Nombre d'elements par page (max 100)

Filtres de recherche

Les filtres ipartial effectuent une recherche insensible a la casse. Les filtres exact requierent une correspondance exacte.

# Recherche partielle + filtre exact + pagination
GET /api/clients?companyName=paris&status=active&page=2&itemsPerPage=10

Tri des resultats

Utilisez le parametre order pour trier les resultats :

# Tri par date de creation decroissante, puis par nom
GET /api/clients?order[createdAt]=desc&order[companyName]=asc

Navigation dans les pages

La reponse JSON-LD contient les liens de navigation dans hydra:view :

{
  "hydra:totalItems": 142,
  "hydra:view": {
    "@id": "/api/clients?page=2",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/api/clients?page=1",
    "hydra:previous": "/api/clients?page=1",
    "hydra:next": "/api/clients?page=3",
    "hydra:last": "/api/clients?page=8"
  }
}

Explorateur d'API

Testez les endpoints directement depuis l'interface Swagger UI interactive. Authentifiez-vous d'abord via le endpoint de connexion, puis utilisez le bouton "Authorize" pour configurer votre token.

Swagger UI

Ouvrir dans un nouvel onglet