Déclarer une opération collective

POST

/v1/entreprises/{entreprise}/operations-collectives

const url = 'https://passerelle.teneur.exemple/v1/entreprises/example/operations-collectives';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    'Correlation-Id': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"dispositif":"example","nature":"example","exercice":1,"periode":{"debut":"2026-04-15","fin":"2026-04-15"},"montant_global_ct":1,"date_versement_souhaitee":"2026-04-15","repartition":[{"matricule":"example","montant_ct":1}],"reference_du_teneur":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://passerelle.teneur.exemple/v1/entreprises/example/operations-collectives \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Correlation-Id: example' \
  --header 'Idempotency-Key: example' \
  --data '{ "dispositif": "example", "nature": "example", "exercice": 1, "periode": { "debut": "2026-04-15", "fin": "2026-04-15" }, "montant_global_ct": 1, "date_versement_souhaitee": "2026-04-15", "repartition": [ { "matricule": "example", "montant_ct": 1 } ], "reference_du_teneur": "example" }'

La déclaration est prise en compte, elle n’est pas exécutée : la réponse est un accusé portant la référence de l’opération collective née, que Location désigne et que le portail suit.

Autorisations

jetonPartenaire

Paramètres

Paramètres (path)

entreprise

required

string

>= 1 characters

L’identifiant publié de l’entreprise chez ce teneur de compte. Il désigne la ressource ; un identifiant d’entreprise dans une URL ne vaut jamais autorisation.

Paramètres (header)

Idempotency-Key

required

string

>= 8 characters <= 128 characters

La clé d’idempotence de l’écriture, choisie par l’appelant. Un serveur tiers réessaie : deux envois de la même clé produisent un effet. Le rejeu à charge identique rend la réponse d’origine ; le rejeu à charge différente est refusé.

Correlation-Id

required

string

>= 1 characters <= 128 characters

L’identifiant que le teneur de compte donne à l’échange dans son journal. Obligatoire : notre trace dit qui a lu quoi, jamais pour qui, et ce champ est la seule jointure entre les deux journaux. Il est restitué dans la réponse.

Corps de la requête^required

application/json

object

dispositif

required

string

nature

required

La nature déclarée, dans la nomenclature publiée par les Opérations.

string

exercice

required

L’exercice au titre duquel l’opération est déclarée.

integer

periode

object

debut

required

string format: date

fin

Absente pour une période encore ouverte.

string format: date

montant_global_ct

required

Le montant global déclaré, en centimes. La somme de la répartition lui est confrontée : un écart est refusé, jamais absorbé.

integer

>= 1

date_versement_souhaitee

string format: date

repartition

required

La répartition individuelle calculée par l’entreprise, par matricule.

Array<object>

>= 1 items

object

matricule

required

string

montant_ct

required

integer

reference_du_teneur

string

Example^generated

{
  "dispositif": "example",
  "nature": "example",
  "exercice": 1,
  "periode": {
    "debut": "2026-04-15",
    "fin": "2026-04-15"
  },
  "montant_global_ct": 1,
  "date_versement_souhaitee": "2026-04-15",
  "repartition": [
    {
      "matricule": "example",
      "montant_ct": 1
    }
  ],
  "reference_du_teneur": "example"
}

Réponses

202

La déclaration est prise en compte. Un rejeu de la même clé rend cette même réponse, avec la même référence.

application/json

object

reference

required

La référence de ce qui est né — celle que Location désigne.

string

etat

required

string

recu_le

required

string format: date-time

reference_du_teneur

string

Example^generated

{
  "reference": "example",
  "etat": "example",
  "recu_le": "2026-04-15T12:00:00Z",
  "reference_du_teneur": "example"
}

Headers

Location

string

La ressource d’opération collective où suivre l’exécution.

Correlation-Id

string

>= 1 characters <= 128 characters

L’identifiant de corrélation reçu, restitué tel quel — la jointure entre le journal du teneur et le nôtre.

400

400 — la demande est mal formée ; le motif nomme le champ en cause.

application/json

object

code

required

Le code stable sur lequel un portail se branche — le motif, lui, est écrit pour être lu par une personne et peut changer sans rupture.

string

Allowed values: DEMANDE_MAL_FORMEE CHAMP_INVALIDE NON_AUTHENTIFIE HORS_PERIMETRE_SOUSCRIT RESSOURCE_INCONNUE REJEU_DIVERGENT ECRITURE_REFUSEE AGREGAT_RETENU

motif

required

Le motif, qui nomme le champ ou l’identifiant en cause.

string

champ

Le champ en cause, quand l’erreur en désigne un.

string

correlation

L’identifiant de corrélation de l’appel — le même que l’en-tête restitué.

string

Example

{
  "code": "DEMANDE_MAL_FORMEE"
}

401

401 — aucune identité présentée, ou jeton invalide : signature, émetteur, dates, tenant, ou audience obtenue pour une autre surface. La réponse porte WWW-Authenticate: Bearer error="invalid_token".

application/json

object

code

required

Le code stable sur lequel un portail se branche — le motif, lui, est écrit pour être lu par une personne et peut changer sans rupture.

string

Allowed values: DEMANDE_MAL_FORMEE CHAMP_INVALIDE NON_AUTHENTIFIE HORS_PERIMETRE_SOUSCRIT RESSOURCE_INCONNUE REJEU_DIVERGENT ECRITURE_REFUSEE AGREGAT_RETENU

motif

required

Le motif, qui nomme le champ ou l’identifiant en cause.

string

champ

Le champ en cause, quand l’erreur en désigne un.

string

correlation

L’identifiant de corrélation de l’appel — le même que l’en-tête restitué.

string

Example

{
  "code": "DEMANDE_MAL_FORMEE"
}

Headers

WWW-Authenticate

string

Le défi d’authentification, au format des jetons porteurs.

403

403 — le cas d’usage n’est pas dans le périmètre souscrit de ce client. La réponse ne dit jamais si la ressource existe.

application/json

object

code

required

Le code stable sur lequel un portail se branche — le motif, lui, est écrit pour être lu par une personne et peut changer sans rupture.

string

Allowed values: DEMANDE_MAL_FORMEE CHAMP_INVALIDE NON_AUTHENTIFIE HORS_PERIMETRE_SOUSCRIT RESSOURCE_INCONNUE REJEU_DIVERGENT ECRITURE_REFUSEE AGREGAT_RETENU

motif

required

Le motif, qui nomme le champ ou l’identifiant en cause.

string

champ

Le champ en cause, quand l’erreur en désigne un.

string

correlation

L’identifiant de corrélation de l’appel — le même que l’en-tête restitué.

string

Example

{
  "code": "DEMANDE_MAL_FORMEE"
}

404

404 — inconnu de ce teneur de compte. Une entreprise, un dispositif ou une opération relevant d’un autre teneur est inexistant, jamais interdit : la muraille de Chine ne laisse pas fuir une existence.

application/json

object

code

required

Le code stable sur lequel un portail se branche — le motif, lui, est écrit pour être lu par une personne et peut changer sans rupture.

string

Allowed values: DEMANDE_MAL_FORMEE CHAMP_INVALIDE NON_AUTHENTIFIE HORS_PERIMETRE_SOUSCRIT RESSOURCE_INCONNUE REJEU_DIVERGENT ECRITURE_REFUSEE AGREGAT_RETENU

motif

required

Le motif, qui nomme le champ ou l’identifiant en cause.

string

champ

Le champ en cause, quand l’erreur en désigne un.

string

correlation

L’identifiant de corrélation de l’appel — le même que l’en-tête restitué.

string

Example

{
  "code": "DEMANDE_MAL_FORMEE"
}

409

409 — cette clé d’idempotence a déjà servi, avec une charge utile différente. Rien n’a été engagé.

application/json

object

code

required

Le code stable sur lequel un portail se branche — le motif, lui, est écrit pour être lu par une personne et peut changer sans rupture.

string

Allowed values: DEMANDE_MAL_FORMEE CHAMP_INVALIDE NON_AUTHENTIFIE HORS_PERIMETRE_SOUSCRIT RESSOURCE_INCONNUE REJEU_DIVERGENT ECRITURE_REFUSEE AGREGAT_RETENU

motif

required

Le motif, qui nomme le champ ou l’identifiant en cause.

string

champ

Le champ en cause, quand l’erreur en désigne un.

string

correlation

L’identifiant de corrélation de l’appel — le même que l’en-tête restitué.

string

Example

{
  "code": "DEMANDE_MAL_FORMEE"
}

422

422 — la demande est bien formée mais l’écriture est refusée par le métier : dispositif clos à la période déclarée, exercice déjà arrêté, montant global incohérent avec la répartition transmise.

application/json

object

code

required

Le code stable sur lequel un portail se branche — le motif, lui, est écrit pour être lu par une personne et peut changer sans rupture.

string

Allowed values: DEMANDE_MAL_FORMEE CHAMP_INVALIDE NON_AUTHENTIFIE HORS_PERIMETRE_SOUSCRIT RESSOURCE_INCONNUE REJEU_DIVERGENT ECRITURE_REFUSEE AGREGAT_RETENU

motif

required

Le motif, qui nomme le champ ou l’identifiant en cause.

string

champ

Le champ en cause, quand l’erreur en désigne un.

string

correlation

L’identifiant de corrélation de l’appel — le même que l’en-tête restitué.

string

Example

{
  "code": "DEMANDE_MAL_FORMEE"
}

Déclarer une opération collective

Autorisations

Paramètres

Paramètres (path)

Paramètres (header)

Corps de la requêterequired

Examplegenerated

Réponses

202

Examplegenerated

Headers

400

Example

401

Example

Headers

403

Example

404

Example

409

Example

422

Example

Corps de la requête^required

Example^generated

Example^generated