Créer un processus de pièces jointes

POST/package/uploadclé privéeprk_

Ce service permet de lancer un processus de demande de pièces jointes à signer, ou simplement de pièces jointes 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 téléverser le document PDF dans la même requête : en Base64 avec file, ou en binaire (via une URL signée avec PUT) en utilisant compress. Si vous souhaitez que la signature et la demande de pièces jointes fassent partie d'un modèle de parcours préenregistré, celui-ci doit être configuré au préalable avec notre équipe d'assistance ; une fois créé, vous le référencez par son identifiant dans le champ document.

info

Avant d'intégrer ce endpoint, il peut être utile de consulter comment définir les positions de signature et la configuration des validations d'identité.

---

Authentification

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

Authorization: prk_xxx...

---

Paramètres de création

info

• Les champs file, compress et document sont mutuellement exclusifs : vous pouvez en envoyer au maximum un. Si vous n'en envoyez aucun, un processus de collecte de pièces jointes uniquement, sans signature, est créé (aucun document n'est généré) et, dans ce cas, name n'est pas non plus obligatoire.
• Chaque objet signProfile doit inclure exactement un parmi type, label ou position (mutuellement exclusifs, un seul étant obligatoire), y compris dans les processus de pièces jointes uniquement, sans signature.

Nom	Type	Description
email	String obligatoire	Adresse e-mail du créateur du processus.
document	String conditionnel	Identifiant d'un modèle de parcours préenregistré (créé au préalable avec l'équipe d'assistance) utilisé pour créer le processus.
name	String conditionnel	Nom du document à signer. Obligatoire uniquement si le processus inclut un document (file, compress ou document). Dans un processus de collecte de pièces jointes uniquement, sans signature, il n'est pas nécessaire de l'envoyer.
packageName	String obligatoire	Nom du dossier qui contiendra les pièces jointes et le document à signer (s'il est inclus).
message	String facultatif	Message qui sera inclus dans le corps de l'e-mail de notification envoyé aux signataires ou aux approbateurs. S'il n'est pas envoyé, Auco utilise une valeur par défaut.
subject	String facultatif	Objet de l'e-mail de notification envoyé aux signataires ou aux approbateurs. S'il n'est pas envoyé, Auco utilise une valeur par défaut.
file	String conditionnel	Si vous souhaitez téléverser le document dans la même requête, envoyez le fichier PDF au format Base64 dans ce paramètre. (Uniquement pour les petits fichiers)
compress	Boolean conditionnel	Si le fichier PDF à téléverser est trop volumineux, il est recommandé de ne pas envoyer le paramètre file ; utilisez plutôt compress: true. Le service renverra une URL signée permettant de téléverser 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 ici le chemin de ce dossier. 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 être envoyée au format JSON Date.
camera	Boolean facultatif	Indique si une validation par photo est requise. La valeur par défaut est false.
otpCode	Boolean facultatif	Indique si une validation par code OTP est requise. La valeur par défaut est false.
options	Object facultatif	Spécifie la configuration des validations d'identité.
signProfile	Array obligatoire	Liste d'objets contenant les informations de chaque signataire ou approbateur pour la notification et la signature.
signProfile[x].name	String obligatoire	Nom de l'utilisateur des pièces jointes.
signProfile[x].email	String obligatoire	Adresse e-mail de l'utilisateur des pièces jointes.
signProfile[x].phone	String obligatoire	Numéro de téléphone de l'utilisateur des pièces jointes.
signProfile[x].role	String conditionnel	Définit le rôle du participant ; peut être 'APPROVER' ou 'SIGNER'.
signProfile[x].order	String conditionnel	Définit l'ordre dans lequel le processus de notification pour la signature ou l'approbation aura lieu.
signProfile[x].label	Boolean conditionnel	Indique si le positionnement des signatures sera effectué à l'aide d'étiquettes (labels) dans le PDF.
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 plus d'informations, consultez la documentation.
signProfile[x].type	String conditionnel	Identifiant du 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 donné. Si vous souhaitez appliquer des validations individuelles par signataire, ce paramètre accepte les mêmes champs que options global. Vous pouvez combiner validations globales et individuelles, en appliquant par défaut les validations globales et les validations individuelles là où un traitement spécial est nécessaire.
signProfile[x].camera	Boolean facultatif	Pour disposer de validations individuelles par signataire et exiger une validation par photo, définissez ce paramètre à true. La valeur par défaut est false.
signProfile[x].otpCode	Boolean facultatif	Pour disposer de validations individuelles par signataire et exiger une validation par OTP, définissez ce paramètre à true. La valeur par défaut est false.
signProfile[x].files	Array obligatoire	Liste des fichiers joints qui seront demandés au signataire.
signProfile[x].files[x].name	String obligatoire	Nom du fichier joint.
signProfile[x].files[x].optional	Boolean facultatif	Si un fichier joint est facultatif, envoyez ce paramètre à true. La valeur par défaut est false.

Auco notifie toujours dans un processus de pièces jointes

Contrairement à POST /document/many et POST /document/upload, la notification ne peut pas être désactivée ici : Auco écrit à chaque participant pour lui demander ses fichiers. L'envoi de notification à la racine ou dans signProfile[x] renvoie une erreur — pour le niveau signataire, SIGNER_NOTIFICATION_NOT_SUPPORTED.

---

🧪 Exemples d'utilisation

astuce

Vous pouvez copier l'un des exemples selon votre langage préféré.

Collecte de pièces jointes uniquement (sans document ni signature)

astuce

Aucun file, compress, document ni name n'est envoyé : le processus ne fait que demander des pièces jointes aux participants.

curl

curl --location 'https://api.auco.ai/v1.5/ext/package/upload' \
--header 'Authorization: prk_prk_tuLlavePrivada' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "owner@auco.ai",
    "message": "Cargar adjuntos de prueba",
    "subject": "Solicitud de adjuntos",
    "packageName": "Adjuntos sin firma",
    "signProfile": [
        {
            "type": "anexador1",
            "name": "Nombre Anexador 1",
            "email": "example@auco.ai",
            "phone": "+573000000000",
            "files": [
                {
                    "name": "cedula de ciudadanía"
                },
                {
                    "name": "hoja de vida",
                    "optional": true
                }
            ]
        }
    ]
}'

Python

import requests
import json

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

payload = json.dumps({
  "email": "owner@auco.ai",
  "message": "Cargar adjuntos de prueba",
  "subject": "Solicitud de adjuntos",
  "packageName": "Adjuntos sin firma",
  "signProfile": [
    {
      "type": "anexador1",
      "name": "Nombre Anexador 1",
      "email": "example@auco.ai",
      "phone": "+573000000000",
      "files": [
        {
          "name": "cedula de ciudadanía"
        },
        {
          "name": "hoja de vida",
          "optional": True
        }
      ]
    }
  ]
})
headers = {
  'Authorization': 'prk_prk_tuLlavePrivada',
  '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({
  email: 'owner@auco.ai',
  message: 'Cargar adjuntos de prueba',
  subject: 'Solicitud de adjuntos',
  packageName: 'Adjuntos sin firma',
  signProfile: [
    {
      type: 'anexador1',
      name: 'Nombre Anexador 1',
      email: 'example@auco.ai',
      phone: '+573000000000',
      files: [
        {
          name: 'cedula de ciudadanía',
        },
        {
          name: 'hoja de vida',
          optional: true,
        },
      ],
    },
  ],
});

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

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

---

Pièces jointes facultatives avec signature de document (PDF en Base64)

curl

curl --location 'https://api.auco.ai/v1.5/ext/package/upload' \
--header 'Authorization: prk_prk_tuLlavePrivada' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Contratación de prueba upload 1",
    "email": "owner@auco.ai",
    "message": "Cargar adjuntos de prueba",
    "subject": "Solicitud de adjuntos",
    "packageName": "Adjuntos api prueba",
    "file": Base64,
    "signProfile": [
        {
            "name": "Nombre Firmante 1",
            "email": "example@auco.ai",
            "phone": "+573000000000",
            "position": [
                {
                    "page": 1,
                    "x": 0.5854166461564629,
                    "y": 0.8034861200774693,
                    "w": 100,
                    "h": 50
                }
            ],
            "files": [
                {
                    "name": "cedula de ciudadanía"
                },
                {
                    "name": "hoja de vida"
                },
                {
                    "name": "pasaporte",
                    "optional": true
                }
            ]
        }
    ],
}'

Python

import requests
import json

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

payload = json.dumps({
  "name": "Contratación de prueba upload 1",
  "email": "owner@auco.ai",
  "message": "Cargar adjuntos de prueba",
  "subject": "Solicitud de adjuntos",
  "packageName": "Adjuntos api prueba",
  "file": Base64,
  "signProfile": [
    {
      "name": "Nombre Firmante 1",
      "email": "example@auco.ai",
      "phone": "+573000000000",
      "position": [
        {
          "page": 1,
          "x": 0.5854166461564629,
          "y": 0.8034861200774693,
          "w": 100,
          "h": 50
        }
      ],
      "files": [
        {
          "name": "cedula de ciudadanía"
        },
        {
          "name": "hoja de vida"
        },
        {
          "name": "pasaporte",
          "optional": True
        }
      ]
    }
  ],
})
headers = {
  'Authorization': 'prk_prk_tuLlavePrivada',
  '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: 'Contratación de prueba upload 1',
  email: 'owner@auco.ai',
  message: 'Cargar adjuntos de prueba',
  subject: 'Solicitud de adjuntos',
  packageName: 'Adjuntos api prueba',
  file: Base64,
  signProfile: [
    {
      name: 'Nombre Firmante 1',
      email: 'example@auco.ai',
      phone: '+573000000000',
      position: [
        {
          page: 1,
          x: 0.5854166461564629,
          y: 0.8034861200774693,
          w: 100,
          h: 50,
        },
      ],
      files: [
        {
          name: 'cedula de ciudadanía',
        },
        {
          name: 'hoja de vida',
        },
        {
          name: 'pasaporte',
          optional: true,
        },
      ],
    },
  ],
});

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

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

---

Pièces jointes facultatives avec signature de document (PDF compress et validations individuelles)

curl

curl --location 'https://api.auco.ai/v1.5/ext/package/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",
    "packageName": "Adjuntos api prueba 2",
    "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": "email"
            },
            "files": [
                {
                    "name": "certificado"
                }
            ]
        }
    ],
    "compress": true
}'

Python

import requests
import json

url = "https://api.auco.ai/v1.5/ext/package/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",
  "packageName": "Adjuntos api prueba 2",
  "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": "email"
      },
      "files": [
        {
          "name": "certificado"
        }
      ]
    }
  ],
  "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',
  packageName: 'Adjuntos api prueba 2',
  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: 'email',
      },
      files: [
        {
          name: 'certificado',
        },
      ],
    },
  ],
  compress: true,
});

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

🔹 Envoi du PDF en Base64 via l'attribut 'file'

{
  "package": "PROCESSID",
  "code": "DOCUMENTCODE"
}

🔹 Processus de pièces jointes uniquement (sans document)

info

Comme aucun document n'est créé, la réponse n'inclut que le package.

{
  "package": "PROCESSID"
}

🔸 Envoi de l'attribut 'compress'

info

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

{
  "package": "PROCESSID",
  "code": "DOCUMENTCODE",
  "url": "signed_url"
}

---

⚠️ Réponses d'erreur

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