Conventions de l’API
Format, pagination, erreurs, idempotence, limites de débit et versions.
Toutes les ressources de l'API suivent les mêmes règles : apprenez-les une fois, elles valent pour chaque endpoint.
URL de base et format
| URL de base |
https://strikespace.net/api/platform/v1
|
| Transport |
HTTPS uniquement. Corps de requête et de réponse en JSON UTF-8 (Content-Type: application/json).
|
| Nommage |
Champs en snake_case. Chaque objet porte "object": "<type>" et un id (UUID).
|
| Dates |
ISO 8601 en UTC, par exemple 2026-10-16T10:05:51.000Z. En entrée, toute date ISO 8601 avec fuseau est acceptée.
|
| Montants |
Entiers dans l'unité de la devise (FCFA : 15000 = 15 000 FCFA), avec currency.
|
| Valeurs absentes |
Les champs sans valeur sont présents avec null, jamais omis.
|
| Cache |
Les réponses portent Cache-Control: no-store.
|
Pagination
Les endpoints de liste retournent une enveloppe commune, triée du plus récent au plus ancien :
{
"object": "list",
"data": [
{
"object": "lead",
"id": "8f14e45f-ceea-4e7a-9a3b-2c1d5e6f7a80",
"first_name": "Awa"
}
],
"has_more": true,
"next_cursor": "MjAyNi0xMC0xNFQwOToxMjozMS4wMDBafDhmMTRlNDVm"
}
limit: de 1 à 100 éléments par page, 25 par défaut.cursor: passez la valeurnext_cursorreçue pour obtenir la page suivante. Le curseur est opaque : ne le construisez pas et ne l'interprétez pas.- La pagination par curseur est stable : un élément créé pendant que vous parcourez la liste ne décale pas les pages suivantes.
- Les filtres doivent être identiques d'une page à l'autre.
// Parcourt toutes les pages de /leads
async function* allLeads() {
let cursor = null
do {
const url = new URL('https://strikespace.net/api/platform/v1/leads')
url.searchParams.set('limit', '100')
if (cursor) url.searchParams.set('cursor', cursor)
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.STRIKE_API_KEY}` },
})
const page = await response.json()
if (!response.ok) throw new Error(page.error.message)
yield* page.data
cursor = page.has_more ? page.next_cursor : null
} while (cursor)
}
for await (const lead of allLeads()) console.log(lead.id)
import os
import requests
def all_leads():
params = {"limit": 100}
headers = {"Authorization": f"Bearer {os.environ['STRIKE_API_KEY']}"}
while True:
response = requests.get("https://strikespace.net/api/platform/v1/leads", headers=headers, params=params, timeout=10)
response.raise_for_status()
page = response.json()
yield from page["data"]
if not page["has_more"]:
break
params["cursor"] = page["next_cursor"]
for lead in all_leads():
print(lead["id"])
Erreurs
Toute erreur renvoie un code HTTP adapté et le même format JSON :
{
"error": {
"type": "permission_error",
"message": "Cette clé n’a pas la permission « Créer, modifier et supprimer des leads » (scope leads:write).",
"code": "insufficient_scope",
"request_id": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
}
}
| HTTP |
type
|
Signification et conduite à tenir |
|---|---|---|
| 400 / 422 |
invalid_request
|
Requête mal formée ou champ invalide ; param désigne le champ. Corrigez avant de renvoyer.
|
| 401 |
authentication_error
|
Clé ou jeton absent, invalide, expiré ou révoqué. L'en-tête WWW-Authenticate indique les métadonnées OAuth.
|
| 403 |
permission_error
|
Accès refusé. code précise : insufficient_scope, plan_required, ip_not_allowed, ou une règle métier (quota, canal non inclus).
|
| 404 |
not_found
|
Ressource inexistante ou appartenant à un autre compte. |
| 409 |
conflict
|
Conflit d'état : version obsolète, doublon, Idempotency-Key réutilisée avec un autre corps, limite de l'offre atteinte.
|
| 429 |
rate_limit
|
Trop de requêtes (code: "rate_limited"). Attendez Retry-After secondes.
|
| 500 |
internal
|
Erreur de notre côté. Réessayez avec un délai croissant ; si elle persiste, contactez-nous avec le request_id.
|
{
"error": {
"type": "invalid_request",
"message": "Le champ email doit être une adresse email valide.",
"param": "email",
"request_id": "0b7e2c4a-1d3f-4e5a-9b6c-7d8e9f0a1b2c"
}
}
Les messages (message) sont rédigés en français pour être affichés ou journalisés ; basez votre logique sur
type et code, qui sont stables.
Identifiant de requête
Chaque réponse, succès ou erreur, porte un en-tête X-Request-Id (repris dans
error.request_id). Journalisez-le : il permet à notre support de retrouver votre appel dans nos journaux, et
il apparaît dans votre Journal développeurs.
Idempotence
Les requêtes POST acceptent un en-tête Idempotency-Key (255 caractères maximum, par exemple un
UUID v4 ou votre identifiant métier). Pendant 24 heures :
- la même clé avec le même corps rejoue la réponse enregistrée, sans refaire l'opération, avec l'en-tête
Idempotent-Replayed: true; - la même clé avec un corps différent est refusée :
409,code: "idempotency_key_reused"; - la même clé pendant que la première requête est encore en cours :
409,code: "idempotency_request_in_progress"(réessayez un instant plus tard) ; - une réponse d'erreur n'est pas mémorisée : après correction, un nouvel envoi avec la même clé est exécuté normalement.
# Le même appel peut être rejoué sans risque pendant 24 h
curl -X POST 'https://strikespace.net/api/platform/v1/leads' \
-H "Authorization: Bearer $STRIKE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: crm-contact-48213" \
-d '{ "first_name": "Awa", "email": "awa@exemple.com" }'
# Second envoi identique : réponse stockée, en-tête « Idempotent-Replayed: true »
Utilisez-la systématiquement pour les créations (leads, événements, publications, inscriptions) : en cas de coupure
réseau ou de délai dépassé, vous pouvez renvoyer sans risque de doublon. PATCH et DELETE sont
naturellement idempotents.
Limites de débit
Les limites protègent la plateforme et dépendent de votre offre. La limite par minute s'applique à chaque clé ou agent connecté ; la limite journalière à l'ensemble du compte.
| Limite | Pro | Enterprise |
|---|---|---|
| Requêtes par minute, par clé ou agent | 60 | 300 |
| Requêtes par jour, par compte | 50 000 | 500 000 |
| Clés API actives | 10 | 50 |
| Endpoints de webhooks | 5 | 25 |
| Agents IA connectés | 20 | 100 |
Chaque réponse indique votre consommation de la minute en cours :
HTTP/1.1 200 OK
X-Request-Id: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 42
HTTP/1.1 429 Too Many Requests
Retry-After: 18
RateLimit-Remaining: 0
RateLimit-Reset: 18
RateLimit-Limit: requêtes autorisées par minute ;RateLimit-Remaining: requêtes restantes ;RateLimit-Reset: secondes avant la remise à zéro ;- en cas de dépassement :
429etRetry-After(secondes).
Renvoyez uniquement les 429 et les 5xx, avec un délai croissant et un peu d'aléa :
// Renvoi avec délai croissant sur 429 et 5xx uniquement
async function strikeFetch(url, options = {}, attempt = 0) {
const response = await fetch(url, options)
const retryable = response.status === 429 || response.status >= 500
if (!retryable || attempt >= 4) return response
const retryAfter = Number(response.headers.get('retry-after'))
const delay = retryAfter > 0 ? retryAfter * 1000 : Math.min(30_000, 500 * 2 ** attempt)
await new Promise((resolve) => setTimeout(resolve, delay + Math.random() * 250))
return strikeFetch(url, options, attempt + 1)
}
import random
import time
import requests
def strike_request(method, url, attempt=0, **kwargs):
response = requests.request(method, url, timeout=10, **kwargs)
retryable = response.status_code == 429 or response.status_code >= 500
if not retryable or attempt >= 4:
return response
retry_after = response.headers.get("Retry-After")
delay = int(retry_after) if retry_after and retry_after.isdigit() else min(30, 0.5 * 2 ** attempt)
time.sleep(delay + random.random() / 4)
return strike_request(method, url, attempt + 1, **kwargs)
Versions
La version actuelle de l'API est 2026-10-01. Elle figure dans le chemin (/v1) et dans le
champ api_version de chaque événement webhook.
- Changements compatibles, sans préavis : nouveaux endpoints, nouveaux champs dans les réponses, nouveaux paramètres facultatifs, nouveaux types d'événements, nouvelles valeurs de
code. Votre code doit ignorer les champs inconnus. - Changements incompatibles (suppression ou renommage d'un champ, changement de type) : publiés dans une nouvelle version datée, annoncés à l'avance dans le changelog et par email ; l'ancienne version reste disponible pendant une période de transition.
Une question sur l'intégration ? Écrivez à
contact@strike.app
en indiquant l'endpoint, l'heure et le request_id de la réponse.