Skip to content

Envoyer et récupérer des documents

Déposer un contrat signé ou un justificatif, et télécharger les documents de l’entreprise.

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 :

  • mimeType est 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 leur fileName garde l’extension.
  • fileName est 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 nom Avenant 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.pdf

Lister 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, maxCreationDate et foreignErpId se 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.id et workStoppage.proofFile.id pour une absence, et proofFiles[].documentId pour 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 foreignErpId par une clé d’API révoquée depuis.

Type to search…

↑↓ navigate↵ selectEsc close