Créer un lot de signature

POST/document/manyclé privéeprk_

Ce service vous permet de générer un lot de documents à partir d’un modèle Auco ou d’un fichier PDF. Une fois le processus terminé, vous recevrez chaque document avec son propre certificat de signature.

info

Avant d’intégrer cet endpoint, il peut être utile de consulter comment définir les positions de signature et les paramètres de validation d’identité au niveau du lot.

avertissement

Le tableau documents doit contenir au moins 2 éléments. Si vous n’avez besoin que d’un seul document, utilisez l’endpoint POST /document/upload.

Étapes pour créer un lot de documents à partir d’un modèle automatisé :

1. Consultez les modèles ou documents personnalisés disponibles.
2. Obtenez l’_id du document de base.
3. Consultez les variables requises du document sélectionné.
4. Construisez et envoyez la requête de création.

info

Si vous souhaitez procéder avec un PDF, il n’est pas nécessaire d’envoyer le fichier dans la requête initiale. À la fin, une URL signée sera renvoyée pour chaque document du lot.

Vous trouverez ci-dessous les paramètres requis pour ce service, accompagnés d’exemples et des réponses possibles du système.

---

Authentification

Incluez votre clé privée dans l'en-tête Authorization.

Authorization: prk_xxx...

---

Paramètres de création

Nom	Type	Description
email	String obligatoire	Adresse e-mail du créateur du processus.
package	String facultatif	Identifiant d’un lot précédemment placé en modification. L’envoyer écrase ce lot au lieu d’en créer un nouveau, en conservant son identifiant. Renvoyez la charge utile complète : tout ce que vous omettez est supprimé. En savoir plus
document	String conditionnel	ID du document personnalisé ou du modèle Auco. Requis uniquement si vous souhaitez utiliser un modèle.
name	String obligatoire	Nom du processus de signature du document. Requis si le processus inclut la signature de documents.
message	String facultatif	Message qui sera envoyé dans le corps de l’e-mail notifiant le document aux signataires ou aux approbateurs.
subject	String facultatif	Objet avec lequel l’e-mail de notification sera envoyé aux signataires ou aux approbateurs.
folder	String conditionnel	Si vous souhaitez enregistrer ce processus dans un dossier précis, indiquez ici son chemin. Le dossier doit exister et appartenir au créateur du processus.
remember	Number conditionnel	Active les rappels automatiques avec l’intervalle de temps (en heures) entre chaque notification. Doit être un multiple de 3.
expiredDate	Date facultatif	Date d’expiration du document. Elle doit être postérieure d’au moins 3 jours à la date de création du processus et est envoyée au format Date JSON.
camera	Boolean facultatif	Indique si la validation par photo est requise. Valeur par défaut : false.
otpCode	Boolean facultatif	Indique si la validation par code OTP est requise. Valeur par défaut : false.
options	Object facultatif	Précise les paramètres de validation d’identité. En savoir plus
notification	Boolean facultatif	Définit si Auco notifie les participants une fois le processus créé. Valeur par défaut : true. C’est la valeur par défaut pour chaque signataire ; chacun peut la remplacer avec signProfile[x].notification. Les signataires qu’Auco ne notifie pas reçoivent un id dans la réponse, regroupé par e-mail pour l’ensemble des documents, afin que l’intégrateur puisse les amener à signer de manière autonome.
custom	Object facultatif	Objet libre permettant d’envoyer des paramètres définis par l’intégrateur (par exemple, des identifiants internes ou des métadonnées). Auco le stocke tel quel et le transmet dans les notifications webhook et dans la réponse de GET /document, sans interpréter ni valider son contenu. S’applique à l’ensemble du lot.
data	Array conditionnel	Contient toutes les données requises par le modèle pour générer le document. Requis uniquement si vous utilisez un modèle.
data[x].key	String obligatoire	Nom du paramètre enregistré dans le modèle.
data[x].value	String obligatoire	Valeur attribuée au paramètre.
documents *	Array obligatoire	Liste d’objets, chacun représentant un document du lot.
documents[0].name	String obligatoire	Nom du document.
documents[0].readers	Array facultatif	Liste d’objets définissant les participants qui ne font pas partie du processus de signature mais doivent suivre chacune de ses étapes.
documents[0].readers[x].name	String obligatoire	Nom du lecteur.
documents[0].readers[x].email	String obligatoire	Adresse e-mail du lecteur.
documents[0].signProfile	Array obligatoire	Liste d’objets contenant les informations de chaque signataire ou approbateur pour la notification et la signature.
documents[0].signProfile[x].name	String obligatoire	Nom du signataire.
documents[0].signProfile[x].email	String obligatoire	Adresse e-mail du signataire. C’est ce qu’Auco utilise pour le relier à chaque document du lot ; elle est donc obligatoire même lorsque vous le notifiez par WhatsApp. Son omission renvoie SIGNER_EMAIL_REQUIRED.
documents[0].signProfile[x].phone	String facultatif	Numéro de téléphone du signataire, avec l’indicatif du pays. Requis si le lot utilise WhatsApp comme canal.
documents[0].signProfile[x].position	Array conditionnel	Positions de signature de ce signataire sur chaque page. Les positions de signature peuvent être préchargées dans les modèles. Pour en savoir plus, consultez comment définir les positions de signature.
documents[0].signProfile[x].type	Array conditionnel	Nom utilisé pour identifier le type de signataire s’il est préenregistré dans un modèle, par exemple : 'co-signer'.
documents[0].signProfile[x].label	Boolean conditionnel	Indique si le positionnement des signatures se fera à l’aide d’étiquettes dans le PDF.
documents[0].signProfile[x].notification	Boolean facultatif	Remplace le paramètre global notification pour ce signataire, dans les deux sens : false le rend silencieux même si la valeur globale est true, et true fait qu’Auco le notifie même si la valeur globale est false. Si le même e-mail apparaît dans plusieurs documents avec des valeurs différentes, false l’emporte. S’applique uniquement aux documents PDF ; pour les documents issus d’un modèle, l’indicateur par signataire est défini dans le signatureProfile du modèle.

Les validations d’identité dans les lots sont globales

Dans ce service, la validation d’identité et le canal de signature sont configurés une seule fois pour l’ensemble du lot, à l’aide de camera, otpCode et options à la racine de la requête, et s’appliquent de la même manière à tous les participants.

La création de lot ne prend pas en charge les validations d’identité ni le choix du canal par participant. L’envoi de camera, otpCode ou options dans signProfile[x] renvoie l’erreur SIGNER_VALIDATIONS_NOT_SUPPORTED. Si vous avez besoin de validations différentes selon les participants, créez des processus distincts avec POST /document/upload.

Un lot n’a ni signature séquentielle ni rôles

Tous les participants d’un lot sont notifiés en même temps : il n’y a ni tours de signature ni étapes d’approbation. L’envoi de role ou order dans signProfile[x] renvoie l’erreur SIGNER_SEQUENCE_NOT_SUPPORTED.

Si vous avez besoin que certains participants signent avant d’autres, ou que quelqu’un approuve avant le début de la signature, créez des processus distincts avec POST /document/upload, qui prend en charge order et role.

---

🧪 Exemples d’utilisation

astuce

Vous pouvez copier n’importe lequel des exemples selon votre langage de programmation préféré.

• Les adresses e-mail et les numéros de téléphone ne doivent pas se répéter entre signataires.
• Les lecteurs recevront une notification à chaque mise à jour du processus de signature.
• Format de date : 'DD/MM/YYYY'
• Les numéros de téléphone doivent inclure l’indicatif du pays, par exemple : +57, +1, +52...

Lot de documents via PDF

curl

curl --location 'https://api.auco.ai/v1.5/ext/document/many' \
--header 'Authorization: prk_e1cd6a01ecdb4b4ea72ec118e33b18de' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prueba paquete 2 documentos",
    "email": "example@auco.ai",
    "message": "Hola a todos, les comparto el paquete de documentos para la firma",
    "options": {
        "camera": "identification",
        "whatsapp": true
    },
    "camera": true,
    "otpCode": false,
    "documents": [
        {
            "name": "Documento 1",
            "signProfile": [
                {
                    "type": "solicitante",
                    "name": "Firmante 1",
                    "phone": "+573000000000",
                    "email": "example1@auco.ai"
                }
            ]
        },
        {
            "name": "Documento 2",
            "signProfile": [
                {
                    "type": "solicitante",
                    "name": "Firmante 1",
                    "phone": "+573000000000",
                    "email": "example2@auco.ai"
                }
            ]
        }
    ]
}

Python

import requests
import json

url = "https://api.auco.ai/v1.5/ext/document/many"

payload = json.dumps({
  "name": "Contract package",
  "email": "example@auco.ai",
  "message": "Hola a todos, les comparto el paquete de documentos para la firma",
  "options": {
    "camera": "identification",
    "whatsapp": True
  },
  "camera": True,
  "otpCode": False,
  "documents": [
    {
      "name": "Documento 1",
      "signProfile": [
        {
          "type": "solicitante",
          "name": "Firmante 1",
          "phone": "+573000000000",
          "email": "example1@auco.ai"
        }
      ]
    },
    {
      "name": "Documento 2",
      "signProfile": [
        {
          "type": "solicitante",
          "name": "Firmante 1",
          "phone": "+573000000000",
          "email": "example2@auco.ai"
        }
      ]
    }
  ]
})
headers = {
  'Authorization': 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Node.js

const axios = require('axios');
let data = JSON.stringify({
  name: 'Contract package',
  email: 'example@auco.ai',
  message: 'Hola a todos, les comparto el paquete de documentos para la firma',
  options: {
    camera: 'identification',
    whatsapp: true,
  },
  camera: true,
  otpCode: false,
  documents: [
    {
      name: 'Documento 1',
      signProfile: [
        {
          type: 'solicitante',
          name: 'Firmante 1',
          phone: '+573000000000',
          email: 'example1@auco.ai',
        },
      ],
    },
    {
      name: 'Documento 2',
      signProfile: [
        {
          type: 'solicitante',
          name: 'Firmante 1',
          phone: '+573000000000',
          email: 'example2@auco.ai',
        },
      ],
    },
  ],
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/document/many',
  headers: {
    Authorization: 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
    'Content-Type': 'application/json',
  },
  data: data,
};

axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Lot de documents via modèles personnalisés

curl

curl --location 'https://api.auco.ai/v1.5/ext/document/many' \
--header 'Authorization: prk_e1cd6a01ecdb4b4ea72ec118e33b18de' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Contract package",
    "email": "example@auco.ai",
    "message": "Hola a todos, les comparto el paquete de documentos para la firma",
    "options": {
        "camera": "identification",
        "whatsapp": true
    },
    "camera": true,
    "otpCode": false,
    "documents": [
        {
            "name": "Documento 1",
            "document": "documentId",
            "data": [
                {"key": "signer_nombre", "value":"firmante 1"},
                {"key": "signer_identification", "value":"cc"},
                {"key": "signer_phone", "value":"+573000000000"},
                {"key": "manager_name", "value":"manager 1"}
            ]
        },
        {
            "name": "Documento 2",
            "document": "documentId",
            "data": [
                {"key": "signer_nombre", "value":"firmante 1"},
                {"key": "signer_identification", "value":"cc"},
                {"key": "signer_phone", "value":"+573000000000"},
                {"key": "manager_name", "value":"manager 1"}
            ]
        }
    ]
}'

Python

import requests
import json

url = "https://api.auco.ai/v1.5/ext/document/many"

payload = json.dumps({
  "name": "Contract package",
  "email": "example@auco.ai",
  "message": "Hola a todos, les comparto el paquete de documentos para la firma",
  "options": {
    "camera": "identification",
    "whatsapp": True
  },
  "camera": True,
  "otpCode": False,
  "documents": [
    {
      "name": "Documento 1",
      "document": "documentId",
      "data": [
        {
          "key": "signer_nombre",
          "value": "firmante 1"
        },
        {
          "key": "signer_identification",
          "value": "cc"
        },
        {
          "key": "signer_phone",
          "value": "+573000000000"
        },
        {
          "key": "manager_name",
          "value": "manager 1"
        }
      ]
    },
    {
      "name": "Documento 2",
      "document": "documentId",
      "data": [
        {
          "key": "signer_nombre",
          "value": "firmante 1"
        },
        {
          "key": "signer_identification",
          "value": "cc"
        },
        {
          "key": "signer_phone",
          "value": "+573000000000"
        },
        {
          "key": "manager_name",
          "value": "manager 1"
        }
      ]
    }
  ]
})
headers = {
  'Authorization': 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Node.js

const axios = require('axios');
let data = JSON.stringify({
  name: 'Contract package',
  email: 'example@auco.ai',
  message: 'Hola a todos, les comparto el paquete de documentos para la firma',
  options: {
    camera: 'identification',
    whatsapp: true,
  },
  camera: true,
  otpCode: false,
  documents: [
    {
      name: 'Documento 1',
      document: 'documentId',
      data: [
        {
          key: 'signer_nombre',
          value: 'firmante 1',
        },
        {
          key: 'signer_identification',
          value: 'cc',
        },
        {
          key: 'signer_phone',
          value: '+573000000000',
        },
        {
          key: 'manager_name',
          value: 'manager 1',
        },
      ],
    },
    {
      name: 'Documento 2',
      document: 'documentId',
      data: [
        {
          key: 'signer_nombre',
          value: 'firmante 1',
        },
        {
          key: 'signer_identification',
          value: 'cc',
        },
        {
          key: 'signer_phone',
          value: '+573000000000',
        },
        {
          key: 'manager_name',
          value: 'manager 1',
        },
      ],
    },
  ],
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/document/many',
  headers: {
    Authorization: 'prk_e1cd6a01ecdb4b4ea72ec118e33b18de',
    'Content-Type': 'application/json',
  },
  data: data,
};

axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

---

📥 Exemples de réponses

Lot de documents via PDF

{
  "id": "packageId",
  "documents": [
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 1",
      "code": "CODEDOC1",
      "signProfile": [{ "name": "Firmante 1", "email": "example1@auco.ai" }]
    },
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 2",
      "code": "CODEDOC2",
      "signProfile": [{ "name": "Firmante 1", "email": "example2@auco.ai" }]
    }
  ]
}

info

L’URL signée fournie dans la réponse ne sera disponible que pendant 300 secondes (5 minutes). Elle doit être utilisée pour téléverser le document PDF au format binaire via une requête HTTP PUT.

Via modèles personnalisés

{
  "id": "packageId",
  "documents": [
    {
      "name": "Documento 1",
      "code": "CODEDOC1",
      "signProfile": [{ "name": "Firmante 1", "email": "example1@auco.ai" }]
    },
    {
      "name": "Documento 2",
      "code": "CODEDOC2",
      "signProfile": [{ "name": "Firmante 1", "email": "example2@auco.ai" }]
    }
  ]
}

🔹 Signataires qu’Auco ne notifie pas

Un signataire est silencieux lorsque sa valeur effective de notification est false : la sienne s’il en a une, sinon la valeur globale. signProfile est toujours renvoyé dans la réponse ; la différence est que les signataires silencieux portent un id et que ceux qu’Auco notifie n’en ont pas, car leur accès est généré lors de l’envoi de l’e-mail.

Cet exemple désactive la notification pour l’ensemble du lot et ne la réactive que pour example2@auco.ai :

{
  "name": "Contract package",
  "email": "example@auco.ai",
  "notification": false,
  "documents": [
    {
      "name": "Documento 1",
      "signProfile": [
        { "type": "solicitante", "name": "Firmante 1", "email": "example1@auco.ai" },
        { "type": "aprobador", "name": "Firmante 2", "email": "example2@auco.ai", "notification": true }
      ]
    },
    {
      "name": "Documento 2",
      "signProfile": [
        { "type": "solicitante", "name": "Firmante 1", "email": "example1@auco.ai" }
      ]
    }
  ]
}

Firmante 1 apparaît dans les deux documents ; il reçoit donc le même id dans chacun : il s’agit d’une seule personne au sein du lot. Firmante 2 n’a pas d’id car Auco s’en charge.

{
  "id": "packageId",
  "documents": [
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 1",
      "code": "CODEDOC1",
      "signProfile": [
        { "id": "0Q", "name": "Firmante 1", "email": "example1@auco.ai" },
        { "name": "Firmante 2", "email": "example2@auco.ai" }
      ]
    },
    {
      "url": "https://signed_url_to_upload_PDF",
      "name": "Documento 2",
      "code": "CODEDOC2",
      "signProfile": [{ "id": "0Q", "name": "Firmante 1", "email": "example1@auco.ai" }]
    }
  ]
}

Champ	Type	Description
documents[x].signProfile	Array	Liste des signataires du document.
documents[x].signProfile[y].id	String	Identifiant du signataire au sein du lot. Présent uniquement lorsqu’Auco ne le notifie pas ; régénéré si vous écrasez le lot.
documents[x].signProfile[y].name	String	Nom du signataire.
documents[x].signProfile[y].email	String	E-mail du signataire.

---

⚠️ Réponses d’erreur

Code	Description
400	Paramètres manquants, ou une ou plusieurs validations ne remplissent pas les conditions d’applicabilité.
400	DOCUMENTS_MIN_TWO — Le tableau documents doit comporter au moins 2 éléments. Utilisez /document/upload pour un seul document.
401	Authentification invalide ou manquante.