Démarrage rapide

Ce parcours mène d'une application déclarée à un premier appel authentifié. L'API publique est en ligne en production depuis le 2026-11-05 (voir Versions et changelog) ; la sandbox, construite, n'est pas encore lancée : vos premiers appels se font donc sur les données réelles de l'entreprise qui a autorisé votre application.

1. Déclarer l'application

Un administrateur de l'entreprise (rôle ERP_OWNER ou ERP_ADMIN) ouvre dans l'application Tauraco la section Données et intégrations › Applications connectées (https://app.tauraco.io/app/integrations/apps), crée une application de type « partenaire », choisit ses scopes puis l'autorise pour son entreprise.

• L'identifiant public a la forme tc_live_ suivi de 24 caractères.
• Le secret (tcs_…) n'est affiché qu'une fois, à la création ou à la rotation. Rangez-le dans un coffre de secrets ; Tauraco n'en garde qu'une empreinte et ne peut pas le réafficher.
• Une application tierce déjà déclarée par un éditeur s'ajoute par son identifiant public : l'administrateur de votre entreprise l'autorise, il ne reçoit pas son secret.

2. Obtenir un jeton

Le flux client_credentials sert les échanges de serveur à serveur. Le jeton dure 10 minutes ; il n'y a pas de jeton de rafraîchissement pour ce flux : redemandez-en un.

#!/usr/bin/env sh
# Obtenir un jeton d'accès client_credentials (10 minutes).
# Get a client_credentials access token (10 minutes).
# Variables : TAURACO_CLIENT_ID (tc_live_…), TAURACO_CLIENT_SECRET (tcs_…), TAURACO_TENANT (facultatif).
# Le secret passe par l'entrée standard (--config -), jamais sur la ligne de commande :
# les arguments d'un processus sont lisibles par les autres comptes de la machine (ps).
set -eu
: "${TAURACO_CLIENT_ID:?identifiant du client requis}" "${TAURACO_CLIENT_SECRET:?secret du client requis}"
printf 'user = "%s:%s"\n' "${TAURACO_CLIENT_ID}" "${TAURACO_CLIENT_SECRET}" |
curl -sS --config - -X POST "https://api.tauraco.io/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=invoices:read customers:read" \
  --data-urlencode "resource=https://api.tauraco.io/public/v1" \
  ${TAURACO_TENANT:+--data-urlencode "tenant=${TAURACO_TENANT}"}
# Réponse : {"access_token":"…","token_type":"Bearer","expires_in":600,"scope":"customers:read invoices:read"}

Le paramètre resource (RFC 8707) désigne l'API visée ; tenant n'est nécessaire que si plusieurs entreprises ont autorisé la même application.

3. Premier appel

curl -sS "https://api.tauraco.io/public/v1/companies/me" \
  -H "Authorization: Bearer ${TAURACO_TOKEN}" -H "Accept: application/json"

Chaque réponse porte X-Request-Id (à citer au support), Tauraco-Version, les en-têtes de débit RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset et le quota du jour X-Quota-Limit, X-Quota-Remaining.

4. Lire une liste page par page

Les listes sont paginées par curseur opaque : limit (200 au plus), puis cursor repris de next_cursor tant que has_more vaut true.

#!/usr/bin/env sh
# Lire toutes les factures payées, page par page (curseur opaque). Nécessite jq.
# Read every paid invoice, page by page (opaque cursor). Requires jq.
set -eu
: "${TAURACO_TOKEN:?jeton requis (voir obtenir_jeton.sh)}"
BASE="https://api.tauraco.io/public/v1"
CURSOR=""
while : ; do
  PAGE=$(curl -sS -G "${BASE}/invoices" \
    -H "Authorization: Bearer ${TAURACO_TOKEN}" -H "Accept: application/json" \
    --data-urlencode "status=PAID" --data-urlencode "limit=100" \
    ${CURSOR:+--data-urlencode "cursor=${CURSOR}"})
  echo "${PAGE}" | jq -r '.data[] | [.number, .customer_name, .total, .currency] | @tsv'
  [ "$(echo "${PAGE}" | jq -r '.has_more')" = "true" ] || break
  CURSOR=$(echo "${PAGE}" | jq -r '.next_cursor')
done

Le jeu invoices expose notamment id, number, customer_id, customer_name, issue_date, due_date, currency, subtotal, tax_total, total, amount_paid et status.

5. Écrire sans doublon

Tout POST exige Idempotency-Key. Rejouer la même clé avec le même corps renvoie la réponse d'origine (Idempotent-Replayed: true) ; un corps différent est refusé (idempotency_key_reused) ; un appel concurrent reçoit idempotency_in_progress.

#!/usr/bin/env sh
# Créer un client : tout POST exige un en-tête Idempotency-Key (≤ 255 caractères).
# Create a customer: every POST requires an Idempotency-Key header (≤ 255 characters).
# Rejouer la même requête avec la même clé renvoie la réponse d'origine (Idempotent-Replayed: true) ;
# la même clé avec un corps différent est refusée (422 idempotency_key_reused).
set -eu
: "${TAURACO_TOKEN:?jeton requis (scope customers:write)}"
KEY="${IDEMPOTENCY_KEY:-$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)}"
curl -sS -X POST "https://api.tauraco.io/public/v1/customers" \
  -H "Authorization: Bearer ${TAURACO_TOKEN}" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "Idempotency-Key: ${KEY}" \
  -d '{"name":"Société Exemple SARL","country":"CI","currency":"XOF"}'

6. Recevoir les événements

Déclarez un endpoint HTTPS dans Données et intégrations › Webhooks, ou par l'API (POST /webhooks, scope webhooks:manage), notez son secret whsec_… (affiché une fois) et vérifiez chaque livraison comme décrit dans le guide des webhooks.

Et ensuite

• Les règles d'accès détaillées : Authentification.
• Toutes les opérations : Référence API REST.
• Les codes d'erreur : Gestion des erreurs.