Aller au contenu principal

Votre premier appel

Vous avez reçu vos identifiants OAuth et obtenu un access token (Authentification). Cette page vous amène à votre première requête authentifiée réussie et vous donne votre workspace_id, l'identifiant de votre espace de travail nécessaire aux appels suivants. Il n'y a pas de sandbox : vous appelez la production avec votre compte de production. Les deux endpoints de cette page sont des lectures : ils ne créent rien, n'envoient rien vers un tiers et ne modifient rien dans le workspace - c'est exactement pour cela qu'ils constituent le premier appel.

Étape 1 : vérifier que l'API répond​

GET /api/v1/health confirme que l'API est joignable, sans authentification.

curl https://app.scribee.tech/api/v1/health
{
  "status": "ok"
}

Cet endpoint répond status: "ok" dès qu'il est joignable ; il ne publie pas de métriques de disponibilité. Il accepte 60 requêtes par minute et par adresse IP.

Étape 2 : lister vos workspaces​

GET /api/v1/workspaces retourne les workspaces (espaces de travail) auxquels votre client OAuth a accès ; le scope read suffit.

curl https://app.scribee.tech/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Réponse abrégée aux champs utiles ici (chaque workspace porte aussi created_at et updated_at) :

{
  "data": [
    {
      "id": 42,
      "name": "ACME Workspace"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

La liste est paginée (page, per_page - 20 par défaut, 100 au maximum) et triable (sort_by : name, created_at ou updated_at ; sort_order : asc ou desc ; tri par défaut : name croissant). L'enveloppe data + meta et la pagination sont la règle sur les endpoints de liste, mais pas une garantie universelle : quelques listes bornées par nature - les paiements d'une facture, par exemple - renvoient data seul, sans meta et sans pagination. Les exceptions sont recensées dans Conventions de l'API ; ne codez pas en dur la présence de meta.

Un tableau data vide n'est pas une erreur : soit aucun workspace n'a encore été rattaché à votre client OAuth (demandez le rattachement à votre contact Scribee), soit l'allowlist IPv4 des workspaces concernés exclut votre adresse IP (voir plus bas).

Étape 3 : construire vos prochains appels​

Le champ id de chaque workspace est le workspace_id. Les endpoints qui listent ou créent des ressources sont imbriqués sous /api/v1/workspaces/{workspace_id}/ : par exemple, les factures du workspace 42 se listent sur /api/v1/workspaces/42/invoices. Les endpoints qui portent sur une ressource déjà identifiée référencent le plus souvent cette ressource directement par son id, sans workspace_id dans le chemin. Relevez cet identifiant une fois ; il est stable dans le temps.

Ce qui se passe ensuite​

  • Rien. Ces deux appels n'ont aucun effet de bord : aucune ressource créée, aucune transmission vers le PPF (Portail Public de Facturation), le réseau Peppol ou un destinataire. Vous pouvez les rejouer autant de fois que nécessaire.
  • Le filtrage IP s'applique déjà à la liste elle-même : un workspace dont l'allowlist IPv4 rejette votre adresse est retiré de la réponse de GET /api/v1/workspaces, sans erreur. Une liste plus courte qu'attendu peut donc signaler un problème d'adresse IP, pas un retrait d'accès.
  • Le rattachement d'un workspace à votre client OAuth est effectué par un administrateur Scribee. Un nouveau workspace apparaît dans la liste dès que ce rattachement est fait, sans action de votre côté.

Erreurs et cas limites​

401 Unauthorized​

Token absent, expiré, révoqué ou invalide. Le corps de la réponse est vide ; l'en-tête WWW-Authenticate précise la cause. Demandez un nouveau token sur /oauth/token (Authentification) - les tokens expirent, votre intégration doit savoir en redemander un.

403 Forbidden : accès au workspace​

Sur un endpoint préfixé par {workspace_id}, si votre client OAuth n'est pas rattaché à ce workspace :

{
  "error": "forbidden",
  "message": "L'application n'a pas accès à cet espace de travail"
}

Vérifiez le workspace_id contre la liste de l'étape 2. S'il est correct, demandez le rattachement à votre contact Scribee.

403 Forbidden : adresse IP refusée​

Si l'allowlist IPv4 du workspace est configurée et rejette l'adresse source de la requête :

{
  "error": "forbidden",
  "message": "Cette adresse IP n'est pas autorisée pour cet espace de travail"
}

Demandez à votre contact Scribee d'ajouter l'adresse IPv4 sortante de vos serveurs à l'allowlist du workspace. Une allowlist vide autorise toutes les adresses.

L'allowlist ne connaît que l'IPv4 : dès qu'elle contient au moins une entrée, une requête arrivant depuis une adresse IPv6 est refusée et aucune entrée ne peut l'autoriser. Si vos serveurs sortent en dual-stack, forcez l'IPv4 vers app.scribee.tech avant de demander une allowlist.

400 Bad Request : page au-delà de la dernière​

Sur GET /api/v1/workspaces, demander une page au-delà de la dernière page d'une collection non vide retourne :

{
  "error": "bad_request",
  "message": "Le numéro de page dépasse le nombre de pages disponibles"
}

Repartez de page=1 ou bornez vos requêtes avec meta.total_pages. Ce message ne couvre qu'une page trop grande. Une valeur de page invalide - page=0, une valeur négative, vide, non numérique, ou envoyée sous forme de tableau (page[]=1) - retourne le même statut 400 et la même clé error, avec un message distinct : "Le numéro de page doit être un entier supérieur ou égal à 1". Envoyez toujours un page entier supérieur ou égal à 1.

429 Too Many Requests : limite du health check​

Au-delà de 60 requêtes par minute et par adresse IP sur /api/v1/health, la réponse est un statut 429 avec un en-tête Retry-After. Espacez vos appels ; la limite se réinitialise à la minute suivante.

Pages liées​