Ingérer des événements

POST /v1/events reçoit un lot d’événements. C’est l’endpoint qu’utilisent les SDK. Vous ne l’appelez directement que si vous envoyez des événements depuis un serveur ou une plateforme sans SDK.

Requête

POST https://api.bissa.tech/v1/events
Content-Type: application/json
X-API-Key: <clé d'ingestion>

string

requis

Clé d’ingestion de l’environnement visé. Voir Authentification.

Event[]

requis

Entre 1 et 100 événements. Le format de chaque événement est décrit dans Schéma d’événement.

Champs d’un événement

Champ	Obligatoire	Règle
`eventId`	✅	UUID v4 généré par le client, identique à chaque nouvel essai
`eventName`	✅	1 à 256 caractères
`source`	✅	1 à 64 caractères, par exemple `sdk-react` ou `server`
`anonymousId`	✅	1 à 256 caractères
`sessionId`	✅	1 à 256 caractères
`timestamp`	✅	Date ISO 8601
`userId`		256 caractères maximum
`properties`		Objet JSON, 32 Ko maximum une fois sérialisé

Un timestamp de plus de 7 jours dans le passé, ou de plus de 10 minutes dans le futur, est remplacé par l’heure de réception.

Exemple

curl -i -X POST https://api.bissa.tech/v1/events \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: jch_pr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -d '{
    "events": [
      {
        "eventId": "93599a8a-6973-4dcf-9741-fedb3b34d4ac",
        "eventName": "signup_completed",
        "source": "server",
        "anonymousId": "7bac4caf-c18d-406e-830d-9187b03c188f",
        "sessionId": "9e1d9f79-9e06-42d8-a00d-a4f492cb2fde",
        "timestamp": "2026-07-28T08:45:41.374Z",
        "properties": { "schemaVersion": 1, "custom": { "plan": "pro" } }
      }
    ]
  }'

Réponse

Un lot traité renvoie 202 Accepted :

{
  "accepted": 1,
  "eventIds": ["93599a8a-6973-4dcf-9741-fedb3b34d4ac"]
}

number

Nombre d’événements nouvellement enregistrés. Les doublons ne sont pas comptés.

string[]

Tous les eventId du lot considérés comme traités, doublons compris. Le client peut les retirer de sa file d’attente.

Doublons et nouveaux essais

Renvoyer un lot déjà reçu ne crée pas de doublon : un eventId déjà connu est ignoré, et il est quand même renvoyé dans eventIds. Après une erreur réseau, renvoyez donc le même lot avec les mêmes eventId.

Quota mensuel

Chaque plan inclut un nombre d’événements par mois. Quand le quota est atteint, l’API répond toujours 202, mais avec accepted: 0 : les événements ne sont pas enregistrés. Suivez votre consommation dans Paramètres → Usage. Une alerte est envoyée à 90 % du quota.

Codes de réponse

Code	Signification	Que faire
`202`	Lot traité	Retirer les `eventIds` de la file
`400`	Événement illisible (par exemple `timestamp` invalide)	Corriger le lot ; ne pas le renvoyer tel quel
`401`	Clé absente ou invalide	Corriger la clé ; garder les événements
`403`	Clé sans droit d’écriture	Utiliser une clé d’ingestion
`422`	Lot invalide : plus de 100 événements, champ manquant ou trop long, `properties` au-delà de 32 Ko	Corriger le lot
`429`	Limite de débit (120/min par clé, 180/min par IP)	Réessayer après `Retry-After` secondes
`5xx`	Erreur serveur	Réessayer avec un délai croissant

Les erreurs sont renvoyées sous la forme { "detail": ... }. Chaque réponse contient un en-tête X-Request-Id à communiquer au support si besoin.

CORS

L’endpoint accepte les requêtes de n’importe quelle origine navigateur. Aucun proxy n’est nécessaire, y compris en développement local.

​Requête

​Champs d’un événement

​Exemple

​Réponse

​Doublons et nouveaux essais

​Quota mensuel

​Codes de réponse

​CORS