Developers

Quick start

This walkthrough takes you from a declared application to a first authenticated call. The public API is online in production since 2026-11-05 (see Versions and changelog); the sandbox, built, is not launched yet: your first calls therefore run on the real data of the company that authorised your application.

1. Declare the application

A company administrator (role ERP_OWNER or ERP_ADMIN) opens Data & integrations › Connected apps in the Tauraco application (https://app.tauraco.io/app/integrations/apps), creates a "partner" application, picks its scopes, then authorises it for the company.

The public identifier looks like tc_live_ followed by 24 characters.
The secret (tcs_…) is shown only once, at creation or rotation. Keep it in a secrets vault; Tauraco only stores a hash and cannot show it again.
A third-party application already declared by a vendor is added by its public identifier: your company's administrator authorises it and never receives its secret.

2. Get a token

The client_credentials flow serves server-to-server exchanges. The token lasts 10 minutes; there is no refresh token for this flow: request a new one.

curl/obtenir_jeton.shDownload the file

#!/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"}

The resource parameter (RFC 8707) names the target API; tenant is only needed when several companies have authorised the same application.

3. First call

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

Every response carries X-Request-Id (quote it to support), Tauraco-Version, the rate headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and the daily quota X-Quota-Limit, X-Quota-Remaining.

4. Read a list page by page

Lists use an opaque cursor: limit (200 at most), then cursor taken from next_cursor while has_more is true.

curl/lister_factures.shDownload the file

#!/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

The invoices dataset exposes, among others, id, number, customer_id, customer_name, issue_date, due_date, currency, subtotal, tax_total, total, amount_paid and status.

5. Write without duplicates

Every POST requires Idempotency-Key. Replaying the same key with the same body returns the original response (Idempotent-Replayed: true); a different body is refused (idempotency_key_reused); a concurrent call gets idempotency_in_progress.

curl/creer_client.shDownload the file

#!/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. Receive events

Declare an HTTPS endpoint in Data & integrations › Webhooks, or through the API (POST /webhooks, scope webhooks:manage), note its whsec_… secret (shown once) and verify every delivery as described in the webhooks guide.

Detailed access rules: Authentication.
Every operation: REST API reference.
Error codes: Error handling.