Aller au contenu
Summapar ARKKAD
Menu

Documentation API · Summa

Des connexions claires, des données à leur place.

Lire et créer les documents commerciaux avec des accès dédiés, puis convertir les temps de Chron en facturation.

Avant le premier appel

Préparez un échange dans votre organisation.

  1. Choisir la donnée et l’outil qui la gère.
  2. Créer un accès dédié avec les droits nécessaires dans le destinataire.
  3. Vérifier la correspondance des organisations, établissements et projets : leurs identifiants locaux peuvent différer.
  4. Tester d’abord une lecture, puis une écriture et sa reprise sur des données de test.
  5. Planifier les workers nécessaires et surveiller leurs échecs avant une utilisation automatique.

L’origine publique est https://summa.arkkad.fr. Les exemples utilisent des jetons fictifs à remplacer sur votre serveur.

Identité et permissions

La connexion commune et l’accès API ont chacun leur rôle.

Authentification Summa

Chaque appel métier /api/v1 requiert un client API actif associé à un établissement, authentifié avec Authorization: Bearer ou X-API-KEY. Les deux en-têtes doivent contenir le même jeton s’ils sont présents ensemble. Le jeton doit disposer des scopes requis ; la limite de requêtes est appliquée au client.

Droits nécessaires

clients:read/write, devis:read/write, factures:read/write, articles:read/write, pipelr:sync, chron:read, chron:configure, chron:import et chron:invoice. La conversion d’un devis exige devis:write et factures:write ; la création de facture depuis Chron exige chron:invoice et factures:write.

Paramètres et format

Les listes utilisent page et limit (20 par défaut, 100 maximum). Les écritures externes nécessitent X-Arkkad-Org-Id, X-Arkkad-Request-Id et Idempotency-Key. Les correspondances ARKKAD_ORG_MAPPINGS relient l’organisation source à l’établissement Summa.

Une responsabilité par donnée

Qui possède la donnée de référence ?

La donnée est corrigée dans son outil de référence. Les autres outils en utilisent une lecture ou une projection liée à son identité ; ils ne deviennent pas une seconde source concurrente.

Outil de référenceDonnées gérées
ARKKADComptes, organisations, membres et accès
PipelrClients et contacts commerciaux
UnissonDossiers RH et contrats
ChronProjets, tâches et temps
SummaDevis, factures et paiements
CadenceContenus, validations et publications
QuantyVisites, événements et parcours web

Le rôle de Summa dans les échanges

Summa est la référence pour les devis, factures et paiements. Les clients commerciaux reçus de Pipelr sont des projections avec identité et version. Les événements plus anciens sont ignorés ; une même version avec un contenu divergent ouvre un conflit à résoudre. Les temps restent rattachés à leur identifiant Chron.

Référence utile

Les routes à utiliser pour cette intégration.

Les éléments entre accolades sont des identifiants à remplacer. Ce catalogue présente les routes liées aux échanges ; les interfaces internes disposent d’autres routes.

MéthodeCheminAccèsUtilisation
GET/api/v1/clientsclients:readClients de l’établissement.
GET|POST/api/v1/devisdevis:read / devis:writeLister ou créer les devis.
POST/api/v1/devis/{id}/convert-to-facturedevis:write + factures:writeTransformer un devis en facture.
GET|POST/api/v1/facturesfactures:read / factures:writeLister ou créer des factures.
POST/api/v1/factures/{id}/validerfactures:writeValider une facture.
POST/api/v1/sync/pipelr/eventspipelr:syncProjeter un événement commercial autorisé.
GET|POST|DELETE/api/v1/sync/chron/configchron:read / chron:configureConfigurer le lien et le jeton Chron.
GET/api/v1/sync/chron/entrieschron:readLire les temps Chron.
POST/api/v1/sync/chron/importchron:importImporter les temps.
POST/api/v1/sync/chron/create-invoicechron:invoice + factures:writePréparer une facture depuis les temps importés.

Premier contrôle

Commencez par une lecture.

curl --request GET 'https://summa.arkkad.fr/api/v1/factures?page=1&limit=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer VOTRE_JETON'

Utilisez les cookies et jetons uniquement côté serveur. Ne placez pas de secret dans le JavaScript public, l’URL d’une page ou un exemple partagé.

Lire la réponse

Extrait illustratif avec des identifiants fictifs ; les objets métier peuvent contenir d’autres champs.

{
    "data": [
        {
            "ID": 12,
            "NOM": "Entreprise exemple"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 20,
        "total": 1,
        "total_pages": 1
    }
}

Traiter les réponses

Un échange doit pouvoir être vérifié et repris.

Accès refusé

401 : vérifier le jeton ou la session. 403 : vérifier les droits, le projet et la protection CSRF. La forme exacte de l’erreur dépend de l’outil.

Donnée invalide ou introuvable

400 ou 422 : corriger le JSON, les champs requis et les identifiants. 404 peut indiquer une ressource absente ou hors du périmètre autorisé.

Service indisponible

Sur une erreur réseau ou 5xx, conserver l’identité de l’opération. Avant de réessayer une création, vérifier si le destinataire l’a reçue. Respecter Retry-After lorsqu’un 429 le fournit.

Contrôlez le statut HTTP et l’accusé de réception JSON. Un code HTTP 200, une entrée de journal ou un bouton disponible ne suffisent pas à prouver qu’une donnée a été synchronisée. Gardez l’identifiant source et l’identifiant reçu pour retrouver la même opération.

Périmètre vérifié dans le code

Les points à connaître avant l’automatisation.

  • Les organisations ARKKAD et les établissements Summa n’ont pas nécessairement le même identifiant : le mapping est obligatoire.
  • Envoyer Idempotency-Key ne garantit pas à lui seul que toutes les routes dédupliquent leurs écritures. Vérifiez le comportement de la route avant une reprise automatique.
  • Les workers d’événements et les connexions Chron doivent être configurés et supervisés séparément de la connexion SSO.
  • Le retour des factures vers Pipelr utilise un jeton invoices:sync par organisation (PIPELR_SYNC_TOKENS_JSON). Le SSO ne configure pas ces secrets de connexion.

Cette documentation décrit le code local examiné. L’activation des accès, des workers et des connexions doit être vérifiée dans chaque environnement.