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

# Criar documento

> Adicionar um novo documento a uma base de conhecimento

Este endpoint cria um novo documento em uma base de conhecimento. Os documentos são processados de forma assíncrona - o endpoint retorna imediatamente enquanto o processamento continua em segundo plano.

### Parâmetros de Caminho

<ParamField path="knowledgebaseId" type="integer" required>
  O identificador único da base de conhecimento
</ParamField>

### Corpo da Requisição

<ParamField body="name" type="string" required>
  O nome do documento (máx. 255 caracteres)
</ParamField>

<ParamField body="description" type="string">
  Descrição opcional do documento (máx. 255 caracteres)
</ParamField>

<ParamField body="type" type="string" required>
  Tipo de documento: `website`, `pdf`, `txt` ou `docx`
</ParamField>

#### Documentos de Website

<ParamField body="url" type="string">
  A URL principal para fazer scraping. Obrigatório se `links` não for fornecido.
</ParamField>

<ParamField body="links" type="array">
  Array de URLs específicas para fazer scraping. Obrigatório se `url` não for fornecido.

  <Expandable title="links properties">
    <ParamField body="link" type="string" required>
      Uma URL válida para incluir no documento
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="relative_links_limit" type="integer" default="10">
  Número máximo de links relativos a seguir durante o scraping (1-50)
</ParamField>

#### Documentos de Arquivo (PDF, TXT, DOCX)

<ParamField body="file" type="file" required>
  O arquivo para upload (máx. 20MB). Use codificação `multipart/form-data`.
</ParamField>

### Resposta

<ResponseField name="message" type="string">
  Mensagem de sucesso
</ResponseField>

<ResponseField name="data" type="object">
  O objeto de documento criado

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      O identificador único do documento
    </ResponseField>

    <ResponseField name="name" type="string">
      O nome do documento
    </ResponseField>

    <ResponseField name="description" type="string">
      Descrição do documento
    </ResponseField>

    <ResponseField name="type" type="string">
      Tipo de documento
    </ResponseField>

    <ResponseField name="type_label" type="string">
      Rótulo de tipo legível para humanos
    </ResponseField>

    <ResponseField name="status" type="string">
      Status de processamento (será `processing` inicialmente)
    </ResponseField>

    <ResponseField name="status_label" type="string">
      Rótulo de status legível para humanos
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp ISO 8601 da criação
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Website Document Created theme={null}
  {
    "message": "Documento criado com sucesso. O processamento começará em breve.",
    "data": {
      "id": 1,
      "name": "Website da Empresa",
      "description": "Conteúdo do website principal",
      "type": "website",
      "type_label": "Website",
      "status": "processing",
      "status_label": "Processando",
      "created_at": "2025-01-08T10:30:00.000000Z"
    }
  }
  ```

  ```json 201 PDF Document Created theme={null}
  {
    "message": "Documento criado com sucesso. O processamento começará em breve.",
    "data": {
      "id": 2,
      "name": "Manual do Produto",
      "description": "Guia do usuário para nosso produto",
      "type": "pdf",
      "type_label": "PDF",
      "status": "processing",
      "status_label": "Processando",
      "created_at": "2025-01-08T10:35:00.000000Z"
    }
  }
  ```

  ```json 404 Knowledgebase Not Found theme={null}
  {
    "error": "Base de conhecimento não encontrada."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Um arquivo é obrigatório para este tipo de documento.",
    "errors": {
      "file": [
        "Um arquivo é obrigatório para este tipo de documento."
      ]
    }
  }
  ```

  ```json 500 Processing Error theme={null}
  {
    "error": "Falha ao criar documento. Tente novamente."
  }
  ```
</ResponseExample>

### Tipos de Documento

| Tipo      | Descrição                                              | Entrada                |
| --------- | ------------------------------------------------------ | ---------------------- |
| `website` | Faz scraping de páginas web e extrai conteúdo de texto | URL ou lista de URLs   |
| `pdf`     | Extrai texto de arquivos PDF                           | Upload de arquivo PDF  |
| `txt`     | Conteúdo de texto simples                              | Upload de arquivo TXT  |
| `docx`    | Extrai texto de documentos Word                        | Upload de arquivo DOCX |

### Exemplo: Criando um Documento de Website

```bash theme={null}
curl -X POST https://suasofia.online/api/user/knowledgebases/1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website da Empresa",
    "description": "Conteúdo do website principal",
    "type": "website",
    "url": "https://example.com",
    "relative_links_limit": 20
  }'
```

### Exemplo: Fazendo Upload de um Documento PDF

```bash theme={null}
curl -X POST https://suasofia.online/api/user/knowledgebases/1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=Manual do Produto" \
  -F "description=Guia do usuário para nosso produto" \
  -F "type=pdf" \
  -F "file=@/caminho/para/documento.pdf"
```

<Note>
  O processamento de documentos é assíncrono. Consulte o endpoint [get document](/api-reference/knowledgebases/get-document) para verificar quando o processamento estiver completo.
</Note>