Anexar ficheiros

Guia prático que explica como anexar ficheiros a documentos

Anexar ficheiro a um documento

O processo é realizado em dois passos. No primeiro o ficheiro é transferido para o servidor de uploads para uma área temporária. No segundo passo a API é utilizada para estabelecer a associação ao documento sendo então o ficheiro arquivado definitivamente.

A tabela apresenta os URL de API e UPLOAD em função do serviço:

Para utilizar os exemplos deste guia sugerimos exportar a configuração para variáveis de shell, por exemplo para o serviço Cloudware Business, depois obter um token de acesso definir as seguintes variáveis.

export API_URL="https://api-cwb.cldware.com"
export UPLOAD_URL="https://upload-cwb-opo.cldware.com/upload"
export ACCESS_TOKEN="1-42-104-e17d72a5254029bc41d9b3c65795008cdf00278f1151cf31527fe3d3548335dd"

1º Passo transferir ficheiro para o servidor de arquivo

Neste passo o ficheiro é transferido para uma área temporária no servidor de ficheiros, o método devolve o caminho para um ficheiro único temporário que será mantido durante sete dias.

curl -X 'POST' ${UPLOAD_URL} \
-H "Content-Type: application/octet-stream" \
-H "Content-Disposition: attachment" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
--data-binary @teste.pdf

Resposta de sucesso

O servidor de ficheiros retorna no atributo file o identificador do ficheiro temporário que será utilizado no próximo passo.

Para usar este identificador no exemplo do passo 2 coloque-o na variavel TEMP_FILE

export TEMP_FILE="2021-02-20/MekIAU.ul"

Respostas de erro

2º Passo associar ficheiro ao documento

A API disponibiliza três rotas para associar anexos documentos:

  • /api/attachments/purchases_documents/:document_id - para associar a facturas de compra

  • /api/attachments/documents/:document_id - para associar a facturas de venda

  • /api/attachments/receipts/:document_id - para associar a recibos

Estas rotas aceitam pedidos POST com o seguinte body:

{
  "data": {
    "type": "attachment",
    "attributes": {
      "file": <nome do ficheiro temporário obtido no 1º passo>,
      "file_name": <nome com que o ficheiro será arquivado e exibido ao utilizador>,
      "file_type": <application/pdf ou image/jpeg ou image/png>
    }
  }
}

Exemplo de pedido para factura de compra, para executar definir TEMP_FILE com valor obtido no 1º passo e DOCUMENT_ID com o identificador de uma fatura de compra da empresa.

Remover anexo do documento

Para remover um anexo enviar um pedido DELETE para a rota

  • /api/attachments/:documenttype/:documentid/:archiveid em que o archive_id é valor retornado no 2º passo

Exemplo de comando para remover o anexo inserido no passo 2

curl -X 'DELETE' ${API_URL}/api/attachments/purchases_documents/${DOCUMENT_ID}/${ARCHIVE_ID} \
 -H "Content-Type: application/vnd.api+json" \
 -H "Authorization: bearer ${ACCESS_TOKEN}" 

Last updated