Synchronisation avec les PDP

Cette documentation decrit comment Scell.io synchronise les factures entrantes avec les Plateformes de Dematerialisation Partenaires (PDP).

Table des matieres

1. Vue d'ensemble
2. Synchronisation SuperPDP
3. Evenements synchronises
4. Configuration
5. Gestion des erreurs

---

Vue d'ensemble

La reforme de facturation electronique francaise impose l'utilisation de Plateformes de Dematerialisation Partenaires (PDP) pour l'echange de factures entre entreprises assujetties a la TVA.

Scell.io s'integre avec ces plateformes pour :

• Recevoir automatiquement les factures entrantes
• Synchroniser les statuts (acceptation, rejet, paiement)
• Transmettre les factures sortantes

---

Synchronisation SuperPDP

Mecanisme de polling

Pour les plateformes qui n'exposent pas de webhooks natifs (comme SuperPDP), Scell.io utilise un mecanisme de polling intelligent :

Parametre	Valeur
Frequence	Toutes les 5 minutes
Endpoint	GET /v1.beta/invoice_events
Direction	in (factures entrantes)
Pagination	Par curseur (starting_after_id)

Processus de synchronisation

+---------------+     1. Poll events      +------------+
|   Scell.io    | ----------------------> |  SuperPDP  |
|   Scheduler   |                         |    API     |
+---------------+ <---------------------- +------------+
        |              2. New events
        |
        v
+---------------+
|   Process &   |
|   Store       |
+---------------+
        |
        v
+---------------+     3. Webhook          +------------+
|   Webhook     | ----------------------> |   Client   |
|   Dispatcher  |                         |   Server   |
+---------------+                         +------------+

Persistance du curseur

Pour eviter les doublons et garantir la fiabilite :

• Le curseur (last_event_id) est stocke par tenant
• En cas d'erreur, le curseur n'est pas mis a jour
• La synchronisation reprend au dernier point connu

---

Evenements synchronises

Mapping des evenements

Evenement SuperPDP	Webhook Scell.io	Description
api:received	invoice.incoming.received	Nouvelle facture recue
api:validated	invoice.incoming.validated	Facture validee techniquement
api:accepted	invoice.incoming.accepted	Facture acceptee par le destinataire
api:rejected	invoice.incoming.rejected	Facture rejetee

Evenements geres localement

Certains evenements sont geres uniquement cote Scell.io :

Webhook Scell.io	Description
invoice.incoming.disputed	Contestation ouverte par le client
invoice.incoming.paid	Facture marquee comme payee

---

Configuration

Activation de la synchronisation

Pour activer la synchronisation automatique avec SuperPDP, configurez les credentials dans les parametres du tenant :

curl -X PATCH "https://api.scell.io/api/v1/companies/{id}/settings" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "pdp_provider": "superpdp",
    "pdp_credentials": {
      "client_id": "your_client_id",
      "client_secret": "your_client_secret",
      "environment": "production"
    },
    "sync_enabled": true
  }'

Variables d'environnement (backend)

# SuperPDP Configuration
SUPERPDP_API_URL=https://api.superpdp.fr
SUPERPDP_CLIENT_ID=your_client_id
SUPERPDP_CLIENT_SECRET=your_client_secret

# Sync Configuration
INCOMING_INVOICE_SYNC_ENABLED=true
INCOMING_INVOICE_SYNC_INTERVAL=5

Parametres de synchronisation

Parametre	Description	Defaut
sync_enabled	Active/desactive la synchronisation	true
sync_interval	Intervalle en minutes	5
auto_accept	Acceptation automatique des factures	false
notification_email	Email pour alertes	null

---

Gestion des erreurs

Retry automatique

En cas d'echec de synchronisation :

Tentative	Delai
1ere	Immediate
2eme	+1 minute
3eme	+5 minutes
4eme	+15 minutes
5eme	+1 heure

Apres 5 echecs consecutifs, une alerte est envoyee et la synchronisation est mise en pause.

Codes d'erreur

Code	Description	Action
sync_auth_failed	Authentification SuperPDP echouee	Verifier les credentials
sync_rate_limited	Rate limit atteint	Attendre le reset
sync_parse_error	Erreur de parsing	Contacter le support
sync_duplicate	Facture deja existante	Ignoree automatiquement

Logs et monitoring

Consultez les logs de synchronisation via l'API :

curl "https://api.scell.io/api/v1/sync/logs?from=2026-01-01&limit=100" \
  -H "Authorization: Bearer {token}"

Reponse :

{
  "data": [
    {
      "id": "log_abc123",
      "timestamp": "2026-01-24T14:30:00+00:00",
      "event": "sync_completed",
      "provider": "superpdp",
      "invoices_synced": 5,
      "duration_ms": 1234
    }
  ],
  "meta": {
    "total": 100,
    "last_sync": "2026-01-24T14:30:00+00:00",
    "next_sync": "2026-01-24T14:35:00+00:00"
  }
}

---

Declenchement manuel

Pour forcer une synchronisation immediate :

curl -X POST "https://api.scell.io/api/v1/sync/trigger" \
  -H "Authorization: Bearer {token}"

Reponse :

{
  "message": "Synchronisation declenchee",
  "job_id": "job_xyz789",
  "estimated_completion": "2026-01-24T14:31:00+00:00"
}

---

Support

• Documentation API : https://api.scell.io/api/documentation
• Email : support@scell.io
• Dashboard : https://app.scell.io