Central de ajudaIntegrações

Para: Administradores

Faça upload e anexe arquivos com uma chave de hub.

Obtenha um endereço de upload, carregue um arquivo, anexe-o a uma publicação, nota, tarefa, formulário ou assinatura eletrônica e baixe os arquivos de um caso.

Neste artigo10 seções

Antes de começar

Esta página explica como carregar arquivos para um caso, como anexá-los e como baixá-los, utilizando uma chave de hub. Os caminhos estão localizados abaixo de https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

Como funciona

O arquivo realiza três etapas: primeiro, solicita um endereço para o upload do arquivo; em seguida, o arquivo é carregado nesse endereço; por fim, o arquivo é anexado ao item em questão.

ItemEndereço para uploadAnexarRemover
Uma publicação/artigoGET /posts/<post_id>/drivePUT /posts/<post_id>/mediaDELETE /posts/<post_id>/media
Uma nota/observaçãoGET /notes/<note_id>/drivePUT /notes/<note_id>/mediaDELETE /notes/<note_id>/media
Uma tarefaGET /tasks/<task_id>/drivePUT /tasks/<task_id>/mediaDELETE /tasks/<task_id>/media
Uma tarefa infantilGET /subtasks/<subtask_id>/drivePUT /subtasks/<subtask_id>/mediaDELETE /subtasks/<subtask_id>/media
Documento em formato digital, assinado ou emitido por meio de tecnologia eletrônica.GET /<forms, signs or notes>/<id>/drive com media_group=schemasPUT /<forms, signs or notes>/<id>/schema/media—
  • Uma chave só pode anexar arquivos às postagens criadas pelo Assistente Virtual. Ela também pode anexar arquivos a qualquer nota, tarefa ou tarefa subordinada.
  • Para anexar um arquivo a um comentário, peça o endereço correspondente ao comentário em questão, usando o tag /drive. Depois, utilize o tag PUT /<posts, signs, tasks or subtasks>/<id>/comments/<comment_id>/media para anexar o arquivo ao comentário. Um chave só pode ser anexado aos próprios comentários.
  • Uma forma ou assinatura eletrônica contém apenas um documento, e nenhum outro arquivo. Uma vez que o documento é convertido, ela não precisa mais de outro arquivo, a menos que o primeiro não tenha sido convertido com sucesso.

1. Obtenha um endereço de upload

ParâmetroO que fazObrigatórioPadrão
media_groupO tipo de arquivo é: docs, images, audios, videos ou files. Para documentos relacionados a formulários, assinaturas eletrônicas ou notas, o tipo de arquivo pode ser schemas.Sim—
media_extensionA extensão do arquivo é, por exemplo, pdf. Ela deve ser uma das extensões permitidas; files permite qualquer extensão.Sim—
tag_idO nome do arquivo é salvado em letras, números e hífenes, como por exemplo: repair-estimateSim—
TipoExtensões
docs e schemascsv, doc, docx, odt, pdf, ppt, pptx, rtf, txt, xls, xlsx
imagesBMP, GIF, JPEG, JPG, PNG, SVG, TIFF, WebP
audiosaac, aiff, amr, flac, m4a, mp3, oga, opus, wav, wma… E também formatos de áudio menos comuns.
videosFormatos de vídeo menos comuns: 3GP, AVI, FLV, M4V, MKV, MOV, MP4, MPEG, MPG, OGG, WebM, WMV.
filesQualquer coisa
curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ele responde a url, que é o endereço para o qual o arquivo será enviado, e a fields, que indica os campos do formulário que serão enviados junto com o arquivo. fields.key é onde o arquivo será salvo. O endereço funciona por uma hora.

2. Faça o upload do arquivo

Envie um multipart/form-data Envie por POST. url, com cada entrada em fields Portanto, o arquivo que está no final da lista é o último. file. fields Contém um espaço vazio. Content-Type: Preencha-o com o tipo de arquivo, como por exemplo: application/pdf, Em vez de enviar um segundo chamado, essa chamada é direcionada para o armazenamento de arquivos, e não para a API. Portanto, não é necessário fornecer uma chave para esse chamado.

curl -X POST "<url>" \
  --form-string "key=<fields.key>" \
  --form-string "Content-Type=application/pdf" \
  --form-string "<every other entry of fields, as given>" \
  -F "file=@repair-estimate.pdf"

Envie os itens de fields com --form-string, e não com -F. Alguns dos itens começam com <. O -F é interpretado como um arquivo.

Isso responde à pergunta 201. O arquivo mais grande é o limite estabelecido para o papel do Assistente Virtual nesse tipo de arquivo: 5.000 MB, por padrão. Um administrador pode reduzir esse valor nas configurações › Roles. Arquivos que excederem esse limite serão rejeitados pelo armazenamento de arquivos. Arquivos enviados sem nunca serem anexados são apagados após três dias.

3. Anexe-o

curl -X PUT https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media": [{"media_key": "<fields.key>"}]}'
{
  "data": {
    "items": [{"media_key": "hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf", "media_id": "20261002154512_5f4e3d2c1b0a99"}],
    "currentItemCount": 1
  }
}
  • media aceita vários arquivos de uma só vez. Cada um deles deve ter sido carregado com um endereço relacionado ao mesmo item.
  • A função de “anexar arquivos” serve apenas para adicioná-los ao sistema; ela nunca substitui os arquivos existentes.
  • Em uma publicação, você pode anexar seus webhooks. add_post_media Para cada arquivo, a mensagem de e-mail sobre a publicação conta os arquivos relacionados a esse arquivo.

Após anexar

Os arquivos são processados após a sua anexação: as imagens são redimensionadas, o áudio e o vídeo são preparados para reprodução, e os documentos são convertidos em formato PDF, com as imagens das páginas incluídas. Os arquivos do tipo files são mantidos como estão.

Cada item lido, como GET /posts/<post_id>, lista seus arquivos sob media.<kind>.items.<media_id>.

CampoO que contém
execution_statusRUNNING Enquanto está sendo processado… SUCCEEDED ou FAILED
originalO arquivo foi carregado.
pdfO documento, após ser convertido para formato PDF, está pronto.
flatUma cópia eletrônica bloqueada, uma vez que todos tenham assinado.
tag_id, content_type, media_sizeSeu nome, tipo e tamanho em bytes

Enquanto qualquer arquivo estiver sendo processado, a informação relacionada ao mesmo é exibida no campo encoding. Um formulário ou documento digital não pode ser publicado até que o documento esteja pronto.

Baixando um arquivo

Baixe um arquivo a partir de https://privcdn.caseactive.com/, seguido pelo seu original, pdf ou flat. Use sua chave no mesmo cabeçalho utilizado em cada chamada ao arquivo.

curl "https://privcdn.caseactive.com/hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" -o repair-estimate.pdf

Os verificações relacionados à chave são aplicados, assim como em todas as chamadas. O intervalo de endereços IP também é verificado. Além disso, a assistente virtual pode baixar informações de qualquer local onde ela possa encontrar essas informações.

Remover um arquivo

DELETE /<item>/media aceita um corpo JSON contendo os valores media_id e media_group, e retorna o valor 200. Em um post, os webhooks recebem o valor delete_post_media. Os documentos criados por formulários, assinaturas digitais ou notas não podem ser excluídos; é necessário excluir o item em questão.

Exemplo: um PDF em uma nova postagem

  1. POST /posts Com o post… message. O arquivo é postado imediatamente, com uma notificação no portal. O e-mail é enviado cerca de 30 segundos depois, e nesse período, os arquivos anexados são contados. Portanto, anexe-os dentro desse tempo.
  2. GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate.
  3. Carregue o arquivo em url, com o nome fields.
  4. Com PUT /posts/<post_id>/media e fields.key.
  5. Leia o arquivo GET /posts/<post_id> até que o valor de execution_status atinja os valores SUCCEEDED ou FAILED.

Se uma chamada for recusada

StatusmessagePor que
400SchemaFieldsExceptionO parâmetro está faltando ou é inválido. Por exemplo, pode haver um tipo de extensão que não é aceito, ou um campo tag_id com espaços entre as letras; o campo errors contém o nome do arquivo a ser carregado. Em media.<n>.media_key, o arquivo não foi encontrado; provavelmente se referia a outro item. Em /schema/media, o arquivo não foi carregado como schemas. Isso também acontece quando o item que você está tentando anexar não existe. Nada foi anexado na solicitação.
403ItemUpdateFailedExceptionO arquivo já está anexado, ou seja, o formulário, a assinatura eletrônica ou a nota já contêm o documento necessário.
403ItemAuthorOnlyExceptionA pessoa tentou anexar um arquivo a uma publicação ou comentário escrito por outra pessoa.
403CaseClosedExceptionO caso foi encerrado.
404ItemNotFoundExceptionO item não existe quando você tenta obter o endereço para fazer o upload do arquivo, ou quando o arquivo a ser removido também não existe.

O processo de upload é realizado no formato próprio do armazenamento de arquivos: EntityTooLarge para arquivos que excedem o limite permitido, e AccessDenied quando o endereço expirou. Quanto ao corpo de erro da API e aos demais códigos, consulte Lidar com erros e códigos de status da API.

Artigos relacionados

Entenda o que a API pode fazer.Saiba o que uma chave de gerenciamento e uma chave central podem fazer, por que cada chave funciona como um Assistente Virtual e onde encontrar a lista completa de especificações técnicas.IntegraçõesAdicione publicações e comentários com uma chave central.Como Assistente Virtual, você pode adicionar publicações ao feed de um caso, responder com comentários e ler, editar ou excluir essas publicações diretamente do seu software.IntegraçõesEnvie assinaturas eletrônicas e leia assinaturas com uma chave central.Crie uma solicitação de assinatura eletrônica para um caso a partir de um modelo, escolha quem assina cada campo, publique-a para assinatura e baixe a cópia bloqueada assim que todos tiverem assinado.IntegraçõesLidar com erros e códigos de status da APILeia o corpo da mensagem de erro, o que significam os códigos 400, 401, 403, 404, 500 e 503 e por que um item que sua chave não consegue ver responde ao erro 404.Integrações