Anexar ficheiros
Guia prático que explica como anexar ficheiros a documentos
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 | API_URL |
|---|---|---|
app.cloudware.pt | ||
app<1-6>.toconline.pt | ||
app<7-12>.toconline.pt | ||
| | |
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"
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
O servidor de ficheiros retorna no atributo
file o identificador do ficheiro temporário que será utilizado no próximo passo.200 Ficheiro transferido com sucesso (Content-Type: application/json)
{
"file": "2021-02-20/MekIAU.ul"
}
Para usar este identificador no exemplo do passo 2 coloque-o na variavel TEMP_FILE
export TEMP_FILE="2021-02-20/MekIAU.ul"
413 Ficheiro excede o limite de 50 MB, resposta (Content-Type: text/html)
curl -X 'POST' ${UPLOAD_URL} \
-H "Content-Type: application/octet-stream" \
-H "Content-Disposition: attachment" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-F "[email protected]"
<html>
<head><title>413 Request Entity Too Large</title></head>
<body>
<center><h1>413 Request Entity Too Large</h1></center>
<hr><center>nginx/1.16.1</center>
</body>
</html>
401 Token de acesso não é válido (Content-Type: text/html)
curl -X 'POST' ${UPLOAD_URL} \
-H "Content-Type: application/octet-stream" \
-H "Content-Disposition: attachment" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-F "[email protected]"
<html>
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>nginx/1.16.1</center>
</body>
</html>
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.
413 A empresa não tem espaço disponível, será necessário comprar mais espaço arquivo (Content-Type: application/json)
{
"errors": [
{
"status": "413",
"code": "JA000",
"detail": "Excedeu o limite de espaço do seu arquivo digital"
}
]
}
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)
{
"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"
}
]
}
400 Pedido inválido (Content-Type: application/json)
{
"errors": [
{
"status": "400",
"code": "JA000",
"detail": "mandatory 'file_name' attribute not supplied"
}
]
}
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}"
200 Resposta de sucesso
{
"data": {
"type": "attachment",
"id": "0",
"attributes": {
"updated": true,
"detach_response": {
"data": {
"type": "detach_from_entity",
"id": "cQTLsWZCu"
}
}
}
}
}
Last modified 8mo ago