---
title: "Envoyer un document"
description: "Envoie un document (contrat ou avenant signé, convention de stage, DPAE faite hors de Puncto…) en `multipart/form-data`.\n\n- Rattaché à un collaborateur, il est visible tout de suite par les administrateurs et dans son espace, sans notification.\n- Un `foreignErpId` déjà utilisé dans l’entreprise renvoie `409` avec le `documentId` existant. Pour remplacer un fichier, utilisez `PUT /public/v1/documents/{documentId}`.\n\nVoir le guide [Documents](/guides/documents)."
---

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

Path: API Puncto › Documents

`POST /public/v1/documents`

Envoie un document (contrat ou avenant signé, convention de stage, DPAE faite hors de Puncto…) en `multipart/form-data`.

- Rattaché à un collaborateur, il est visible tout de suite par les administrateurs et dans son espace, sans notification.
- Un `foreignErpId` déjà utilisé dans l’entreprise renvoie `409` avec le `documentId` existant. Pour remplacer un fichier, utilisez `PUT /public/v1/documents/{documentId}`.

Voir le guide [Documents](/guides/documents).

## Authentication

- `bearerAuth`, http, header `Authorization`

## Request body

_Required._

- `file` (`uploadDocument.file`; string, required) — Fichier du document, 20 Mo au plus. Extensions acceptées : pdf, jpg, jpeg, png, webp, heic, txt, csv, xml, json, xlsx, doc, docx, zip.
  - format `binary`
- `fileType` (`uploadDocument.fileType`; string, required) — Type de document. Les types `DPAE`, `CONTRACT`, `INTERNSHIP_AGREEMENT` concernent un collaborateur : `collaboratorId` est alors requis. - `DPAE` : DPAE - `CONTRACT` : Contrat - `INTERNSHIP_AGREEMENT` : Convention de stage - `OTHER` : Autre
  - one of `"DPAE"`, `"CONTRACT"`, `"INTERNSHIP_AGREEMENT"`, `"OTHER"`
- `displayFileName` (`uploadDocument.displayFileName`; string, optional) — Nom affiché dans Puncto. Par défaut, le nom du fichier envoyé.
  - minLength 1
- `collaboratorId` (`uploadDocument.collaboratorId`; string, optional) — Identifiant Puncto du collaborateur.
  - minLength 1; example `"coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"`
- `foreignErpId` (`uploadDocument.foreignErpId`; string, optional) — Identifiant du document dans votre système, unique dans l’entreprise.
  - minLength 1; maxLength 255; example `"contrat-salarie-123"`

## Example request

```text
{
  "file": "<file>",
  "fileType": "DPAE",
  "displayFileName": "string",
  "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "foreignErpId": "contrat-salarie-123"
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://api.puncto.fr/public/v1/documents \
  --header 'Authorization: Bearer <token>' \
  --form 'file=@<file>;type=application/octet-stream' \
  --form-string 'fileType=DPAE' \
  --form-string 'displayFileName=string' \
  --form-string 'collaboratorId=coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY' \
  --form-string 'foreignErpId=contrat-salarie-123'
```

### TypeScript

```typescript
import { readFile } from 'node:fs/promises';

const formData = new FormData();
formData.append('file', new Blob([await readFile('<file>')]), '<file>');
formData.append('fileType', 'DPAE');
formData.append('displayFileName', 'string');
formData.append('collaboratorId', 'coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY');
formData.append('foreignErpId', 'contrat-salarie-123');

const url = 'https://api.puncto.fr/public/v1/documents';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}, body: formData};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.puncto.fr/public/v1/documents"

files = [
    ("file", ("<file>", open("<file>", "rb"), "application/octet-stream"))
]
payload = {
    "fileType": "DPAE",
    "displayFileName": "string",
    "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
    "foreignErpId": "contrat-salarie-123"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)
```

## Responses

### 201

Document créé

#### Example

```json
{
  "documentId": "cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "foreignErpId": "string",
  "displayFileName": "string",
  "fileName": "string",
  "fileType": "PAYSLIP",
  "mimeType": "image/jpeg",
  "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "collaboratorForeignErpId": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
```

- `documentId` (`uploadDocument.response.201.documentId`; string, required) — Identifiant Puncto du document
- `foreignErpId` (`uploadDocument.response.201.foreignErpId`; string | null, required) — Identifiant du document dans votre système, renseigné à l'envoi par l'API ; null sinon
- `displayFileName` (`uploadDocument.response.201.displayFileName`; string, required) — Nom du document affiché dans Puncto
- `fileName` (`uploadDocument.response.201.fileName`; string, required) — Nom du fichier téléchargé, extension comprise : le nom du document, suivi de l'extension du fichier s'il ne se termine pas déjà par une extension
- `fileType` (`uploadDocument.response.201.fileType`; string, required) — Type de document
  - one of `"PAYSLIP"`, `"PAYSLIP_ARCHIVED"`, `"DSN_MONTHLY"`, `"DSN_WORK_STOPPAGE"`, `"DSN_WORK_STOPPAGE_RESUMPTION"`, `"DSN_FCTU"`, `"DSN_SADV"`, `"CRM"`, `"EXPENSE_BILL"`, `"MEAL_VOUCHER_EXPORT"`, `"SEPA_PAYROLL"`, `"SEPA_SDTC"`, `"ABSENCE_PROOF"`, `"DPAE"`, `"DPAE_RETURN"`, `"ACCOUNTING_PAYROLL_OD"`, `"ACCOUNTING_PAYROLL_DSN_RECAP"`, `"ACCOUNTING_CONTRIBUTIONS_DETAIL"`, `"ACCOUNTING_CONTRIBUTIONS_RECAP"`, `"ACCOUNTING_PAYBOOK"`, `"ACCOUNTING_PAYROLL_LOG"`, `"ACCOUNTING_REST_RECAP"`, `"IDENTITY"`, `"VITALE"`, `"RIB"`, `"CONTRACT"`, `"INTERNSHIP_AGREEMENT"`, `"INTERNSHIP_CERTIFICATE"`, `"INTERNSHIP_CERTIFICATE_SIGNED"`, `"WORK_CERTIFICATE"`, `"WORK_CERTIFICATE_SIGNED"`, `"FINAL_SETTLEMENT_RECEIPT"`, `"FINAL_SETTLEMENT_RECEIPT_SIGNED"`, `"PROFIT_SHARING_STATEMENT"`, `"ON_CALL_STATEMENT"`, `"PROFIT_SHARING_AGREEMENT_RECEIPT"`, `"BILLING_INVOICE"`, `"COMPANY_SETUP_CHECKLIST"`, `"FCTU_AER"`, `"EXPORT"`, `"ABSENCE_BATCH"`, `"VARIABLE_BATCH"`, `"OC_FICHE"`, `"BPIJ"`, `"SIGNATURE_AUDIT_TRAIL"`, `"OTHER"`
- `mimeType` (`uploadDocument.response.201.mimeType`; any of, required) — Type MIME du fichier, `application/octet-stream` pour un format que Puncto ne connaît pas (docx, xlsx...)
  - any of: `ImageMimeType`, `OtherMimeType`
- `collaboratorId` (`uploadDocument.response.201.collaboratorId`; any of, required) — Collaborateur concerné, null pour un document de l'entreprise
  - any of: `string`, `null`
- `collaboratorForeignErpId` (`uploadDocument.response.201.collaboratorForeignErpId`; string | null, required) — Identifiant du collaborateur dans votre système, null s'il n'a pas été renseigné ou sans collaborateur
- `createdAt` (`uploadDocument.response.201.createdAt`; string, required) — Date d'enregistrement du document dans Puncto
  - format `date-time`
- `updatedAt` (`uploadDocument.response.201.updatedAt`; string, required) — Date de la dernière modification, par exemple le remplacement du fichier par un nouvel envoi
  - format `date-time`

### 401

Clé d’API absente, invalide ou révoquée

#### Example

```json
{
  "error": "Les endpoints de l’API publique sont réservés aux comptes application."
}
```

- `error` (`uploadDocument.response.401.error`; string, required) — Message lisible, en français.
- `errorCode` (`uploadDocument.response.401.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 403

Opération hors de l’accès de la clé d’API

#### Example

```json
{
  "error": "Opération interdite"
}
```

- `error` (`uploadDocument.response.403.error`; string, required) — Message lisible, en français.
- `errorCode` (`uploadDocument.response.403.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 404

Collaborateur introuvable dans l’entreprise

#### Example

```json
{
  "error": "Collaborateur non trouvé"
}
```

- `error` (`uploadDocument.response.404.error`; string, required) — Message lisible, en français.
- `errorCode` (`uploadDocument.response.404.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 409

Un document de l’entreprise porte déjà ce `foreignErpId`

#### Example

```json
{
  "error": "Un document existe déjà avec le foreignErpId \"contrat-salarie-123\"",
  "documentId": "cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
}
```

- `error` (`uploadDocument.response.409.error`; string, required) — Message lisible, en français.
- `documentId` (`uploadDocument.response.409.documentId`; string | null, required) — Identifiant Puncto du document qui porte déjà ce `foreignErpId`.

### 422

Paramètres invalides

#### Example

```json
{
  "errors": [
    {
      "message": "Le champ statut de l’absence doit être une valeur autorisée",
      "rule": "enum",
      "field": "status"
    }
  ]
}
```

- `errors` (`uploadDocument.response.422.errors`; array<object>, required)
  - `message` (`uploadDocument.response.422.errors.message`; string, required)
  - `rule` (`uploadDocument.response.422.errors.rule`; string, required) — Règle de validation en échec.
  - `field` (`uploadDocument.response.422.errors.field`; string, required) — Chemin du champ, par exemple `absences.0.type`.


Source: https://docs.puncto.fr/reference/documents/create/index.md
