# Anexar ficheiros ## 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: | URL applicação | API\_URL | UPLOAD\_URL | | ---------------------------- | -------------------------------------- | -------------------------------------- | | app1.business-pt.cegid.cloud | | | | app2.business-pt.cegid.cloud | | | | app3.business-pt.cegid.cloud | | | Para utilizar os exemplos deste guia sugerimos exportar a configuração para variáveis de shell, por exemplo para o serviço Cegid Cloudware Business, depois obter um token de acesso definir as seguintes variáveis. ``` export API_URL="" export UPLOAD_URL="" 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. {% hint style="success" %} 200 Ficheiro transferido com sucesso (Content-Type: application/json) ```bash { "file": "2021-02-20/MekIAU.ul" } ``` {% endhint %} {% hint style="info" %} Para usar este identificador no exemplo do passo 2 coloque-o na variavel TEMP\_FILE ```bash export TEMP_FILE="2021-02-20/MekIAU.ul" ``` {% endhint %} #### #### Respostas de erro {% hint style="warning" %} 413 Ficheiro excede o limite de 50 MB, resposta (Content-Type: text/html) ```bash curl -X 'POST' ${UPLOAD_URL} \ -H "Content-Type: application/octet-stream" \ -H "Content-Disposition: attachment" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -F "data=@lixo.pdf" 413 Request Entity Too Large

413 Request Entity Too Large

nginx/1.16.1 ``` {% endhint %} {% hint style="warning" %} 401 Token de acesso não é válido (Content-Type: text/html) ```bash curl -X 'POST' ${UPLOAD_URL} \ -H "Content-Type: application/octet-stream" \ -H "Content-Disposition: attachment" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -F "data=@teste.pdf" 401 Authorization Required

401 Authorization Required

nginx/1.16.1 ``` {% endhint %} ### 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: ```bash { "data": { "type": "attachment", "attributes": { "file": , "file_name": , "file_type": } } } ``` 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. {% hint style="warning" %} 413 A empresa não tem espaço disponível, será necessário comprar mais espaço arquivo (Content-Type: application/json) ```bash { "errors": [ { "status": "413", "code": "JA000", "detail": "Excedeu o limite de espaço do seu arquivo digital" } ] } ``` {% endhint %} {% hint style="warning" %} 401 A empresa não tem o módulo de arquivo digital activado ou utilizador da sessão não tem permissão para aceder (Content-Type: application/json) ```bash { "errors": [ { "code": "FORBIDDEN_BY_GATEKEEPER", "detail": "", "meta": { "internal-error": { "method": "POST", "path": "/attachments/purchases_documents/944306", "why": "Access denied by rule at index 120." } }, "status": "401 - Access Denied" } ] } ``` {% endhint %} {% hint style="warning" %} 400 Pedido inválido (Content-Type: application/json) ```bash { "errors": [ { "status": "400", "code": "JA000", "detail": "mandatory 'file_name' attribute not supplied" } ] } ``` {% endhint %} ## 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 ```bash 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}" ``` {% hint style="success" %} 200 Resposta de sucesso ```bash { "data": { "type": "attachment", "id": "0", "attributes": { "updated": true, "detach_response": { "data": { "type": "detach_from_entity", "id": "cQTLsWZCu" } } } } } ``` {% endhint %}