# General Translation Platform: Caricare file sorgente
URL: https://generaltranslation.com/it/docs/platform/openapi/reference/files/upload-source.mdx
---

title: Caricare file sorgente
description: Carica uno o più file sorgente in un progetto di General Translation prima di metterli in coda per la traduzione. Riferimento API per Caricare file sorgente.

method: POST
---

Carica i file sorgente in un progetto in modo che possano essere messi in coda per la traduzione. Invia il contenuto dei file in formato base64, da 1 a 100 file per richiesta.

## Panoramica [#overview]

```http
POST https://api2.gtx.dev/v2/project/files/upload-files
```

**Permesso** `project:files:write` · **Limite di richieste** Medio (120/min)

Carica i file sorgente (non tradotti) di un progetto. Per caricare file già tradotti, usa [Carica traduzioni](/docs/platform/openapi/reference/files/upload-translations). Per tradurre i file caricati, vedi [Metti in coda le traduzioni](/docs/platform/openapi/reference/translation/queue).

## Come funziona [#how-it-works]

* Il `content` di ogni file viene codificato in base64 e decodificato lato server; il base64 non valido viene rifiutato.
* Se `fileId` non è specificato, viene ricavato calcolando l'hash di `fileName`; se `versionId` non è specificato, viene ricavato calcolando l'hash del contenuto del file, quindi ricaricare contenuti identici è idempotente per versione.
* I file vengono associati al branch predefinito, a meno che non venga fornito un `branchId` valido. Un `branchId` sconosciuto restituisce `400`.
* Se viene inviato `sourceLocale` ed è diverso dall'impostazione regionale predefinita corrente del progetto, l'impostazione regionale predefinita del progetto viene aggiornata.

## Richiesta [#request]

### Header

| Header            | Descrizione                                                                 | Obbligatorio |
| ----------------- | --------------------------------------------------------------------------- | ------------ |
| `x-gt-api-key`    | Chiave API del progetto o dell'organizzazione.                          | Sì           |
| `x-gt-project-id` | ID progetto. Obbligatorio quando si usa una chiave dell'organizzazione. | No           |

### Corpo

**Tipo di contenuto** `application/json`

| Campo           | Descrizione                                        | Tipo       | Facoltativo | Predefinito                                     |
| --------------- | -------------------------------------------------- | ---------- | ----------- | ----------------------------------------------- |
| [`data`](#data) | Array di file da caricare (1–100).                 | `object[]` | No          | —                                               |
| `sourceLocale`  | Impostazione regionale sorgente dei file caricati. | `string`   | Sì          | Impostazione regionale predefinita del progetto |

#### `data` [#data]

**Tipo** `object[]` · **Obbligatorio**

Ogni elemento è `{ "source": { ... } }`, dove `source` ha i seguenti campi:

| Campo            | Descrizione                                                                                   | Tipo     | Facoltativo | Predefinito        |
| ---------------- | --------------------------------------------------------------------------------------------- | -------- | ----------- | ------------------ |
| `content`        | Contenuto del file codificato in Base64. Si applica il limite massimo di dimensione del file. | `string` | No          | —                  |
| `fileName`       | Nome del file; non può essere vuoto.                                                          | `string` | No          | —                  |
| `fileFormat`     | Identificatore del formato del file (ad esempio, `JSON`, `MDX`).                              | `string` | No          | —                  |
| `locale`         | Impostazione regionale del contenuto sorgente; non può essere vuota.                          | `string` | No          | —                  |
| `dataFormat`     | Formato dei dati per il contenuto strutturato.                                                | `string` | Sì          | —                  |
| `fileId`         | Identificatore stabile del file.                                                              | `string` | Sì          | Hash di `fileName` |
| `versionId`      | Identificatore della versione di questo contenuto.                                            | `string` | Sì          | Hash del contenuto |
| `branchId`       | Branch a cui associare il file.                                                               | `string` | Sì          | Branch predefinito |
| `formatMetadata` | Metadati aggiuntivi specifici del formato.                                                    | `object` | Sì          | —                  |

## Risposta [#response]

**Stato** `201 Created`

```json title="Response"
{
  "uploadedFiles": [
    {
      "branchId": "br_...",
      "fileId": "file_...",
      "versionId": "ver_...",
      "fileName": "en/common.json",
      "fileFormat": "JSON",
      "dataFormat": "JSON"
    }
  ],
  "count": 1,
  "message": "Successfully uploaded 1 source file(s)"
}
```

## Errori [#errors]

| Stato | Causa                                                                                                                                           |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Corpo della richiesta non valido, impostazione regionale/formato non validi, errore di decodifica, file troppo grande o `branchId` sconosciuto. |
| `401` | Chiave API mancante o non valida.                                                                                                               |
| `403` | La chiave API non dispone di `project:files:write`.                                                                                             |
| `429` | Limite di richieste superato.                                                                                                                   |
| `503` | Server occupato; riprova con backoff.                                                                                                           |

## Esempio [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/files/upload-files \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLocale": "en",
    "data": [
      {
        "source": {
          "content": "eyJoZWxsbyI6ICJIZWxsbyJ9",
          "fileName": "en/common.json",
          "fileFormat": "JSON",
          "locale": "en"
        }
      }
    ]
  }'
```