openapi: 3.0.3
info:
  title: Manifestacao NF-e de Entrada API
  version: 1.0.0
  description: API para autenticacao, integracoes, distribuicao, manifestacao, busca e exportacao de NF-e de entrada.
servers:
  - url: /
    description: Mesma origem da aplicacao
tags:
  - name: Auth
  - name: OAuth
  - name: Integracoes
  - name: Manifestacao NF-e
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
      description: Limite maximo de registros.
    DateFromParam:
      name: date_from
      in: query
      schema:
        type: string
        format: date
    DateToParam:
      name: date_to
      in: query
      schema:
        type: string
        format: date
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    DeleteResponse:
      type: object
      properties:
        deleted:
          type: boolean
        id:
          type: string
          format: uuid
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        time:
          type: string
          format: date-time
        last_log_id:
          type: string
          format: uuid
          nullable: true
    Integration:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        active:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    IntegrationCreateRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          example: ERP Principal
        description:
          type: string
          example: Integracao usada pelo ERP
        active:
          type: boolean
          example: true
    AuthTokenRequest:
      type: object
      required: [username, password]
      properties:
        username:
          type: string
        password:
          type: string
        integration_id:
          type: string
          format: uuid
        integration_name:
          type: string
    AuthRefreshRequest:
      type: object
      required: [refresh_token]
      properties:
        refresh_token:
          type: string
        integration_id:
          type: string
          format: uuid
        integration_name:
          type: string
    KeycloakTokenResponse:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        refresh_expires_in:
          type: integer
        scope:
          type: string
        api_key:
          type: string
        integration:
          type: object
          nullable: true
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
    OAuthTokenRequest:
      type: object
      required: [grant_type, client_id, client_secret]
      properties:
        grant_type:
          type: string
          example: client_credentials
        client_id:
          type: string
        client_secret:
          type: string
        scope:
          type: string
    OAuthTokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        scope:
          type: string
    OAuthRevokeRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string
    OAuthRevokeResponse:
      type: object
      properties:
        revoked:
          type: boolean
          example: true
    OAuthJwksResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            type: object
        alg:
          type: string
          example: HS256
    Control:
      type: object
      properties:
        id:
          type: string
          format: uuid
        integration_id:
          type: string
          format: uuid
          nullable: true
        certificate_id:
          type: string
          format: uuid
          nullable: true
        company_name:
          type: string
        document_number:
          type: string
        document_type:
          type: string
        state_code:
          type: string
        environment:
          type: string
        manifestation_mode:
          type: string
        last_nsu:
          type: string
          nullable: true
        max_nsu:
          type: string
          nullable: true
        last_query_status_code:
          type: string
          nullable: true
        last_query_status_message:
          type: string
          nullable: true
        last_query_at:
          type: string
          format: date-time
          nullable: true
        last_success_at:
          type: string
          format: date-time
          nullable: true
        last_error_at:
          type: string
          format: date-time
          nullable: true
        last_error_message:
          type: string
          nullable: true
        schedule_enabled:
          type: integer
        active:
          type: integer
        metadata_json:
          type: string
          nullable: true
    ControlCreateRequest:
      type: object
      required: [company_name, document_number]
      properties:
        integration_id:
          type: string
          format: uuid
        integration_name:
          type: string
        certificate_id:
          type: string
          format: uuid
        company_name:
          type: string
        document_number:
          type: string
        state_code:
          type: string
          example: SP
        environment:
          type: string
          example: production
        manifestation_mode:
          type: string
          example: manual
        schedule_enabled:
          type: boolean
        active:
          type: boolean
        metadata:
          type: object
          additionalProperties: true
    AssignCertificateRequest:
      type: object
      required: [certificate_id]
      properties:
        certificate_id:
          type: string
          format: uuid
    SyncRequest:
      type: object
      properties:
        nsu:
          type: string
        access_key:
          type: string
        last_nsu:
          type: string
        initial_load:
          type: boolean
    DistributionResult:
      type: object
      properties:
        status_code:
          type: string
        status_message:
          type: string
        ult_nsu:
          type: string
          nullable: true
        max_nsu:
          type: string
          nullable: true
        requests_made:
          type: integer
        initial_load:
          type: boolean
        initial_load_completed:
          type: boolean
    SyncResponse:
      type: object
      properties:
        control:
          $ref: "#/components/schemas/Control"
        documents:
          type: array
          items:
            $ref: "#/components/schemas/Document"
        distribution:
          $ref: "#/components/schemas/DistributionResult"
        log_id:
          type: string
          format: uuid
    DocumentSearchRequest:
      type: object
      properties:
        distribution_control_id:
          type: string
          format: uuid
        integration_id:
          type: string
          format: uuid
        access_key:
          type: string
          example: "35260412345678000199550010000012341000012345"
        issuer_cnpj_cpf:
          type: string
          example: "12345678000199"
        issuer_name:
          type: string
          example: "Fornecedor Alfa"
        recipient_cnpj_cpf:
          type: string
        recipient_name:
          type: string
        number:
          type: string
          example: "1234"
        series:
          type: string
          example: "1"
        operation_nature:
          type: string
          example: "Compra para revenda"
        manifestation_status:
          type: string
          example: "confirmed"
        download_status:
          type: string
          example: "full"
        distribution_type:
          type: string
        distribution_schema:
          type: string
        invoice_status:
          type: string
        freight_mode:
          type: string
        date_from:
          type: string
          format: date
        date_to:
          type: string
          format: date
        manifested_from:
          type: string
          format: date
        manifested_to:
          type: string
          format: date
        authorized_from:
          type: string
          format: date
        authorized_to:
          type: string
          format: date
        total_invoice_min:
          type: number
          format: double
        total_invoice_max:
          type: number
          format: double
        total_products_min:
          type: number
          format: double
        total_products_max:
          type: number
          format: double
        total_discount_min:
          type: number
          format: double
        total_discount_max:
          type: number
          format: double
        value_min:
          type: number
          format: double
        value_max:
          type: number
          format: double
        q:
          type: string
        limit:
          type: integer
    ManifestationEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        nfe_document_id:
          type: string
          format: uuid
        event_type:
          type: string
        event_code:
          type: string
        event_sequence:
          type: integer
        justification:
          type: string
          nullable: true
        protocol_number:
          type: string
          nullable: true
        status:
          type: string
        sefaz_status_code:
          type: string
          nullable: true
        sefaz_status_message:
          type: string
          nullable: true
        requested_at:
          type: string
          format: date-time
          nullable: true
        processed_at:
          type: string
          format: date-time
          nullable: true
    Document:
      type: object
      properties:
        id:
          type: string
          format: uuid
        distribution_control_id:
          type: string
          format: uuid
        integration_id:
          type: string
          format: uuid
          nullable: true
        access_key:
          type: string
        nsu:
          type: string
          nullable: true
        issuer_cnpj_cpf:
          type: string
          nullable: true
        issuer_name:
          type: string
          nullable: true
        recipient_cnpj_cpf:
          type: string
          nullable: true
        recipient_name:
          type: string
          nullable: true
        operation_nature:
          type: string
          nullable: true
        number:
          type: string
          nullable: true
        series:
          type: string
          nullable: true
        issue_datetime:
          type: string
          format: date-time
          nullable: true
        total_invoice:
          type: string
          nullable: true
        manifestation_status:
          type: string
        download_status:
          type: string
          nullable: true
        manifested_at:
          type: string
          format: date-time
          nullable: true
        sefaz_status_code:
          type: string
          nullable: true
        sefaz_status_message:
          type: string
          nullable: true
    ItemSearchRequest:
      allOf:
        - $ref: "#/components/schemas/DocumentSearchRequest"
        - type: object
          properties:
            nfe_document_id:
              type: string
              format: uuid
            line_number:
              type: integer
            product_code:
              type: string
            ean:
              type: string
            description:
              type: string
            ncm:
              type: string
            cfop:
              type: string
            unit:
              type: string
            tax_origin:
              type: string
            icms_cst_csosn:
              type: string
            ipi_cst:
              type: string
            pis_cst:
              type: string
            cofins_cst:
              type: string
            additional_info:
              type: string
            quantity_min:
              type: number
            quantity_max:
              type: number
            unit_value_min:
              type: number
            unit_value_max:
              type: number
            gross_value_min:
              type: number
            gross_value_max:
              type: number
            total_value_min:
              type: number
            total_value_max:
              type: number
            item_q:
              type: string
    Item:
      type: object
      properties:
        id:
          type: string
          format: uuid
        nfe_document_id:
          type: string
          format: uuid
        line_number:
          type: integer
        product_code:
          type: string
          nullable: true
        ean:
          type: string
          nullable: true
        description:
          type: string
        ncm:
          type: string
          nullable: true
        cfop:
          type: string
          nullable: true
        unit:
          type: string
          nullable: true
        quantity:
          type: string
          nullable: true
        unit_value:
          type: string
          nullable: true
        gross_value:
          type: string
          nullable: true
        total_value:
          type: string
          nullable: true
        tax_origin:
          type: string
          nullable: true
        icms_cst_csosn:
          type: string
          nullable: true
        ipi_cst:
          type: string
          nullable: true
        pis_cst:
          type: string
          nullable: true
        cofins_cst:
          type: string
          nullable: true
        additional_info:
          type: string
          nullable: true
        access_key:
          type: string
        issuer_name:
          type: string
          nullable: true
        recipient_name:
          type: string
          nullable: true
        number:
          type: string
          nullable: true
        series:
          type: string
          nullable: true
        issue_datetime:
          type: string
          format: date-time
          nullable: true
        total_invoice:
          type: string
          nullable: true
        manifestation_status:
          type: string
          nullable: true
        download_status:
          type: string
          nullable: true
        manifested_at:
          type: string
          format: date-time
          nullable: true
    DocumentDetail:
      allOf:
        - $ref: "#/components/schemas/Document"
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Item"
            manifestations:
              type: array
              items:
                $ref: "#/components/schemas/ManifestationEvent"
    ExportRequest:
      type: object
      properties:
        date_from:
          type: string
          format: date
        date_to:
          type: string
          format: date
        manifested_from:
          type: string
          format: date
        manifested_to:
          type: string
          format: date
        distribution_control_id:
          type: string
          format: uuid
        integration_id:
          type: string
          format: uuid
        access_key:
          type: string
        issuer_cnpj_cpf:
          type: string
        recipient_cnpj_cpf:
          type: string
        manifestation_status:
          type: string
        download_status:
          type: string
        limit:
          type: integer
    ManifestRequest:
      type: object
      properties:
        document_id:
          type: string
          format: uuid
        access_key:
          type: string
        event:
          type: string
          example: confirmacao
        event_code:
          type: string
          example: "210200"
        sequence:
          type: integer
          example: 1
        justification:
          type: string
          nullable: true
    ManifestResponse:
      type: object
      properties:
        manifestation:
          $ref: "#/components/schemas/ManifestationEvent"
        document:
          $ref: "#/components/schemas/Document"
        download:
          type: object
          additionalProperties: true
        log_id:
          type: string
          format: uuid
    Certificate:
      type: object
      properties:
        id:
          type: string
          format: uuid
        integration_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        description:
          type: string
          nullable: true
        document_number:
          type: string
          nullable: true
        company_name:
          type: string
          nullable: true
        certificate_type:
          type: string
        file_name:
          type: string
        mime_type:
          type: string
        file_extension:
          type: string
        serial_number:
          type: string
          nullable: true
        fingerprint_sha1:
          type: string
          nullable: true
        subject_dn:
          type: string
          nullable: true
        issuer_dn:
          type: string
          nullable: true
        valid_from_at:
          type: string
          format: date-time
          nullable: true
        valid_to_at:
          type: string
          format: date-time
          nullable: true
        last_used_at:
          type: string
          format: date-time
          nullable: true
        active:
          type: integer
        metadata_json:
          type: string
          nullable: true
    CertificateImportJsonRequest:
      type: object
      required: [certificate_password, pfx_content_base64]
      properties:
        integration_id:
          type: string
          format: uuid
        integration_name:
          type: string
        name:
          type: string
        description:
          type: string
        certificate_type:
          type: string
          example: A1
        file_name:
          type: string
        mime_type:
          type: string
        certificate_password:
          type: string
        private_key_password:
          type: string
        pfx_content_base64:
          type: string
        active:
          type: boolean
    CertificateImportFileJsonRequest:
      type: object
      required: [pfx_content_base64]
      properties:
        integration_id:
          type: string
          format: uuid
        integration_name:
          type: string
        name:
          type: string
        description:
          type: string
        certificate_type:
          type: string
          example: A1
        file_name:
          type: string
        mime_type:
          type: string
        pfx_content_base64:
          type: string
        active:
          type: boolean
    CertificateImportMultipartRequest:
      type: object
      required: [certificate, certificate_password]
      properties:
        certificate:
          type: string
          format: binary
        integration_id:
          type: string
          format: uuid
        integration_name:
          type: string
        name:
          type: string
        description:
          type: string
        certificate_type:
          type: string
        certificate_password:
          type: string
        private_key_password:
          type: string
        active:
          type: boolean
    CertificateImportFileMultipartRequest:
      type: object
      required: [certificate]
      properties:
        certificate:
          type: string
          format: binary
        integration_id:
          type: string
          format: uuid
        integration_name:
          type: string
        name:
          type: string
        description:
          type: string
        certificate_type:
          type: string
        active:
          type: boolean
    CertificatePasswordRequest:
      type: object
      required: [certificate_password]
      properties:
        integration_id:
          type: string
          format: uuid
        integration_name:
          type: string
        name:
          type: string
        description:
          type: string
        certificate_type:
          type: string
          example: A1
        certificate_password:
          type: string
        private_key_password:
          type: string
        active:
          type: boolean
    LogEntry:
      type: object
      properties:
        id:
          type: string
          format: uuid
        integration_id:
          type: string
          format: uuid
          nullable: true
        distribution_control_id:
          type: string
          format: uuid
          nullable: true
        nfe_document_id:
          type: string
          format: uuid
          nullable: true
        nfe_manifestation_id:
          type: string
          format: uuid
          nullable: true
        operation:
          type: string
        operation_group:
          type: string
        status:
          type: string
        severity:
          type: string
        environment:
          type: string
        actor_document:
          type: string
          nullable: true
        access_key:
          type: string
          nullable: true
        nsu:
          type: string
          nullable: true
        event_code:
          type: string
          nullable: true
        sefaz_status_code:
          type: string
          nullable: true
        sefaz_status_message:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        error_code:
          type: string
          nullable: true
        exception_class:
          type: string
          nullable: true
        ftp_path:
          type: string
          nullable: true
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
paths:
  /auth/token:
    post:
      tags: [Auth]
      summary: Gera token via Keycloak
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/AuthTokenRequest"
      responses:
        "200":
          description: Token emitido
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KeycloakTokenResponse"
        "400":
          description: Requisicao invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /auth/refresh:
    post:
      tags: [Auth]
      summary: Atualiza token via Keycloak
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/AuthRefreshRequest"
      responses:
        "200":
          description: Token atualizado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KeycloakTokenResponse"
        "400":
          description: Requisicao invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /oauth/token:
    post:
      tags: [OAuth]
      summary: Emite token OAuth client credentials
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/OAuthTokenRequest"
      responses:
        "200":
          description: Token OAuth emitido
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthTokenResponse"
        "400":
          description: Requisicao invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Cliente invalido
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /oauth/revoke:
    post:
      tags: [OAuth]
      summary: Revoga token OAuth
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/OAuthRevokeRequest"
      responses:
        "200":
          description: Token revogado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthRevokeResponse"
        "400":
          description: Token invalido
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /oauth/jwks:
    get:
      tags: [OAuth]
      summary: Retorna JWKS simplificado
      responses:
        "200":
          description: Chaves disponiveis
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthJwksResponse"
  /api/v1/health:
    get:
      tags: [Manifestacao NF-e]
      summary: Health check da API
      security:
        - bearerAuth: []
      responses:
        "200":
          description: API operante
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /api/v1/auth/token:
    post:
      tags: [Auth]
      summary: Gera token via Keycloak
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/AuthTokenRequest"
      responses:
        "200":
          description: Token emitido
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KeycloakTokenResponse"
        "400":
          description: Requisicao invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/auth/refresh:
    post:
      tags: [Auth]
      summary: Atualiza token via Keycloak
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/AuthRefreshRequest"
      responses:
        "200":
          description: Token atualizado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KeycloakTokenResponse"
        "400":
          description: Requisicao invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/integrations:
    get:
      tags: [Integracoes]
      summary: Lista integracoes
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Lista de integracoes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Integration"
    post:
      tags: [Integracoes]
      summary: Cria integracao
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IntegrationCreateRequest"
      responses:
        "201":
          description: Integracao criada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Integration"
        "400":
          description: Entrada invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Integracao ja existe
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/integrations/{id}:
    put:
      tags: [Integracoes]
      summary: Atualiza integracao
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IntegrationCreateRequest"
      responses:
        "200":
          description: Integracao atualizada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Integration"
        "400":
          description: Entrada invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Integracao nao encontrada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags: [Integracoes]
      summary: Exclui integracao
      description: Exclui apenas integracoes sem controles, certificados, chaves de API ou dados historicos gerados pela operacao.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      responses:
        "200":
          description: Integracao excluida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteResponse"
        "404":
          description: Integracao nao encontrada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Exclusao bloqueada por vinculos ou historico operacional
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/health:
    get:
      tags: [Manifestacao NF-e]
      summary: Health check do modulo de manifestacao
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Modulo operante
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /api/v1/nfe/manifestation/controls:
    get:
      tags: [Manifestacao NF-e]
      summary: Lista controles de distribuicao
      security:
        - bearerAuth: []
      parameters:
        - name: integration_id
          in: query
          schema:
            type: string
            format: uuid
        - name: document_number
          in: query
          schema:
            type: string
        - name: active
          in: query
          schema:
            type: boolean
      responses:
        "200":
          description: Lista de controles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Control"
    post:
      tags: [Manifestacao NF-e]
      summary: Cria ou atualiza controle de distribuicao
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ControlCreateRequest"
      responses:
        "200":
          description: Controle salvo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Control"
        "400":
          description: Entrada invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/controls/{id}:
    put:
      tags: [Manifestacao NF-e]
      summary: Atualiza controle de distribuicao
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ControlCreateRequest"
      responses:
        "200":
          description: Controle atualizado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Control"
        "400":
          description: Entrada invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Controle nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags: [Manifestacao NF-e]
      summary: Exclui controle de distribuicao
      description: Permitido apenas para controles sem documentos distribuidos, sem logs operacionais e sem historico de NSU gerado pela SEFAZ.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      responses:
        "200":
          description: Controle excluido
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteResponse"
        "404":
          description: Controle nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Exclusao bloqueada por historico SEFAZ ou logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    get:
      tags: [Manifestacao NF-e]
      summary: Detalha controle de distribuicao
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      responses:
        "200":
          description: Controle encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Control"
        "404":
          description: Controle nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/controls/{id}/certificate:
    post:
      tags: [Manifestacao NF-e]
      summary: Vincula certificado ao controle
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssignCertificateRequest"
      responses:
        "200":
          description: Controle atualizado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Control"
        "400":
          description: Requisicao invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/controls/{id}/sync:
    post:
      tags: [Manifestacao NF-e]
      summary: Sincroniza distribuicao com a SEFAZ
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyncRequest"
      responses:
        "200":
          description: Sincronizacao concluida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncResponse"
        "400":
          description: Falha na sincronizacao
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/documents:
    get:
      tags: [Manifestacao NF-e]
      summary: Busca notas encontradas pela SEFAZ
      security:
        - bearerAuth: []
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: access_key
          in: query
          schema:
            type: string
        - name: issuer_name
          in: query
          schema:
            type: string
        - name: issuer_cnpj_cpf
          in: query
          schema:
            type: string
        - name: recipient_name
          in: query
          schema:
            type: string
        - name: manifestation_status
          in: query
          schema:
            type: string
        - name: download_status
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/DateFromParam"
        - $ref: "#/components/parameters/DateToParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Lista de notas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Document"
    post:
      tags: [Manifestacao NF-e]
      summary: Busca notas com filtros compostos
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DocumentSearchRequest"
      responses:
        "200":
          description: Lista de notas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Document"
  /api/v1/nfe/manifestation/documents/{id}:
    get:
      tags: [Manifestacao NF-e]
      summary: Detalha uma nota
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      responses:
        "200":
          description: Documento encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentDetail"
        "404":
          description: Documento nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/items:
    get:
      tags: [Manifestacao NF-e]
      summary: Busca itens das notas manifestadas
      security:
        - bearerAuth: []
      parameters:
        - name: item_q
          in: query
          schema:
            type: string
        - name: issuer_name
          in: query
          schema:
            type: string
        - name: cfop
          in: query
          schema:
            type: string
        - name: ncm
          in: query
          schema:
            type: string
        - name: manifestation_status
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/DateFromParam"
        - $ref: "#/components/parameters/DateToParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Lista de itens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Item"
    post:
      tags: [Manifestacao NF-e]
      summary: Busca itens com filtros compostos
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemSearchRequest"
      responses:
        "200":
          description: Lista de itens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Item"
  /api/v1/nfe/manifestation/export:
    get:
      tags: [Manifestacao NF-e]
      summary: Exporta notas manifestadas
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/DateFromParam"
        - $ref: "#/components/parameters/DateToParam"
        - name: manifestation_status
          in: query
          schema:
            type: string
        - name: download_status
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Arquivo ZIP
          content:
            application/zip:
              schema:
                type: string
                format: binary
    post:
      tags: [Manifestacao NF-e]
      summary: Exporta notas manifestadas com filtros compostos
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExportRequest"
      responses:
        "200":
          description: Arquivo ZIP
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /api/v1/nfe/manifestation/events:
    post:
      tags: [Manifestacao NF-e]
      summary: Envia evento de manifestacao para a SEFAZ
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ManifestRequest"
      responses:
        "200":
          description: Manifestacao processada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManifestResponse"
        "400":
          description: Erro de validacao ou envio
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/certificates:
    get:
      tags: [Manifestacao NF-e]
      summary: Lista certificados
      security:
        - bearerAuth: []
      parameters:
        - name: integration_id
          in: query
          schema:
            type: string
            format: uuid
        - name: document_number
          in: query
          schema:
            type: string
        - name: active
          in: query
          schema:
            type: boolean
        - name: include_sensitive
          in: query
          schema:
            type: boolean
      responses:
        "200":
          description: Lista de certificados
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Certificate"
  /api/v1/nfe/manifestation/certificates/import:
    post:
      tags: [Manifestacao NF-e]
      summary: Importa certificado A1
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CertificateImportJsonRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/CertificateImportMultipartRequest"
      responses:
        "201":
          description: Certificado importado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Certificate"
        "400":
          description: Falha na importacao
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/certificates/import/file:
    post:
      tags: [Manifestacao NF-e]
      summary: Importa somente o arquivo do certificado A1
      description: Salva o arquivo PFX/P12 sem validar a senha. Use o endpoint de definicao de senha para completar o cadastro.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/CertificateImportFileMultipartRequest"
      responses:
        "201":
          description: Arquivo do certificado importado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Certificate"
        "400":
          description: Falha na importacao do arquivo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/certificates/{id}:
    put:
      tags: [Manifestacao NF-e]
      summary: Atualiza metadados do certificado
      description: Permite atualizar apenas campos cadastrais e operacionais do certificado. O arquivo do PFX, itens de NF-e e manifestacoes nao sao editados por este endpoint.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CertificatePasswordRequest"
      responses:
        "200":
          description: Certificado atualizado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Certificate"
        "400":
          description: Entrada invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Certificado nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags: [Manifestacao NF-e]
      summary: Exclui certificado
      description: Permitido apenas para certificados sem vinculo com controles e sem historico de utilizacao.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      responses:
        "200":
          description: Certificado excluido
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteResponse"
        "404":
          description: Certificado nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Exclusao bloqueada por vinculo ou historico de uso
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    get:
      tags: [Manifestacao NF-e]
      summary: Detalha certificado
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
        - name: include_sensitive
          in: query
          schema:
            type: boolean
      responses:
        "200":
          description: Certificado encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Certificate"
        "404":
          description: Certificado nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/certificates/{id}/password:
    post:
      tags: [Manifestacao NF-e]
      summary: Define a senha do certificado importado
      description: Completa um certificado enviado sem senha, validando o PFX e preenchendo os metadados.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CertificatePasswordRequest"
      responses:
        "200":
          description: Senha definida e certificado validado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Certificate"
        "400":
          description: Falha ao definir senha
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Certificado nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/certificates/{id}/deactivate:
    post:
      tags: [Manifestacao NF-e]
      summary: Desativa certificado
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      responses:
        "200":
          description: Certificado desativado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Certificate"
        "404":
          description: Certificado nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/nfe/manifestation/logs:
    get:
      tags: [Manifestacao NF-e]
      summary: Lista logs operacionais
      security:
        - bearerAuth: []
      parameters:
        - name: operation
          in: query
          schema:
            type: string
        - name: operation_group
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
        - name: severity
          in: query
          schema:
            type: string
        - name: access_key
          in: query
          schema:
            type: string
        - name: actor_document
          in: query
          schema:
            type: string
        - name: event_code
          in: query
          schema:
            type: string
        - name: sefaz_status_code
          in: query
          schema:
            type: string
        - name: error_code
          in: query
          schema:
            type: string
        - name: distribution_control_id
          in: query
          schema:
            type: string
            format: uuid
        - name: nfe_document_id
          in: query
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/DateFromParam"
        - $ref: "#/components/parameters/DateToParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Lista de logs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LogEntry"
  /api/v1/nfe/manifestation/logs/{id}:
    get:
      tags: [Manifestacao NF-e]
      summary: Detalha log operacional
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdParam"
      responses:
        "200":
          description: Log encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LogEntry"
        "404":
          description: Log nao encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
