Poser une signature visuelle

Une signature se scelle dans le document, avec ses certificats ; l'encart la montre à l'œil : le nom du signataire, la date et l'heure, le sceau. Il se pose par un emplacement de signature :

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

{
  "TransactionMemberId": "dddddddd-0000-4000-8000-000000000004",
  "TransactionFileId": "eeeeeeee-0000-4000-8000-000000000005",
  "Pages": "-1",
  "Coordinates": "320,90,180,100"
}

curl -X POST "https://staging-api.docage.com/TransactionFields" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "TransactionMemberId": "dddddddd-0000-4000-8000-000000000004",
    "TransactionFileId": "eeeeeeee-0000-4000-8000-000000000005",
    "Pages": "-1",
    "Coordinates": "320,90,180,100"
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/TransactionFields");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "TransactionMemberId": "dddddddd-0000-4000-8000-000000000004",
      "TransactionFileId": "eeeeeeee-0000-4000-8000-000000000005",
      "Pages": "-1",
      "Coordinates": "320,90,180,100"
    }
    """, 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/TransactionFields", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "TransactionMemberId": "dddddddd-0000-4000-8000-000000000004",
    "TransactionFileId": "eeeeeeee-0000-4000-8000-000000000005",
    "Pages": "-1",
    "Coordinates": "320,90,180,100"
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

La réponse est l'identifiant de l'emplacement. Les routes répondent aussi sous leur ancien nom, TransactionMemberSignatureLocations, que la référence ne montre plus : préférez TransactionFields.

Les coordonnées

Coordinates vaut x,y,largeur,hauteur, en points (1/72 de pouce ; une page A4 mesure 595 × 842), depuis le coin inférieur gauche de la page. Ici : 320 points du bord gauche, 90 du bas, 180 de large et 100 de haut.

Les pages

Pages dit où l'encart se répète ; plusieurs écritures se séparent par ; (1;4;7-10;-1) :

Sans Pages, l'encart se pose sur la page 1. Voir Plusieurs signatures pour un participant pour le champ dans le texte.

Les refus

• 404 « Le TransactionMember n'existe pas. » — le participant est introuvable, ou vous ne le voyez pas ; « Le TransactionFile n'existe pas » — le document est introuvable, ou n'est pas du parcours du participant.
• 403 « Action non autorisée » : vous voyez le participant sans avoir le droit de le modifier.
• 409 : le parcours est déjà lancé.

Les pièges

• Plusieurs emplacements pour un même document dessinent chacun leur encart : une seule signature, montrée à chaque place. Pour répéter un encart à la même place sur plusieurs pages, un seul emplacement et plusieurs Pages suffisent.
• Les coordonnées ne sont pas contrôlées : une valeur illisible (une virgule décimale, une valeur manquante) laisse la signature sans encart, sans erreur. Relisez le document avant l'envoi : GET https://staging-api.docage.com/TransactionFiles/Download/{id}?format=pdf.
• Sans emplacement, la signature est valide, mais aucun encart ne la montre.
• L'ancienne route SignatureLocations n'existe plus ; Pages à 0 n'ajoute plus de page — écrivez EXTRA — et ne se compte plus depuis la fin que -1.
• Pour déplacer un emplacement : PUT https://staging-api.docage.com/TransactionFields/{id} ; pour le retirer : DELETE https://staging-api.docage.com/TransactionFields/{id}, ou DELETE https://staging-api.docage.com/TransactionFields/BatchDelete avec la liste des identifiants. Un emplacement retiré l'est définitivement, sans passer par la corbeille.
• Cette route ne pose que des signatures : une zone de saisie (texte, date, case…) se déclare dans les champs du parcours (Fields).