SYNAPLINK

API Documentation

Documentation complète de l'API SYNAPLINK pour la gestion des flux, l'authentification et la recherche dans l'annuaire.

v1.0

Variables de Collection

Variables utilisées dans les requêtes. Configurez-les avant d'utiliser l'API.

Configuration

{{server}} URL de base du serveur API : https://backend.integration.synaplink.synap6.fr/api
{{token}} Token d'accès JWT (auto-généré après login)
{{refresh_token}} Token de rafraîchissement (auto-généré après login)
{{username}} généré dans le portail client
{{password}} généré dans le portail client

Authentification

Endpoints pour l'authentification OAuth2 via Keycloak. Obtenez un token d'accès pour utiliser les autres endpoints.

POST /realms/synaplink/protocol/openid-connect/token Compte API Login

Authentifie un utilisateur et retourne un token d'accès JWT ainsi qu'un refresh token. Le token d'accès a une durée de vie limitée (25 minutes) et doit être inclus dans l'en-tête Authorization: Bearer {token} de toutes les requêtes authentifiées. Utilisez le scope offline_access pour obtenir un refresh token valide plus longtemps.

URL complète

https://keycloak.integration.synaplink.synap6.fr/realms/synaplink/protocol/openid-connect/token

Headers

Content-Type: application/x-www-form-urlencoded Accept: application/json

Body (x-www-form-urlencoded)

username={{username}}
password={{password}}
grant_type=password
client_id=editeur-logiciel
scope=offline_access

Réponse 200 OK

200 OK 
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "expires_in": 1500,
  "refresh_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "offline_access profile email"
}
POST /realms/synaplink/protocol/openid-connect/token Compte API Refresh Token

Renouvelle le token d'accès sans nécessiter une nouvelle authentification complète. Utilisez cet endpoint lorsque votre token d'accès a expiré mais que votre refresh token est encore valide. Le refresh token a une durée de vie plus longue (1 jour avec offline_access).

URL complète

https://keycloak.integration.synaplink.synap6.fr/realms/synaplink/protocol/openid-connect/token

Headers

Content-Type: application/x-www-form-urlencoded Accept: application/json

Body (x-www-form-urlencoded)

refresh_token={{refresh_token}}
grant_type=refresh_token
client_id=editeur-logiciel

Réponse 200 OK

200 OK 
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "expires_in": 1500,
  "refresh_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "offline_access profile email"
}

Flows

Gestion des flux de documents. Créez, recherchez et récupérez des flux de factures électroniques.

GET /v1/flows/{id} Récupérer un flow par ID Bearer

Télécharge un fichier lié à un flux donné. Le paramètre docType permet de spécifier le type de fichier à télécharger : Metadata (JSON des métadonnées), Original (document source envoyé par l'émetteur), Converted (document converti par le système) ou ReadableView (version lisible générée).

URL

{{server}}/v1/flows/{id}?docType=Original

Headers

Accept: application/json Authorization: Bearer {{token}}

Paramètres Query

docType = Metadata | Original | Converted | ReadableView

Paramètres Path

id (UUID du flow, max 36 caractères)

Réponse 200 OK (docType=Metadata)

200 OK 
{
  "flowId": "550e8400-e29b-41d4-a716-446655440000",
  "trackingId": "TRACKING-facturx-0000115",
  "submittedAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:35:00.000Z",
  "flowType": "CustomerInvoice",
  "flowDirection": "Out",
  "flowSyntax": "UBL",
  "flowProfile": "Basic",
  "processingRule": "B2B",
  "acknowledgement": {
    "status": "Ok"
  }
}
POST /v1/flows Créer un nouveau flow Bearer

Soumet un nouveau flux de facturation électronique. Un flux est un fichier mono-facture avec un fichier XML/PDF contenant les données de la facture. Le flux peut être une facture (CII, UBL, Factur-X), un cycle de vie (CDAR) ou un fichier e-reporting (FRR). Utilisez trackingId pour suivre le flux avec votre propre référence externe.

URL

{{server}}/v1/flows

Headers

Content-Type: multipart/form-data Accept: application/json Authorization: Bearer {{token}}

Body (multipart/form-data)

flowInfo (application/json):
{
  "name": "FAC-0000115",
  "flowSyntax": "UBL",           // CII | UBL | Factur-X | CDAR | FRR
  "flowProfile": "Basic",        // Basic | CIUS | Extended-CTC-FR
  "trackingId": "TRACKING-facturx-0000115",
  "processingRule": "B2B",                // B2B | B2BInt | B2C | OutOfScope | ArchiveOnly
  "processingRuleSource": "Sender",       // Optionnel: Sender | Receiver | PDP | OD | PPF — origine de la règle (transmise telle quelle à la PA)
  "sha256": "a1b2c3d4..."                 // Optionnel: empreinte pour vérification d'intégrité
}

file (application/xml ou application/pdf):
[Fichier XML/PDF de la facture]

Réponse 202 Accepted

202 Accepted 
{
  "flowId": "550e8400-e29b-41d4-a716-446655440000",
  "submittedAt": "2025-01-15T10:30:00.000Z",
  "trackingId": "TRACKING-facturx-0000115",
  "name": "FAC-0000115",
  "flowSyntax": "UBL",
  "flowProfile": "Basic",
  "sha256": "a1b2c3d4e5f6..."
}
POST /v1/flows/search Rechercher des flows Bearer

Recherche et filtre les flux selon différents critères. Au moins un critère doit être spécifié. Les critères sont combinés avec un ET logique, et les valeurs multiples dans un critère sont combinées avec un OU logique. La pagination fonctionne via la propriété updatedAfter. Maximum 100 résultats par requête (défaut: 25).

URL

{{server}}/v1/flows/search

Headers

Content-Type: application/json Accept: application/json Authorization: Bearer {{token}} X-Request-Id: UUID (optionnel, pour corrélation des logs)

Body

{
  "limit": 40,                    // Max: 100, Défaut: 25
  "where": {
    "updatedAfter": "2025-01-01T00:00:00.000Z",
    "updatedBefore": "2025-01-31T23:59:59.999Z",
    "flowDirection": ["Out"],     // In | Out
    "flowType": ["CustomerInvoice", "SupplierInvoice"],
    "ackStatus": "Pending",       // Pending | Ok | Error
    "trackingId": "TRACKING-xxx",
    "processingRule": ["B2B"]     // B2B | B2BInt | B2C | OutOfScope | ArchiveOnly
  }
}

Réponse 200 OK

200 OK 
{
  "limit": 40,
  "filters": {
    "updatedAfter": "2025-01-01T00:00:00.000Z",
    "flowDirection": ["Out"],
    "ackStatus": "Pending"
  },
  "results": [
    {
      "flowId": "550e8400-e29b-41d4-a716-446655440000",
      "trackingId": "TRACKING-001",
      "submittedAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:35:00.000Z",
      "flowType": "CustomerInvoice",
      "flowDirection": "Out",
      "flowSyntax": "UBL",
      "processingRule": "B2B",
      "processingRuleSource": "Sender",
      "acknowledgement": {
        "status": "Pending"
      }
    }
  ]
}

Directory

Recherche dans l'annuaire des entreprises par SIREN, SIRET, code de routage ou ligne d'annuaire.

POST /v1/siren/search Recherche par SIREN Bearer

Recherche multicritères d'entreprises (unités légales). Permet de rechercher par SIREN (9 chiffres), nom commercial, type d'entité ou statut administratif. Utilisez les opérateurs equals, contains ou startsWith pour filtrer les résultats. Utile pour vérifier si un partenaire est inscrit dans l'annuaire.

URL

{{server}}/v1/siren/search

Headers

Content-Type: application/json Accept: application/json Accept-Language: fr | en Authorization: Bearer {{token}}

Body

{
  "filters": {
    "businessName": {
      "op": "contains",           // equals | contains | startsWith
      "value": "ynap"
    },
    "siren": {
      "op": "equals",
      "value": "702042755"
    }
  },
  "sorting": [
    { "field": "siren", "sortingOrder": "ascending" }
  ],
  "fields": ["siren", "businessName", "entityType", "administrativeStatus"],
  "limit": 10,
  "ignore": 0                     // Offset pour pagination
}

Réponse 200 OK

200 OK 
{
  "totalNumberOfResults": 1,
  "results": [
    {
      "siren": "702042755",
      "businessName": "SYNAPLINK SAS",
      "entityType": "PrivatePerson",
      "administrativeStatus": "Active"
    }
  ]
}
POST /v1/siret/search Recherche par SIRET Bearer

Recherche multicritères d'établissements. Le SIRET (14 chiffres = SIREN + NIC) identifie un établissement spécifique. Permet de filtrer par code postal, nom, type d'établissement ou statut. Utile pour cibler une adresse de facturation précise lorsqu'une entreprise possède plusieurs établissements.

URL

{{server}}/v1/siret/search

Headers

Content-Type: application/json Accept: application/json Authorization: Bearer {{token}}

Body

{
  "filters": {
    "postalCode": {
      "op": "strict",
      "value": "750"              // Établissements à Paris
    },
    "siret": {
      "op": "equals",
      "value": "70204275500240"
    }
  },
  "fields": ["siret", "siren", "name", "facilityType", "address", "administrativeStatus"],
  "include": ["siren"],           // Inclure les données de l'unité légale
  "limit": 10,
  "ignore": 0
}

Réponse 200 OK

200 OK 
{
  "totalNumberOfResults": 1,
  "results": [
    {
      "siret": "70204275500240",
      "siren": "702042755",
      "name": "SYNAPLINK - Agence Paris",
      "facilityType": "Secondary",
      "administrativeStatus": "Active",
      "address": {
        "streetNumber": "15",
        "streetName": "Rue de la Paix",
        "postalCode": "75002",
        "city": "Paris",
        "country": "FR"
      }
    }
  ]
}
POST /v1/routing-code/search Recherche par Routing Code Bearer

Recherche par identifiant de routage. Le code de routage est l'adresse technique utilisée pour acheminer les factures électroniques. Il peut être un code service, un code GLN 0224, un code ODETTE 0088 ou un code de gestion interne. Indispensable pour valider la capacité d'un partenaire à recevoir des factures électroniques via Peppol ou les PDP.

URL

{{server}}/v1/routing-code/search

Headers

Content-Type: application/json Accept: application/json Authorization: Bearer {{token}}

Body

{
  "filters": {
    "routingIdentifier": {
      "op": "contains",
      "value": "0224"
    },
    "siret": {
      "op": "equals",
      "value": "70204275500240"
    }
  },
  "fields": ["siret", "routingIdentifier", "routingIdentifierType", "routingCodeName", "administrativeStatus"],
  "include": ["siren", "siret"],
  "limit": 10,
  "ignore": 0
}

Réponse 200 OK

200 OK 
{
  "totalNumberOfResults": 1,
  "results": [
    {
      "siret": "70204275500240",
      "routingIdentifier": "0224:702042755",
      "routingIdentifierType": "GLN",
      "routingCodeName": "Service Comptabilité",
      "administrativeStatus": "Active",
      "managesLegalCommitment": true
    }
  ]
}
POST /v1/directory-line/search Recherche Directory Line Bearer

Recherche avancée dans les lignes d'annuaire. La ligne d'annuaire est l'emplacement où le destinataire souhaite recevoir ses factures (SIREN ou SIREN/SIRET ou SIREN/SIRET/routingIdentifier). Retourne les informations complètes de routage associées à une entreprise avec les relations vers l'unité légale, l'établissement et la plateforme.

URL

{{server}}/v1/directory-line/search

Headers

Content-Type: application/json Accept: application/json Authorization: Bearer {{token}}

Body

{
  "filters": {
    "siren": {
      "op": "strict",
      "value": "702042755"
    },
    "addressingIdentifier": {
      "op": "contains",
      "value": "dcsc456"
    }
  },
  "fields": ["addressingIdentifier", "siren", "siret", "routingIdentifier", "dateFrom", "dateTo"],
  "include": ["siren", "siret", "routingCode", "platform"],
  "limit": 10,
  "ignore": 0
}

Réponse 200 OK

200 OK 
{
  "totalNumberOfResults": 1,
  "results": [
    {
      "addressingIdentifier": "dcsc456sdcsdcs556",
      "siren": "702042755",
      "siret": "70204275500240",
      "routingIdentifier": "0224:702042755",
      "dateFrom": "2025-01-01",
      "dateTo": null,
      "legalUnit": {
        "businessName": "SYNAPLINK SAS",
        "administrativeStatus": "Active"
      },
      "platform": {
        "platformType": "PDP",
        "platformStatus": "Active"
      }
    }
  ]
}

Webhooks

Gestion des webhooks pour recevoir des notifications en temps réel sur les événements de facturation. Supporte l'authentification par headers personnalisés ou Basic Auth.

POST /v1/webhooks Créer un webhook Bearer

Enregistre un nouveau webhook. Permet de recevoir des notifications automatiques lors d'événements liés à vos flux de facturation. Deux méthodes de vérification sont supportées : headers personnalisés ou BASIC Auth. Trois types de flux sont disponibles : factures d'achats, cycles de vie factures d'achats, cycles de vie factures de ventes.

URL

{{server}}/v1/webhooks

Headers

Content-Type: application/json Accept: application/json Authorization: Bearer {{token}}

Body

{
  "callback": {
    "url": "https://mon-serveur.com/webhook",
    "authentication": {               // Option 1 : Basic Auth
      "authType": "BASIC",
      "userId": "mon_utilisateur_api",
      "userPassword": "mot_de_passe_robuste_123"
    },
    "headers": [                      // Option 2 : Headers personnalisés
      {
        "headerName": "X-Custom-Token",
        "headerValue": "secret-123"
      }
    ]
  },
  "metadata": {
    "flowType": "SupplierInvoice",    // Voir types supportés ci-dessous
    "flowDirection": "In"
  }
}

Types de flux supportés (metadata.flowType)

SupplierInvoice — Factures d'achats SupplierInvoiceLC — Cycles de vie factures d'achats CustomerInvoiceLC — Cycles de vie factures de ventes

Réponse 201 Created

201 Created 
{
  "webhookId": "2529623b-85c8-4267-87b0-bbf47f1175d9"
}
GET /v1/webhooks Lister les webhooks Bearer

Retourne la liste des identifiants de webhooks. Un administrateur peut filtrer par client via le query param client_id.

URL

{{server}}/v1/webhooks

Headers

Authorization: Bearer {{token}}

Paramètres Query

client_id (optionnel, admin uniquement)

Réponse 200 OK

200 OK 
{
  "webhookIds": [
    "2529623b-85c8-4267-87b0-bbf47f1175d9",
    "a1b2c3d4-0000-1111-2222-333344445555"
  ]
}
GET /v1/webhooks/{webhookId} Détail d'un webhook Bearer

Retourne la configuration complète d'un webhook. Inclut le callback, les métadonnées, le statut et le client associé.

URL

{{server}}/v1/webhooks/{webhookId}

Paramètres Path

webhookId (UUID du webhook)

Réponse 200 OK

200 OK 404 Not Found 
{
  "webhookId": "2529623b-85c8-4267-87b0-bbf47f1175d9",
  "callback": {
    "url": "https://mon-serveur.com/webhook",
    "authentication": {
      "authType": "BASIC",
      "userId": "mon_utilisateur_api"
    },
    "headers": [
      { "headerName": "X-Custom-Token", "headerValue": "secret-123" }
    ]
  },
  "metadata": {
    "flowType": "SupplierInvoice",
    "flowDirection": "In"
  },
  "client_id": "6a0f1c5c887ac7f8970c4067",
  "status": "active"
}
PATCH /v1/webhooks/{webhookId} Mettre à jour un webhook Bearer

Modifie partiellement la configuration d'un webhook. Seuls les champs envoyés sont mis à jour. Permet de changer les headers, l'authentification ou la signature.

URL

{{server}}/v1/webhooks/{webhookId}

Headers

Content-Type: application/json Authorization: Bearer {{token}}

Body

{
  "headers": [
    {
      "headerName": "X-New-Token",
      "headerValue": "nouveau-secret"
    }
  ],
  "authentication": {
    "authType": "BASIC",
    "userId": "nouvel_utilisateur",
    "userPassword": "nouveau_mdp"
  }
}

Réponse 204 No Content

204 No Content 404 Not Found 
// Corps vide en cas de succès
DELETE /v1/webhooks/{webhookId} Supprimer un webhook Bearer

Supprime définitivement un webhook. Les événements en cours de traitement ne seront plus notifiés après suppression.

URL

{{server}}/v1/webhooks/{webhookId}

Réponse 204 No Content

204 No Content 404 Not Found 
// Corps vide en cas de succès

Health

Vérification de l'état du service API.

GET /v1/healthcheck Vérifier l'état du service

Vérifie si le service API est en ligne et opérationnel. Cet endpoint ne nécessite aucune authentification et retourne un statut 200 OK si le service fonctionne correctement. Idéal pour les systèmes de monitoring, les health checks Kubernetes et les scripts de surveillance automatisés.

URL

{{server}}/v1/healthcheck

Codes de réponse

200 OK 500 / 503 
// 200 OK : Service opérationnel, corps vide

// 500 Internal Server Error :
{
  "errorCode": "INTERNAL_ERROR",
  "errorMessage": null
}

// 503 Service Unavailable :
{
  "errorCode": "RESOURCE_ERROR",
  "errorMessage": null
}

Outils

POST /validateur/facturx Validateur fichier Factur-X Bearer

Ce validateur vérifie la conformité de vos factures Factur-X en contrôlant le XML embarqué (validation XSD), les métadonnées XMP, la relation AFRelationship, ainsi que la conformité PDF/A-3 via veraPDF. Les résultats incluent les erreurs bloquantes et les avertissements pour vous aider à corriger vos documents.

URL

{{server}}/validateur/facturx?schematrons=false

Query parameters

schematrons (boolean, optionnel, défaut: false)
Active la validation Schematron (règles métier EN 16931 / CIUS / Extended) en complément
de la validation XSD + PDF/A-3. Les erreurs et warnings Schematron sont fusionnés
dans la réponse, et le détail brut est exposé sous details.schematron.

Headers

Content-Type: multipart/form-data Accept: application/json Authorization: Bearer {{token}}

Body (multipart/form-data)

file (application/pdf ou application/xml):
[Factur-X PDF, ou XML CII/UBL pour validation XML seule]

Réponse 200 Success

200 Success 
{
  "valid": "true",
  "errors": "[]",
  "warnings": "[]",
  "details": "[]",
}