API atual/Referência completa/Venddor Intelligence: conversas

Anexos, exportação e planilhas

Converte um arquivo em texto ou imagem para a VI ler, exporta a conversa em DOCX e baixa planilhas geradas pela VI.

O administrador pode anexar uma foto, um PDF ou uma planilha à pergunta. O fluxo tem dois passos: você envia o arquivo para POST /attachments, que valida e converte; depois manda o resultado no corpo de Enviar uma mensagem. O arquivo em si não fica guardado.

Tipos aceitos

Tipo	Extensões	Tamanho máximo	Resultado
Imagem	`.png` `.jpg` `.jpeg` `.webp` `.gif`	20 MB	`kind: image`, `data_url`
Texto	`.txt` `.md` `.json` `.xml` `.csv` `.html` `.htm`	250 KB	`kind: text`, `markdown`
PDF	`.pdf`	5 MB	`kind: text`, `markdown`
Word	`.docx` `.doc`	5 MB	`kind: text`, `markdown`
Planilha	`.xlsx` `.xls`	5 MB	`kind: text`, `markdown`
Apresentação	`.pptx` `.ppt`	10 MB	`kind: text`, `markdown`

Vídeos (.mp4, .mov, .avi, .mkv, .webm e semelhantes) são recusados.

Converter um anexo

Valida o arquivo, converte para o formato que a VI lê e devolve o resultado. Imagens viram um data_url base64; documentos viram Markdown (cortado em 200 KB, com a marca (documento truncado) ao final); textos simples vêm dentro de uma cerca de código.

POST/api/v1/admin/intelligence/attachmentsAdmin

Converter um anexo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Corpo da requisição

filefileobrigatório

O arquivo, em multipart/form-data. Os limites estão na tabela de tipos aceitos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/attachments" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@tabela-de-precos.pdf"

Resposta

200Documento convertido

json

{
  "kind": "text",
  "markdown": "# Tabela de preços\n\n| SKU | Preço |\n|---|---|\n| A1 | 49,90 |",
  "filename": "tabela-de-precos.pdf"
}

200Imagem

json

{ "kind": "image", "data_url": "data:image/png;base64,iVBORw0KGgo...", "filename": "foto.png" }

Campos da resposta

kindstring

imagetext

Tipo do resultado.

data_urlstring

Só em image. Imagem em base64.

markdownstring

Só em text. Conteúdo em Markdown.

filenamestring

Nome recebido.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Não é multipart ou falta o campo `file`.	`{"error":"invalid multipart form"}` ou `{"error":"file field missing"}`
413	Arquivo acima do limite do tipo.	`{"error":"arquivo excede o tamanho máximo permitido"}` (devolvido em português)
415	Extensão não aceita ou vídeo.	`{"error":"tipo de arquivo não suportado"}` ou `{"error":"vídeos não são aceitos"}` (devolvido em português)
422	Arquivo vazio ou ilegível.	`{"error":"não consegui ler esse arquivo"}` (devolvido em português)

Exportar a conversa

Gera um documento Word com a conversa (até as primeiras 500 mensagens) e devolve o arquivo binário. Precisa do recurso de exportação ligado em Configurações (enable_docx_export).

POST/api/v1/admin/intelligence/sessions/{id}/exportAdmin

Exportar a conversa em DOCX

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Parâmetros de consulta

formatstringpadrão: docx

docx

Formato do arquivo. Só existe docx; qualquer outro valor é recusado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/export?format=docx" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivo DOCX

text

Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="conversa.docx"

(bytes do arquivo)

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Formato diferente de `docx`.	`{"error":"intelligence export: unsupported format (expected docx)"}`
403	Exportação desligada na loja.	`{"error":"DOCX export is disabled..."}`
404	Sessão inexistente.	`{"error":"session not found"}`

Baixar uma planilha

Quando o administrador pede "me mande isso em planilha", a VI gera um arquivo .xlsx e coloca o link para esta rota na resposta. O arquivo é de quem pediu (outro administrador recebe 404) e vale por 24 horas.

GET/api/v1/admin/intelligence/planilhas/{id}Admin

Baixar uma planilha gerada

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

idstringobrigatório

Identificador da planilha: 32 caracteres hexadecimais minúsculos, tirado do link na resposta da VI.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/planilhas/$SHEET_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivo XLSX

text

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="produtos.xlsx"

(bytes do arquivo)

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
404	Id fora do formato, arquivo de outro usuário, inexistente ou vencido.	`{"error":"arquivo não encontrado"}`, `{"error":"arquivo não encontrado ou vencido: peça a planilha de novo"}` ou `{"error":"arquivo vencido: peça a planilha de novo"}` (devolvido em português)
500	Falha ao ler o arquivo.	`{"error":"falha ao ler o arquivo"}`

Veja também

API atual/Referência completa/Venddor Intelligence: conversas

Anexos, exportação e planilhas

Converte um arquivo em texto ou imagem para a VI ler, exporta a conversa em DOCX e baixa planilhas geradas pela VI.

Tipos aceitos

Tipo	Extensões	Tamanho máximo	Resultado
Imagem	`.png` `.jpg` `.jpeg` `.webp` `.gif`	20 MB	`kind: image`, `data_url`
Texto	`.txt` `.md` `.json` `.xml` `.csv` `.html` `.htm`	250 KB	`kind: text`, `markdown`
PDF	`.pdf`	5 MB	`kind: text`, `markdown`
Word	`.docx` `.doc`	5 MB	`kind: text`, `markdown`
Planilha	`.xlsx` `.xls`	5 MB	`kind: text`, `markdown`
Apresentação	`.pptx` `.ppt`	10 MB	`kind: text`, `markdown`

Vídeos (.mp4, .mov, .avi, .mkv, .webm e semelhantes) são recusados.

Converter um anexo

POST/api/v1/admin/intelligence/attachmentsAdmin

Converter um anexo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Corpo da requisição

filefileobrigatório

O arquivo, em multipart/form-data. Os limites estão na tabela de tipos aceitos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/attachments" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@tabela-de-precos.pdf"

Resposta

200Documento convertido

json

{
  "kind": "text",
  "markdown": "# Tabela de preços\n\n| SKU | Preço |\n|---|---|\n| A1 | 49,90 |",
  "filename": "tabela-de-precos.pdf"
}

200Imagem

json

{ "kind": "image", "data_url": "data:image/png;base64,iVBORw0KGgo...", "filename": "foto.png" }

Campos da resposta

kindstring

imagetext

Tipo do resultado.

data_urlstring

Só em image. Imagem em base64.

markdownstring

Só em text. Conteúdo em Markdown.

filenamestring

Nome recebido.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Não é multipart ou falta o campo `file`.	`{"error":"invalid multipart form"}` ou `{"error":"file field missing"}`
413	Arquivo acima do limite do tipo.	`{"error":"arquivo excede o tamanho máximo permitido"}` (devolvido em português)
415	Extensão não aceita ou vídeo.	`{"error":"tipo de arquivo não suportado"}` ou `{"error":"vídeos não são aceitos"}` (devolvido em português)
422	Arquivo vazio ou ilegível.	`{"error":"não consegui ler esse arquivo"}` (devolvido em português)

Exportar a conversa

Gera um documento Word com a conversa (até as primeiras 500 mensagens) e devolve o arquivo binário. Precisa do recurso de exportação ligado em Configurações (enable_docx_export).

POST/api/v1/admin/intelligence/sessions/{id}/exportAdmin

Exportar a conversa em DOCX

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Parâmetros de consulta

formatstringpadrão: docx

docx

Formato do arquivo. Só existe docx; qualquer outro valor é recusado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/export?format=docx" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivo DOCX

text

Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="conversa.docx"

(bytes do arquivo)

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Formato diferente de `docx`.	`{"error":"intelligence export: unsupported format (expected docx)"}`
403	Exportação desligada na loja.	`{"error":"DOCX export is disabled..."}`
404	Sessão inexistente.	`{"error":"session not found"}`

Baixar uma planilha

GET/api/v1/admin/intelligence/planilhas/{id}Admin

Baixar uma planilha gerada

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

idstringobrigatório

Identificador da planilha: 32 caracteres hexadecimais minúsculos, tirado do link na resposta da VI.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/planilhas/$SHEET_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivo XLSX

text

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="produtos.xlsx"

(bytes do arquivo)

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
404	Id fora do formato, arquivo de outro usuário, inexistente ou vencido.	`{"error":"arquivo não encontrado"}`, `{"error":"arquivo não encontrado ou vencido: peça a planilha de novo"}` ou `{"error":"arquivo vencido: peça a planilha de novo"}` (devolvido em português)
500	Falha ao ler o arquivo.	`{"error":"falha ao ler o arquivo"}`