Écrire dans un tableur et lire ses calculs

Créer un tableur, écrire ses cellules, ses lignes et ses formules, le recalculer, puis lire ses résultats.

4 min de lecture Mise à jour le 11 novembre 2026

Un tableur est un document de Docage de type « Feuille de calcul » (Type 1) : un classeur, avec ses feuilles, ses cellules et ses formules. Il se crée, se liste et se supprime comme tout document (https://staging-api.docage.com/Documents) ; son contenu se lit et s'écrit cellule par cellule, par les routes https://staging-api.docage.com/Spreadsheets.

1Créer le tableur

POST https://staging-api.docage.com/Documents
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{ "Name": "Budget 2027", "Type": 1 }

curl -X POST "https://staging-api.docage.com/Documents" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{"Name": "Budget 2027", "Type": 1}'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Documents");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Name": "Budget 2027",
      "Type": 1
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Documents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"Name": "Budget 2027", "Type": 1})
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

La réponse est son identifiant. Il naît avec une feuille vide ; "IsTemplate": true en fait un modèle de tableur.

Retrouver vos tableurs : QUERY https://staging-api.docage.com/Documents, avec le filtre { "PropertyName": "Type", "Comparison": "=", "Value": 1 } — voir Lire des listes.
Copier un tableur, son contenu compris : POST https://staging-api.docage.com/Documents/Duplicate, avec la liste de ses identifiants ; la réponse associe à chacun l'identifiant de sa copie.

2Ses feuilles

GET https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Get, "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets", {
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

La réponse liste les feuilles dans leur ordre : leur nom (Name), leur rang à partir de 0 (Index), et la zone utilisée (RowCount, ColumnCount). Une feuille se désigne dans l'adresse par son nom, encodé s'il porte des espaces, ou par son rang : 0 est la première.

Ajouter une feuille : POST https://staging-api.docage.com/Spreadsheets/{id}/Sheets avec { "Name": "Dépenses", "Index": 1 }, tous deux facultatifs ; un nom déjà pris est refusé.
Supprimer une feuille : DELETE https://staging-api.docage.com/Spreadsheets/{id}/Sheets/{sheet}. Un tableur garde toujours au moins une feuille.

3Écrire

Une cellule se désigne par sa référence (A1, B3). Elle reçoit une valeur — un nombre, un booléen, un texte, ou null pour la vider — ou une formule :

PUT https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/A1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{ "Value": "Poste" }

curl -X PUT "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/A1" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{"Value": "Poste"}'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Put, "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/A1");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Value": "Poste"
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/A1", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"Value": "Poste"})
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

Une ligne entière s'ajoute après la dernière ligne utilisée, ses valeurs posées à partir de la colonne A :

POST https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Rows
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{ "Values": ["Loyer", 1200, "=B2*12"] }

curl -X POST "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Rows" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{"Values": ["Loyer", 1200, "=B2*12"]}'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Rows");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Values": [
        "Loyer",
        1200,
        "=B2*12"
      ]
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Rows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"Values": ["Loyer", 1200, "=B2*12"]})
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

La réponse est le numéro de la ligne créée, à partir de 1. Un texte qui commence par = est une formule.

Une formule s'écrit aussi dans une cellule, avec ou sans le = de tête :

PUT https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/C10
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{ "Formula": "SUM(C2:C9)" }

curl -X PUT "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/C10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{"Formula": "SUM(C2:C9)"}'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Put, "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/C10");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Formula": "SUM(C2:C9)"
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/C10", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"Formula": "SUM(C2:C9)"})
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

Quand Value et Formula sont donnés ensemble, la formule l'emporte.

Pour	Route
Insérer des lignes avant la ligne 5	`POST https://staging-api.docage.com/Spreadsheets/{id}/Sheets/{sheet}/Rows/5`, avec `{ "Count": 2, "Values": […] }`
Supprimer des lignes à partir de la ligne 5	`DELETE https://staging-api.docage.com/Spreadsheets/{id}/Sheets/{sheet}/Rows/5?count=2`
Ajouter des colonnes après la dernière utilisée	`POST https://staging-api.docage.com/Spreadsheets/{id}/Sheets/{sheet}/Columns`
Insérer des colonnes avant la colonne C	`POST https://staging-api.docage.com/Spreadsheets/{id}/Sheets/{sheet}/Columns/C`
Supprimer des colonnes à partir de la colonne C	`DELETE https://staging-api.docage.com/Spreadsheets/{id}/Sheets/{sheet}/Columns/C?count=1`

Count vaut 1 d'office ; Values ne remplit que la première ligne (ou colonne) créée, une colonne se remplissant à partir de la ligne 1. Une colonne se désigne par ses lettres (AB) ou par son numéro, à partir de 1.

4Recalculer, puis lire

Le tableur ne se recalcule pas à chaque écriture : une lecture rend les valeurs du dernier calcul. Après vos écritures, recalculez :

POST https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Calculate
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl -X POST "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Calculate" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Calculate");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Calculate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

Toutes ses feuilles sont recalculées. POST https://staging-api.docage.com/Spreadsheets/{id}/Sheets/{sheet}/Cells/{cell}/Calculate recalcule une seule cellule, et ce dont elle dépend, puis la rend.

GET https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/C10
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/C10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Get, "https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/C10");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Spreadsheets/bbbbbbbb-0000-4000-8000-000000000002/Sheets/0/Cells/C10", {
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

JSON

{ "Cell": "C10", "Row": 10, "Column": "C", "Value": 14400, "Formula": "=SUM(C2:C9)", "Text": "14400" }

Value est la valeur typée — pour une formule, son résultat ; Text est le texte tel que le tableur l'affiche, son format de nombre appliqué. GET https://staging-api.docage.com/Spreadsheets/{id}/Sheets/{sheet}/Rows/{row} lit une ligne, de la colonne A à la dernière utilisée ; GET https://staging-api.docage.com/Spreadsheets/{id}/Sheets/{sheet}/Columns/{column} lit une colonne, de la ligne 1 à la dernière utilisée.

Les refus

Code	Ce qu'il dit
`403`	Vous voyez le tableur, mais vous n'avez pas le droit de le modifier.
`404`	Le tableur est introuvable, ou vous ne le voyez pas : la même réponse pour les deux. Ou la feuille est introuvable : le message nomme la feuille qui manque.
`409`	Le tableur est le document d'un parcours lancé, ou une copie propre à un parcours : il ne se modifie plus par ces routes. Il se lit toujours.
`422`	Le document n'est pas un tableur, ou la demande est invalide : une référence de cellule, un numéro de ligne, un nombre inférieur à 1…

Un document que vous ne voyez pas répond 404 avant tout autre refus : même s'il n'est pas un tableur, la réponse ne le dit pas.

Les pièges

Recalculez avant de lire un résultat : sans Calculate, une formule peut rendre la valeur de son dernier calcul.
Chaque écriture enregistre le tableur et compte comme une modification de sa fiche : regroupez vos valeurs, une ligne par appel, plutôt qu'une cellule par appel.
Un tableur sert aussi dans un parcours, comme un document : les jetons {{…}} écrits dans ses cellules y sont remplacés par les données du parcours, puis ses formules recalculées. Voir Rédiger un document d'après son texte pour les jetons, et Obtenir un document rempli depuis un modèle pour le récupérer, en classeur (.xlsx) ou en PDF.
POST https://staging-api.docage.com/Documents/FromText n'écrit que des documents de texte, jamais un tableur.