openapi: 3.0.0
info:
  title: Hub API - Aprova
  version: ''
  description: >
    O Hub API é uma plataforma de abstração de APIs projetada para padronizar e
    simplificar a integração de sistemas de parceiros terceiros com o Aprova. O
    principal objetivo é criar um ponto de entrada único e seguro para as
    funcionalidades do Aprova. Utilizamos um sistema de autenticação robusto
    para garantir que o uso dos nossos serviços por terceiros seja seguro,
    controlado e intuitivo. Isso facilita o trabalho de desenvolvedores externos
    e reduz a complexidade da integração.


    ## Como Obter sua Chave API

    Para começar a usar o Hub API, siga os passos abaixo para habilitar a
    funcionalidade e gerar suas chaves de acesso:


    **Passo 1: Ative a Permissão de Administrador**

    - Navegue até: *Outros > Administração Geral > Permissões > Todas as
    Permissões*

    - Ative a permissão `hubapi:admin`

    - Vincule essa permissão a um grupo de usuários administradores

    - Saia do sistema e entre novamente


    **Passo 2: Acesse o Gerenciador de Chaves**

    - Após ativar a permissão, um novo menu aparecerá

    - Navegue até: *Outros > Administração Geral > Gerenciar Ambiente > Chaves
    API - Hub API*


    **Passo 3: Crie sua Chave API**

    - Clique em **Criar Chave API**

    - Defina um nome único para identificar a chave

    - Copie e salve a chave exibida imediatamente


    **IMPORTANTE:**

    A chave API será exibida por completo apenas **uma vez**.

    Após sair da tela, por motivos de segurança, a chave completa **não será
    mostrada novamente**.

    Certifique-se de armazená-la em um local seguro.
  contact:
    name: Aprova
    email: suporte@aprova.com.br
components:
  securitySchemes:
    Authorization:
      description: Authorization
      type: apiKey
      name: Authorization
      in: header
    InternalAuth:
      description: Internal Authentication Key
      type: apiKey
      name: x-api-key
      in: header
  schemas: {}
paths:
  /hub-api/process/get-by-np:
    post:
      operationId: consultProcessV1Http
      summary: Consulta um processo por np e codvalid
      tags:
        - Process
      description: >-
        Este endpoint permite consultar um processo específico utilizando o
        número do processo (nP) e o código validador (codValid).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - nP
                - codValid
              properties:
                nP:
                  type: string
                  example: 337-25-pro-alv
                  description: Número do processo
                codValid:
                  type: string
                  example: ckusqxyx
                  description: Código validador
        required: true
      security:
        - InternalAuth: []
      responses:
        '200':
          description: Processo encontrado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identificador único do processo
                    example: 507f1f77bcf86cd799439011
                  nP:
                    type: string
                    description: Número do processo
                    example: 123-25-PRO-EXE
                  cod_valid:
                    type: string
                    description: Código validador do processo
                    example: abc12xyz
                  from:
                    type: object
                    description: Informações do criador do processo
                    properties:
                      userID:
                        type: string
                        example: auth0|123456789abcdef012345678
                  configMetadata:
                    type: object
                    description: Metadados da configuração do processo
                    properties:
                      title:
                        type: string
                        description: Título da configuração
                        example: Alvará de Construção
                      id:
                        type: string
                        description: ID da configuração
                        example: 507f191e810c19729de860ea
                  lastVersion:
                    type: object
                    description: >-
                      Última versão do processo com todos os dados e campos
                      preenchidos
                    properties:
                      from:
                        type: object
                        properties:
                          type:
                            type: string
                            example: user
                          label:
                            type: string
                            example: João da Silva Santos
                          value:
                            type: string
                            example: auth0|123456789abcdef012345678
                          accessLevel:
                            type: string
                            example: FULL
                      proprietario:
                        type: array
                        items:
                          type: object
                        example: []
                      destinatario:
                        type: array
                        items:
                          type: object
                          properties:
                            sector_type:
                              type: string
                              example: sector
                            value:
                              type: string
                              example: setor_urbanismo
                            label:
                              type: string
                              example: Setor de Urbanismo
                            id:
                              type: string
                              example: 507f191e810c19729de860ea
                        example:
                          - sector_type: sector
                            value: setor_urbanismo
                            label: Setor de Urbanismo
                            id: 507f191e810c19729de860ea
                      refinamento:
                        type: object
                        additionalProperties: true
                        example:
                          area_construcao: 150.5
                      cpf_cnpj:
                        type: string
                        example: 123.456.789-00
                      created_at_iso:
                        type: string
                        format: date-time
                        example: '2025-10-15T14:30:00.000Z'
                      created_at:
                        type: string
                        example: 15/10/2025 11:30:00
                      hasSensitiveField:
                        type: boolean
                        example: true
                    additionalProperties: true
                  createdAt:
                    type: string
                    description: Data de criação do processo
                    example: 15/10/2025 09:30:00
                  timeline:
                    type: array
                    description: Linha do tempo com todos os eventos do processo
                    items:
                      type: object
                      properties:
                        from:
                          type: object
                          properties:
                            userId:
                              type: string
                              example: auth0|123456789abcdef012345678
                            name:
                              type: string
                              example: João da Silva Santos
                            asSector:
                              type: string
                              nullable: true
                              example: null
                        class:
                          type: string
                          description: >-
                            Classe do evento (user, prefeituraEncaminha,
                            message, despacho, analise, deadline)
                          example: user
                        type:
                          type: string
                          description: Tipo do evento
                          example: evento
                        data:
                          type: object
                          properties:
                            action:
                              type: string
                              description: Descrição da ação executada
                              example: Processo criado
                        date:
                          type: string
                          example: 15/10/2025 09:30:00
                        created_at_iso:
                          type: string
                          format: date-time
                          example: '2025-10-15T12:30:00.000Z'
                      additionalProperties: true
                    example:
                      - from:
                          userId: auth0|123456789abcdef012345678
                          name: João da Silva Santos
                          asSector: null
                        class: user
                        type: evento
                        data:
                          action: Processo criado
                        date: 15/10/2025 09:30:00
                        created_at_iso: '2025-10-15T12:30:00.000Z'
                      - from:
                          userId: Desconhecido
                          name: Desconhecido/Evento Automático
                        to:
                          name: Setor de Urbanismo
                          userId: setor_urbanismo
                        class: prefeituraEncaminha
                        type: evento
                        data:
                          action: >-
                            Processo encaminhado com acesso total para Setor de
                            Urbanismo
                        date: 15/10/2025 09:30:15
                        created_at_iso: '2025-10-15T12:30:15.000Z'
                      - class: message
                        type: evento
                        data:
                          action: Documento de Aprovação emitido
                        from:
                          userId: auth0|987654321fedcba987654321
                          name: Maria Oliveira Costa
                        date: 16/10/2025 14:20:00
                        created_at_iso: '2025-10-16T17:20:00.000Z'
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid NP
                  message:
                    type: string
                    example: Número de processo inválido
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
                    example: API Key is required
                example:
                  error: Unauthorized
                  message: API Key is required
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Process not found
                  message:
                    type: string
                    example: Processo não encontrado
                example:
                  error: Process not found
                  message: Processo não encontrado
  /hub-api/process/create:
    post:
      operationId: createProcessV1Http
      summary: Cria um processo sem validação de regras de formulário
      tags:
        - Process
      description: >-
        Cria um processo sem validação de regras de formulário (salva a version
        da forma que recebeu). Este endpoint permite criar processos diretamente
        sem passar pelas validações padrão do sistema.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - version
                - city_id
                - config_metadata
                - config
              properties:
                version:
                  type: object
                  description: >-
                    Dados da versão do processo (será salvo exatamente como
                    recebido)
                  additionalProperties: true
                  example:
                    from:
                      type: user
                      label: João da Silva
                      value: auth0|123456789abcdef012345678
                    proprietario: []
                    destinatario: []
                    refinamento: {}
                city_id:
                  type: number
                  description: ID da cidade
                  example: 123
                config_metadata:
                  type: object
                  description: Metadados de configuração do processo
                  additionalProperties: true
                  example:
                    id: 507f191e810c19729de860ea
                    title: Alvará de Construção
                config:
                  type: array
                  description: Configuração do formulário
                  items:
                    type: object
                    additionalProperties: true
                  example: []
                step:
                  type: object
                  description: Configuração de etapas (opcional)
                  additionalProperties: true
                destination:
                  type: object
                  description: Configuração de destino (opcional)
                  additionalProperties: true
                bond:
                  type: object
                  description: Configuração de vínculo (opcional)
                  additionalProperties: true
                tenance:
                  type: string
                  description: Valor de tenance (opcional)
                  example: ''
                _id:
                  type: string
                  description: ID do rascunho (opcional)
                  example: 507f1f77bcf86cd799439012
                resetCountEveryYear:
                  type: boolean
                  description: Flag para resetar contagem a cada ano (opcional)
                  example: false
                from:
                  type: object
                  description: Informações do usuário remetente (opcional)
                  properties:
                    email:
                      type: string
                      example: usuario@exemplo.com
                    userID:
                      type: string
                      example: auth0|123456789abcdef012345678
                    alias:
                      type: object
                      additionalProperties: true
                form_tramites:
                  type: array
                  description: Configuração de formulários de trâmites (opcional)
                  items:
                    type: object
                    additionalProperties: true
                s3_token:
                  type: string
                  description: Token S3 para upload de arquivos (opcional)
                  example: ''
                status:
                  type: string
                  description: Status do processo
                  example: ''
                analises:
                  type: array
                  description: Análises do processo (opcional)
                  items:
                    type: object
                    additionalProperties: true
                anotacoesAnalista:
                  type: array
                  description: Anotações do analista (opcional)
                  items:
                    type: object
                    additionalProperties: true
                observacoes:
                  type: array
                  description: Observações do processo (opcional)
                  items:
                    type: object
                    additionalProperties: true
                tramites:
                  type: array
                  description: Trâmites do processo (opcional)
                  items:
                    type: object
                    additionalProperties: true
                notes:
                  type: array
                  description: Notas do processo (opcional)
                  items:
                    type: object
                    additionalProperties: true
                tags:
                  type: array
                  description: Tags do processo (opcional)
                  items:
                    type: object
                    additionalProperties: true
        required: true
      security:
        - InternalAuth: []
      responses:
        '200':
          description: Processo criado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identificador único do processo criado
                    example: 507f1f77bcf86cd799439011
                  nP:
                    type: string
                    description: Número do processo gerado
                    example: 123-25-PRO-EXE
                  cod_valid:
                    type: string
                    description: Código validador do processo
                    example: abc12xyz
                  from:
                    type: object
                    description: Informações do criador do processo
                    properties:
                      userID:
                        type: string
                        example: auth0|123456789abcdef012345678
                      email:
                        type: string
                        example: usuario@exemplo.com
                  config_metadata:
                    type: object
                    description: Metadados da configuração do processo
                    properties:
                      id:
                        type: string
                        example: 507f191e810c19729de860ea
                      title:
                        type: string
                        example: Alvará de Construção
                  last_version:
                    type: object
                    description: Última versão do processo criado
                    additionalProperties: true
                  created_at:
                    type: string
                    description: Data de criação do processo
                    example: 15/10/2025 09:30:00
                  city_id:
                    type: number
                    description: ID da cidade do processo
                    example: 123
        '400':
          description: >-
            Requisição inválida (campos obrigatórios ausentes ou dados
            inválidos)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
                  message:
                    type: string
                    example: version, city_id, config_metadata and config are required
        '401':
          description: Falha de autenticação (API Key ausente ou inválida)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
                    example: API Key is required
                example:
                  error: Unauthorized
                  message: API Key is required
        '500':
          description: Erro interno do servidor
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal Server Error
                  message:
                    type: string
                    example: Failed to create process
  /hub-api/users:
    get:
      operationId: getUserV1Http
      summary: Consulta informações de um usuário
      tags:
        - Users
      description: >-
        Consulta dados detalhados de um usuário a partir do identificador do
        Aut0.
      parameters:
        - name: userId
          in: query
          required: true
          schema:
            type: string
            example: auth0|1234567890abcdef12345678
          description: Identificador único do usuário (ID Aut0).
      security:
        - InternalAuth: []
      responses:
        '200':
          description: Usuário encontrado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  person:
                    type: object
                    description: Informações pessoais do usuário
                    properties:
                      id:
                        type: string
                        description: Identificador do usuário
                        example: auth0|1234567890abcdef12345678
                      type:
                        type: string
                        description: Tipo da conta do usuário
                        example: personal
                      document:
                        type: string
                        description: Documento (CPF)
                        example: '12345678900'
                      email:
                        type: string
                        format: email
                        description: E-mail principal
                        example: usuario.parceiro@exemplo.com
                      name:
                        type: string
                        description: Nome completo do usuário
                        example: Maria Oliveira
                      phone:
                        type: string
                        description: Telefone de contato
                        example: '11999998888'
                      address:
                        oneOf:
                          - type: string
                          - type: object
                            description: Endereço estruturado quando disponível
                            properties:
                              cep:
                                type: string
                                example: '01001000'
                              street:
                                type: string
                                example: Praça da Sé
                              number:
                                type: string
                                example: '100'
                              complement:
                                type: string
                                example: Conjunto 12
                              neighborhood:
                                type: string
                                example: Sé
                              city:
                                type: string
                                example: São Paulo
                              state:
                                type: string
                                example: SP
                  user:
                    type: object
                    description: Informações adicionais do usuário no Aprova
                    properties:
                      role:
                        type: string
                        description: Cargo ou função do usuário
                        example: Analista
                      linked_sectors:
                        type: array
                        description: Setores vinculados ao usuário
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              example: 507f1f77bcf86cd799439011
                            name:
                              type: string
                              example: Setor de Licenciamento
                      assigned_permissions:
                        type: array
                        description: Permissões atribuídas ao usuário
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              example: process:view
                            name:
                              type: string
                              example: process:view
                      account_status:
                        type: string
                        description: Status atual da conta
                        example: active
                      account_situation:
                        type: object
                        nullable: true
                        description: Situação da conta quando disponível
                        properties:
                          id:
                            type: string
                            example: situation-01
                          name:
                            type: string
                            example: Conta regular
                      created_at:
                        type: string
                        format: date-time
                        description: Data de criação do usuário
                        example: '2025-06-01T12:00:00.000Z'
                      last_login:
                        type: string
                        format: date-time
                        description: Data do último login
                        example: '2025-11-05T19:52:42.883Z'
                      last_registration_update:
                        type: string
                        format: date-time
                        description: Data da última atualização cadastral
                        example: '2025-10-20T08:15:30.000Z'
                      redirect_to:
                        type: string
                        nullable: true
                        description: ID da conta acolhedora quando aplicável
                        example: null
        '400':
          description: Requisição inválida (parâmetros incorretos ou usuário inexistente)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
                  message:
                    type: string
                    example: Este usuário pertence a outra organização
        '401':
          description: Falha de autenticação (API Key ausente ou inválida)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
                    example: API Key is required
        '404':
          description: Usuário não encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
                  message:
                    type: string
                    example: User not found
servers:
  - url: https://api.producao.aprova.com.br
tags:
  - name: Process
    description: Operações relacionadas à consulta de processos
  - name: Users
    description: Operações relacionadas à consulta de usuários
