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

# Upload asset

> Envia um ficheiro para um chat e obtém uma URL CDN permanente

Envia um ficheiro para os Recursos de um chat e devolve uma URL CDN permanente. Usa este endpoint para imagens, documentos, áudio, vídeo ou qualquer outro ficheiro que queiras que a tua app ou processamento referencie por URL.

## Pedido

```
POST /api/client-app/assets/upload
```

### Cabeçalhos

| Cabeçalho | Obrigatório | Descrição |
| - | - | - |
| `Authorization` | Sim | `Bearer macaly_...` |
| `Content-Type` | Sim | `multipart/form-data` |

### Parâmetros do formulário

| Campo | Tipo | Obrigatório | Predefinição | Descrição |
| - | - | - | - | - |
| `chatId` | string | Sim | - | O chat para o qual enviar o recurso |
| `file` | file | Sim | - | O ficheiro a enviar. Tamanho máximo 20 MB |
| `folderPath` | string | Não | - | Caminho de pasta separado por barras, por exemplo `images/products` |
| `createFolders` | string | Não | `false` | `"true"`, `"1"` ou `"yes"` cria as pastas em falta em `folderPath` |
| `folderId` | string | Não | - | ID de uma pasta existente. Não envies `folderId` e `folderPath` em simultâneo |
| `title` | string | Não | Nome original do ficheiro | Título de apresentação do recurso |
| `metadata` | string (JSON) | Não | - | Objeto JSON guardado junto do recurso |

<Note>
  Fornece `folderId` ou `folderPath`, não ambos. Enviar os dois devolve um erro 400.
</Note>

### Exemplo de pedido

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.macaly.com/api/client-app/assets/upload \
    -H "Authorization: Bearer macaly_abc123..." \
    -F "chatId=abc123def456" \
    -F "file=@./logo.png;type=image/png"
  ```

  ```javascript JavaScript theme={null}
  const form = new FormData();
  form.append('chatId', 'abc123def456');
  form.append('file', fileBlob, 'logo.png');

  const response = await fetch('https://www.macaly.com/api/client-app/assets/upload', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer macaly_abc123...',
    },
    body: form,
  });

  const data = await response.json();
  console.log(data.asset.url);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://www.macaly.com/api/client-app/assets/upload',
      headers={'Authorization': 'Bearer macaly_abc123...'},
      data={'chatId': 'abc123def456'},
      files={'file': ('logo.png', open('logo.png', 'rb'), 'image/png')},
  )

  data = response.json()
  print(data['asset']['url'])
  ```
</CodeGroup>

### Enviar para uma pasta

Usa `folderPath` para uma estrutura de pastas legível e define `createFolders=true` para criar as pastas em falta ao longo do caminho:

```bash cURL theme={null}
curl -X POST https://www.macaly.com/api/client-app/assets/upload \
  -H "Authorization: Bearer macaly_abc123..." \
  -F "chatId=abc123def456" \
  -F "folderPath=images/products" \
  -F "createFolders=true" \
  -F "title=Product hero image" \
  -F "file=@./hero.png;type=image/png"
```

## Resposta

```json theme={null}
{
  "success": true,
  "asset": {
    "assetId": "asset_123",
    "url": "https://cdn.macaly.app/user/chat/key/logo.png",
    "storageKey": "user/chat/key/logo.png",
    "contentType": "image/png",
    "fileSize": 12345,
    "type": "image",
    "folderId": "folder_123"
  }
}
```

| Campo | Tipo | Descrição |
| - | - | - |
| `asset.assetId` | string | Identificador único do recurso |
| `asset.url` | string | URL CDN permanente do ficheiro enviado |
| `asset.storageKey` | string | Caminho de armazenamento interno |
| `asset.contentType` | string | Tipo MIME do ficheiro enviado |
| `asset.fileSize` | number | Tamanho do ficheiro em bytes |
| `asset.type` | string | Tipo de recurso inferido, por exemplo `image`, `document` |
| `asset.folderId` | string \| null | Pasta onde o recurso foi colocado, se aplicável |

## Códigos de estado

| Estado | Descrição |
| - | - |
| 200 | Sucesso: recurso enviado |
| 400 | `chatId` ou `file` em falta, JSON de `metadata` inválido, ou `folderId` e `folderPath` fornecidos em simultâneo |
| 401 | Chave API inválida ou em falta |
| 403 | A chave API não tem acesso a este chat |
| 404 | Pasta não encontrada |
| 413 | O ficheiro excede o limite de envio de 20 MB |
| 500 | Erro do servidor |

## Regras das pastas

* Os caminhos de pasta são divididos por `/`, com espaços removidos, e os segmentos vazios são ignorados.
* A profundidade máxima é de 8 pastas.
* Cada nome de pasta pode ter até 255 caracteres.
* A correspondência de pastas não distingue maiúsculas de minúsculas dentro do mesmo diretório principal.
* Se `folderPath` não existir e `createFolders` não for `true`, o envio falha com um erro 404.

## É bom saber

* Este endpoint usa a mesma chave API `macaly_...` que o resto da API, apesar de a URL começar com `/api/client-app/`. Não é necessário um token separado.
* O chat referenciado por `chatId` tem de pertencer à mesma equipa que a tua chave API.
* Os recursos enviados obtêm uma URL CDN permanente que podes referenciar em [Create chat](/docs/pt/api/create-chat) ou [Publish message](/docs/pt/api/publish-message) como anexo, ou usar em qualquer lugar fora da Macaly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.