Pular para o conteúdo principal

List company documents

GET 
/company/documents

Obtém uma lista paginada de todos os documentos associados à empresa do utilizador autenticado.

Fluxo de operação:​

  1. Autenticação via JWT válido com função de gestor ou superior
  2. Validação dos parâmetros de paginação
  3. Filtragem opcional por tipo de documento
  4. Consulta paginada à base de dados (apenas a última versão de cada documento)
  5. Retorno dos documentos com metadados e caminhos dos ficheiros

Requisitos de acesso:​

  • Autenticação: Token JWT válido (Bearer token)
  • Função mínima: Gestor da empresa (isGestor)
  • Permissões: Acesso apenas aos documentos da própria empresa

Casos de uso típicos:​

  • Consultar faturas e contratos da empresa
  • Filtrar documentos por categoria (documentType)
  • Revisar o estado de aprovação de documentos pendentes
  • Aceder ao histórico de versões recentes

Estados do documento:​

  • pending: Pendente de revisão pela administração
  • approved: Aprovado e disponível para utilização
  • rejected: Rejeitado com motivo especificado

Considerações importantes:​

  • Apenas devolve a última versão de cada documento (exclui versões obsoletas com newVersion: null)
  • Todos os timestamps estão no formato UTC
  • Máximo de 100 documentos por página
  • Ordenação por data de criação descendente (mais recentes primeiro)
  • Os ficheiros são armazenados em S3/MinIO com caminhos relativos em filePaths

Exemplo de solicitação:​

GET /company/documents?page=1&limit=25&documentType=648ac82b769e704acd2c73f5
Authorization: Bearer {token}

Exemplo de resposta bem-sucedida:​

\{
  docs: [
    \{
      _id: 5f8d3b7a9c2d1e0f4a6b5c4d,
      name: Fatura Q1 2023,
      status: approved,
      documentType: 5f

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"page","in":"query","description":"Número da página para navegação em resultados paginados.\nÚtil para dividir a exibição quando há muitos documentos.","required":false,"example":1,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Quantidade máxima de documentos a retornar por página.\nPermite equilibrar desempenho (valores baixos) vs conveniência (valores altos).","required":false,"example":25,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"documentType","in":"query","description":"Filtre documentos por tipo específico usando seu ID do MongoDB.\nOs tipos disponíveis são obtidos do endpoint /documents/types.\nÚtil para mostrar apenas faturas, contratos ou outras categorias.","required":false,"example":"648ac82b769e704acd2c73f5","schema":{"type":"string","format":"ObjectId","pattern":"^[a-f0-9]{24}$"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Lista de documentos obtida com sucesso","content":{"application/json":{"schema":{"type":"object","description":"Resposta paginada com lista de documentos da empresa","properties":{"docs":{"type":"array","description":"Lista de documentos da página atual","items":{"type":"object","description":"Representa um documento corporativo com seus metadados.","properties":{"_id":{"type":"string","description":"Identificador único do documento (MongoDB ObjectId)","format":"ObjectId","pattern":"^[a-f0-9]{24}$","example":"5f8d3b7a9c2d1e0f4a6b5c4d"},"name":{"type":"string","description":"Nome descritivo do documento","minLength":3,"maxLength":100,"example":"Factura Q1 2023"},"status":{"type":"string","description":"Status de aprovação do documento","enum":["pending","approved","rejected"],"example":"approved"},"documentType":{"type":"string","description":"ID do tipo de documento (referência a /documents/types)","format":"ObjectId","pattern":"^[a-f0-9]{24}$","example":"5f8d3b7a9c2d1e0f4a6b5c4e"},"version":{"type":"integer","description":"Número da versão do documento","minimum":1,"example":1},"filePaths":{"type":"array","description":"Caminhos dos arquivos no S3/MinIO (relativos ao bucket)","items":{"type":"string"},"example":["documents/company1/factura_q1.pdf","documents/company1/anexo.pdf"]},"previousVersion":{"type":"string","description":"ID da versão anterior (null se for a primeira versão)","format":"ObjectId","pattern":"^[a-f0-9]{24}$","nullable":true,"example":null},"createdAt":{"type":"string","description":"Data de criação do documento (UTC)","format":"date-time","example":"2023-04-15T09:30:00.000Z"},"updatedAt":{"type":"string","description":"Data da última atualização (UTC)","format":"date-time","example":"2023-04-20T14:15:00.000Z"}},"title":"Document"}},"totalDocs":{"type":"integer","description":"Total de documentos encontrados (todas as páginas)","example":15},"limit":{"type":"integer","description":"Limite de documentos por página","example":10},"page":{"type":"integer","description":"Página atual","example":1},"totalPages":{"type":"integer","description":"Total de páginas disponíveis","example":2}},"title":"DocumentsPaginatedResponse"},"example":{"docs":[{"_id":"5f8d3b7a9c2d1e0f4a6b5c4d","name":"Factura Q1 2023","status":"approved","documentType":"5f8d3b7a9c2d1e0f4a6b5c4e","version":1,"filePaths":["documents/company1/factura_q1.pdf"],"createdAt":"2023-04-15T09:30:00.000Z","updatedAt":"2023-04-20T14:15:00.000Z"},{"_id":"5f8d3b7a9c2d1e0f4a6b5c4f","name":"Contrato de Servicios","status":"pending","documentType":"5f8d3b7a9c2d1e0f4a6b5c50","version":2,"filePaths":["documents/company1/contrato_v2.pdf","documents/company1/anexo.pdf"],"createdAt":"2023-05-10T11:20:00.000Z","updatedAt":"2023-05-12T16:45:00.000Z"}],"totalDocs":15,"limit":10,"page":1,"totalPages":2}}}},"401":{"description":"Não autorizado - Token JWT inválido ou ausente","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NO_TOKEN","TOKEN_NOT_VALID"]}}},"example":{"error":"NO_TOKEN"}}}},"403":{"description":"Proibido - Permissões insuficientes","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"NOT_ALLOWED"}}}}}}
>
  
</StatusCodes>