Les mêmes routes servent aux documents que vous envoyez (contrats signés, conventions de stage…) et à ceux que Puncto génère (bulletins, documents de fin de contrat, DPAE, DSN, documents comptables…). Seuls les documents envoyés par l’API peuvent être modifiés ou supprimés.
Envoyer un document
Envoyez le fichier en multipart/form-data :
curl -X POST https://api.puncto.fr/public/v1/documents \
-H "Authorization: Bearer $PUNCTO_TOKEN" \
-F file=@contrat-cdi-signe.pdf \
-F fileType=CONTRACT \
-F collaboratorId=coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY \
-F foreignErpId=contrat-salarie-123| Champ | Contenu |
|---|---|
file |
le fichier, 20 Mo au plus : pdf, jpg, jpeg, png, webp, heic, txt, csv, xml, json, xlsx, doc, docx ou zip |
fileType |
CONTRACT, INTERNSHIP_AGREEMENT, DPAE ou OTHER |
collaboratorId |
l’identifiant Puncto du collaborateur concerné, requis sauf pour OTHER ; un OTHER sans collaborateur est un document de l’entreprise |
displayFileName |
le nom affiché dans Puncto, par défaut celui du fichier |
foreignErpId |
l’identifiant du document dans votre système, facultatif |
La réponse 201 décrit le document créé :
{
"documentId": "cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
"foreignErpId": "contrat-salarie-123",
"fileName": "contrat-cdi-signe.pdf",
"fileType": "CONTRACT",
"mimeType": "application/pdf",
"collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
"createdAt": "2026-10-28T09:30:00.000Z"
}Bon à savoir :
mimeTypeest déduit du contenu (PDF, images, archives). Pour un fichier texte, il reprend le type annoncé dans la requête, que vous devez donc préciser pour un CSV ou un JSON (-F "file=@export.csv;type=text/csv").- Les formats bureautiques (docx, xlsx, doc) sont enregistrés en
application/octet-stream, mais leurfileNamegarde l’extension. fileNameest le nom du document suivi de l’extension du fichier, sauf s’il se termine déjà par une extension (.pdf,.docx…). Par exemple, « Avenant du 01.03.2026 » se télécharge sous le nomAvenant du 01.03.2026.pdf.
Éviter les doublons
Passez un foreignErpId, qui est unique dans l’entreprise. Si un envoi reprend un foreignErpId
déjà connu, aucun document n’est créé et la réponse 409 contient le documentId existant. Vous
pouvez donc rejouer une requête sans risque après une coupure réseau.
{
"error": "Un document existe déjà avec le foreignErpId \"contrat-salarie-123\"",
"documentId": "cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
}Sans foreignErpId (ou avec une valeur vide), chaque envoi crée un document.
Remplacer un document
PUT /public/v1/documents/{documentId} remplace le
fichier, le nom, ou les deux, en multipart/form-data. Un champ omis ne change pas. Le
collaborateur, le type et le foreignErpId restent les mêmes.
curl -X PUT https://api.puncto.fr/public/v1/documents/cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY \
-H "Authorization: Bearer $PUNCTO_TOKEN" \
-F file=@contrat-cdi-signe-lisible.pdfLister et télécharger
La liste est triée du plus récent au plus ancien, avec 200 documents par page au plus. Par exemple, pour les contrats et avenants d’un collaborateur :
curl -g "https://api.puncto.fr/public/v1/documents?collaboratorForeignErpId=salarie-123&type[]=CONTRACT" \
-H "Authorization: Bearer $PUNCTO_TOKEN"Vous pouvez ensuite consulter ou
télécharger un document avec son documentId. Le
fichier téléchargé porte le nom indiqué dans fileName :
curl -OJ https://api.puncto.fr/public/v1/documents/cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY/download \
-H "Authorization: Bearer $PUNCTO_TOKEN"Bon à savoir :
- Les filtres
type[],minCreationDate,maxCreationDateetforeignErpIdse combinent. Un filtre collaborateur écarte les documents de l’entreprise. - Certains fichiers ne sont jamais exposés : les fichiers techniques (retours DPAE, CRM), les factures Puncto, les archives d’export et l’historique repris de votre ancien logiciel de paie.
- Les justificatifs se téléchargent de la même façon, avec
familyProofFile.idetworkStoppage.proofFile.idpour une absence, etproofFiles[].documentIdpour une variable de paie ou une variable récurrente.
Supprimer un document
DELETE /public/v1/documents/{documentId} supprime un
document envoyé par l’API et son fichier (204).
Pour les autres documents, la suppression comme le remplacement renvoient 400 :
- document généré par Puncto ou ajouté dans l’application ;
- justificatif d’une variable de paie (supprimé avec sa variable) ;
- fichier lié à une DPAE ;
- document envoyé sans
foreignErpIdpar une clé d’API révoquée depuis.