Envoi de document

POST/document/uploadclé privéeprk_

Ce service permet de lancer un processus de demande de pièces jointes avec signature ou de pièces jointes seules, sans signature. Chaque pièce jointe peut être configurée comme obligatoire ou facultative.

info

Si vous souhaitez inclure un processus de signature, vous pouvez envoyer directement un document PDF au format base64. Si vous souhaitez que la demande de signature et de pièces jointes fasse partie d'un modèle, notez que ce flux ne peut pas être configuré directement via l'endpoint ; vous devez solliciter l'assistance de notre équipe.

info

Avant d'intégrer cet endpoint, vous pouvez consulter comment définir les positions de signature et les paramètres de validation d'identité.

---

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.
code	String facultatif	Code d'un document préalablement mis en édition. L'envoyer écrase ce processus au lieu d'en créer un nouveau, en conservant son code. Renvoyez la charge utile complète : tout ce que vous omettez est supprimé. En savoir plus
document	String conditionnel	Si vous souhaitez créer le processus à partir d'un modèle, vous devez envoyer l'ID du modèle dans ce champ. Pour consulter et obtenir les modèles, accédez à cette documentation.
name	String obligatoire	Nom du processus de signature du document, uniquement si le processus de pièces jointes inclut la signature du document.
message	String conditionnel	Message qui sera inclus dans le corps de l'e-mail notifiant les signataires ou les approbateurs du document. Obligatoire lorsqu'un participant est notifié par e-mail.
subject	String conditionnel	Objet de l'e-mail de notification envoyé aux signataires ou aux approbateurs. Obligatoire lorsqu'un participant est notifié par e-mail.
file	String conditionnel	Si vous souhaitez envoyer le document dans la même requête, transmettez le fichier PDF en Base64 dans ce paramètre. (Uniquement pour les petits fichiers)
compress	Boolean conditionnel	Si le fichier PDF à envoyer est trop volumineux, il est recommandé de ne pas envoyer le paramètre file ; utilisez plutôt compress: true. Ainsi, le service renvoie une URL signée permettant d'envoyer le fichier PDF au format binaire via une requête PUT.
folder	String conditionnel	Si vous souhaitez enregistrer ce processus dans un dossier spécifique, indiquez le chemin de ce dossier dans ce paramètre. Notez que le dossier doit exister et appartenir au créateur du processus.
remember	Number conditionnel	Paramètre qui active les rappels automatiques avec l'intervalle de temps (en heures) entre chaque notification.
expiredDate	Date facultatif	Date d'expiration du document. Elle doit être postérieure de plus de 3 jours à la date de création du processus et est envoyée au format Date JSON.
camera	Boolean facultatif	Ce paramètre indique si la validation par photo est requise. Par défaut false.
otpCode	Boolean facultatif	Ce paramètre indique si la validation par code OTP est requise. Par défaut false.
options	Object facultatif	Ce paramètre 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éé. Par défaut true. C'est la valeur par défaut pour chaque signataire ; chacun peut la remplacer avec signProfile[x].notification.
targetWebhooks	Array[String] facultatif	Si vous avez plusieurs webhooks, vous pouvez envoyer le nom du webhook auquel vous souhaitez que les mises à jour de ce processus soient notifiées.
tags	Array[String] facultatif	Si vous souhaitez classer les processus avec des étiquettes, vous pouvez envoyer les noms des étiquettes auxquelles associer le processus (elles doivent exister).
custom	Object facultatif	Objet libre pour envoyer des paramètres définis par l'intégrateur (par exemple, des identifiants internes ou des métadonnées). Auco le conserve tel quel et le transmet dans les notifications webhook et dans la réponse de GET /document, sans interpréter ni valider son contenu.
readers	Array facultatif	Ce paramètre est une liste d'objets définissant les participants qui ne font pas partie du processus de signature mais qui doivent pouvoir suivre chaque phase de celui-ci.
readers[x].name	String obligatoire	Nom du lecteur.
readers[x].email	String obligatoire	E-mail du lecteur.
signProfile	Array obligatoire	Ce champ est une liste d'objets contenant les informations de chaque signataire ou approbateur pour sa notification et sa signature.
signProfile[x].name	String obligatoire	Nom du signataire.
signProfile[x].email	String obligatoire	E-mail du signataire.
signProfile[x].phone	String obligatoire	Numéro de téléphone du signataire.
signProfile[x].role	String conditionnel	Ce paramètre définit le rôle du participant ; il peut être 'APPROVER' ou 'SIGNER'.
signProfile[x].order	String conditionnel	Ce paramètre définit l'ordre dans lequel se déroulera le processus de notification pour la signature ou l'approbation.
signProfile[x].label	Boolean(true) | String conditionnel	Paramètre indiquant si le positionnement des signatures se fera à l'aide de balises dans le PDF.
signProfile[x].position	Array conditionnel	Dans ce paramètre sont envoyées les positions de signature de ce signataire sur chaque page. Les positions de signature peuvent être préchargées dans les modèles. Pour plus d'informations, consultez la documentation.
signProfile[x].type	String conditionnel	Nom utilisé pour identifier le type de signataire s'il est préenregistré dans un modèle, par exemple 'co-signer'.
signProfile[x].options	Object facultatif	Permet de définir des validations personnalisées pour un signataire spécifique. Si vous souhaitez appliquer des validations individuellement par signataire, en savoir plus.
signProfile[x].camera	Boolean facultatif	Si vous souhaitez des validations individuelles par signataire et exigez une validation par photo, envoyez ce paramètre à true. Par défaut false.
signProfile[x].otpCode	Boolean facultatif	Si vous souhaitez des validations individuelles par signataire et exigez une validation par code OTP, envoyez ce paramètre à true. Par défaut false.
signProfile[x].notification	Boolean facultatif	Remplace la valeur globale 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. Les signataires silencieux reçoivent un id dans la réponse.

---

🧪 Exemples d'utilisation

astuce

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

• N'oubliez pas que les adresses e-mail et les numéros de téléphone des signataires ne doivent pas être répétés.
• Les lecteurs recevront des notifications pour chaque mise à jour du processus de signature.

Processus de signature avec rappels automatiques (PDF Base64)

Dans ce cas, les rappels seront envoyés toutes les 3 heures.

curl

curl --location 'https://api.auco.ai/v1.5/ext/document/upload' \
--header 'Authorization: prk_private_key_company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Documento de prueba",
    "subject": "prueba auco",
    "message": "prueba auco",
    "remember": 3,
    "email": "example@auco.ai",
    "signProfile": [
        {
            "name": "Jhon Firma",
            "email": "example@auco.ai",
            "label": true
        }
    ],
    "readers":[{"email":"example2@auco.ai", "name":"Frimante 1"}],
    "file": Base64
}'

Python

import requests
import json

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

payload = json.dumps({
  "name": "Documento de prueba",
  "subject": "prueba auco",
  "message": "prueba auco",
  "remember": 3,
  "email": "example@auco.ai",
  "signProfile": [
    {
      "name": "Jhon Firma",
      "email": "example@auco.ai",
      "label": True
    }
  ],
  "readers": [
    {
      "email": "example2@auco.ai",
      "name": "Frimante 1"
    }
  ],
  "file": Base64
})
headers = {
  'Authorization': 'prk_private_key_company',
  '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: 'Documento de prueba',
  subject: 'prueba auco',
  message: 'prueba auco',
  remember: 3,
  email: 'example@auco.ai',
  signProfile: [
    {
      name: 'Jhon Firma',
      email: 'example@auco.ai',
      label: true,
    },
  ],
  readers: [
    {
      email: 'eyvasquezt30@gmail.com',
      name: 'Frimante 1',
    },
  ],
  file: Base64,
});

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

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

---

Signature de document avec validations individuelles (compress - PDF binaire)

curl

curl --location 'https://api.auco.ai/v1.5/ext/document/upload' \
--header 'Authorization: prk_private_key_company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prueba de Anexos Compress y validaciones individuales",
    "email": "owner@auco.ai",
    "message": "Cargar adjuntos de prueba",
    "subject": "Solicitud de adjuntos",
    "signProfile": [
        {
            "type": "firmante1",
            "name": "Nombre Firmante 1",
            "email": "example @auco.ai",
            "camera": true,
            "otpCode": true,
            "options": {
                "camera": "identification",
                "whatsapp": true,
                "otpCode": "email"
            },
            "phone": "+573000000000",
        },
        {
            "type": "firmante2",
            "name": "Nombre Firmante 2",
            "email": "example2@auco.ai",
            "phone": "+573000000000",
            "otpCode": true,
            "options": {
                "otpCode": "email"
            },
        }
    ],
    "compress": true
}'

Python

import requests
import json

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

payload = json.dumps({
  "name": "Prueba de Anexos Compress y validaciones individuales",
  "email": "owner@auco.ai",
  "message": "Cargar adjuntos de prueba",
  "subject": "Solicitud de adjuntos",
  "signProfile": [
    {
      "type": "firmante1",
      "name": "Nombre Firmante 1",
      "email": "example @auco.ai",
      "camera": True,
      "otpCode": True,
      "options": {
        "camera": "identification",
        "whatsapp": True,
        "otpCode": "email"
      },
      "phone": "+573000000000",
    },
    {
      "type": "firmante2",
      "name": "Nombre Firmante 2",
      "email": "example2@auco.ai",
      "phone": "+573000000000",
      "otpCode": True,
      "options": {
        "otpCode": "email"
      }
    }
  ],
  "compress": True
})
headers = {
  'Authorization': 'prk_private_key_company',
  '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: 'Prueba de Anexos Compress y validaciones individuales',
  email: 'owner@auco.ai',
  message: 'Cargar adjuntos de prueba',
  subject: 'Solicitud de adjuntos',
  signProfile: [
    {
      type: 'firmante1',
      name: 'Nombre Firmante 1',
      email: 'example @auco.ai',
      camera: true,
      otpCode: true,
      options: {
        camera: 'identification',
        whatsapp: true,
        otpCode: 'email',
      },
      phone: '+573000000000',
      files: [
        {
          name: 'cedula de ciudadanía',
        },
        {
          name: 'hoja de vida',
        },
        {
          name: 'pasaporte',
          optional: true,
        },
      ],
    },
    {
      type: 'firmante2',
      name: 'Nombre Firmante 2',
      email: 'example2@auco.ai',
      phone: '+573000000000',
      otpCode: true,
      options: {
        otpCode: 'whatsapp',
      },
    },
  ],
  compress: true,
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.auco.ai/v1.5/ext/document/upload',
  headers: {
    Authorization: 'prk_private_key_company',
    '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

🔹 Mode normal (sans compress ou avec compress: false)

{
  "document": "ABCDEF1234"
}

Champ	Type	Description
document	String	Code unique du document créé.

🔸 Mode compress (compress: true)

info

L'URL pré-signée fournie dans la réponse est à usage unique et ne sera disponible que pendant 300 secondes (5 minutes). Elle doit être utilisée pour envoyer le document PDF au format binaire via une requête HTTP PUT.

{
  "document": "ABCDEF1234",
  "url": "https://s3.amazonaws.com/...signed-url..."
}

Champ	Type	Description
document	String	Code unique du document créé.
url	String	URL S3 pré-signée pour envoyer le PDF (expire en 300 s).

🔹 Signataires qu'Auco ne notifie pas

La réponse inclut signProfile lorsqu'un signataire est rendu silencieux, c'est-à-dire lorsque sa valeur effective de notification est false : la sienne s'il en possède une, sinon la valeur globale. Chaque signataire silencieux porte un id que l'intégrateur utilise pour l'amener à signer de manière autonome. Les signataires qu'Auco notifie apparaissent sans id : leur accès est généré lors de leur notification.

{
  "document": "ABCDEF1234",
  "signProfile": [
    {
      "id": "abc123",
      "name": "Juan",
      "email": "juan@email.com",
      "phone": "+57300..."
    }
  ]
}

Champ	Type	Description
document	String	Code unique du document créé.
signProfile	Array	Liste des signataires du processus.
signProfile[x].id	String	Identifiant unique du signataire.
signProfile[x].name	String	Nom du signataire.
signProfile[x].email	String	Adresse e-mail du signataire.
signProfile[x].phone	String	Numéro de téléphone du signataire.

astuce

Ce champ est également inclus en mode compress, avec l'url.

---

⚠️ Réponses d'erreur

Code	Description
400	Paramètres manquants, ou certaines validations ne remplissent pas les conditions d'applicabilité
401	Authentification invalide ou manquante