---
title: "Envoyer et récupérer des documents"
description: "Déposer un contrat signé ou un justificatif, et télécharger les documents de l’entreprise."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.puncto.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Envoyer et récupérer des documents

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](/reference/documents/create) en `multipart/form-data` :

```bash
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éé :

```json
{
  "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"
}
```

> **Caution**
>
> Un document rattaché à un collaborateur est immédiatement visible par les administrateurs et par le
> collaborateur dans son espace Puncto, quel que soit son type. N’envoyez pas ici un document qui
> ne doit pas lui être communiqué.

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.

```json
{
  "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}`](/reference/documents/update) 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.

```bash
curl -X PUT https://api.puncto.fr/public/v1/documents/cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY \
  -H "Authorization: Bearer $PUNCTO_TOKEN" \
  -F file=@contrat-cdi-signe-lisible.pdf
```

> **Caution**
>
> Le remplacement supprime l’ancien fichier. Pour conserver chaque document signé (le contrat, puis
> chaque avenant), envoyez-le comme un nouveau document.

## Lister et télécharger

[La liste](/reference/documents/list) 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 :

```bash
curl -g "https://api.puncto.fr/public/v1/documents?collaboratorForeignErpId=salarie-123&type[]=CONTRACT" \
  -H "Authorization: Bearer $PUNCTO_TOKEN"
```

Vous pouvez ensuite [consulter](/reference/documents/retrieve) ou
[télécharger](/reference/documents/download) un document avec son `documentId`. Le
fichier téléchargé porte le nom indiqué dans `fileName` :

```bash
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.

> **Note**
>
> Une clé en lecture seule permet de télécharger tous les documents exposés, y compris les pièces
> d’identité, les RIB et les bulletins de paie. Traitez-la comme une donnée sensible.

## Supprimer un document

[`DELETE /public/v1/documents/{documentId}`](/reference/documents/delete) 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.

Source: https://docs.puncto.fr/developpeurs/guides/documents/index.mdx
