openapi: 3.0.3
info:
  title: Lompa ERP API Publica
  version: 1.0.0-alpha.1
  description: |
    Especificacao inicial da API publica partner-facing do ERP Lompa.

    Escopo atual (v1-alpha):
    - onboarding inicial (em preparacao para exposicao publica)
    - fiscal / naturezas de operacao (em preparacao para exposicao publica)
    - integracao inicial com Mercado Livre (em preparacao para fachada publica)

    Nesta primeira versao do spec, apenas os endpoints publicos atualmente registrados em `/api/public/v1`
    estao documentados. Alguns endpoints ainda sao placeholders e servem para consolidar contrato, DX e padroes.

    Autenticacao alvo da API publica: OAuth 2.0 (Authorization Code + PKCE), conforme decisoes de arquitetura.
    O runtime atual ainda esta em fase de transicao para esse modelo.
  contact:
    name: Lompa ERP
servers:
  - url: https://erp.lompa.com.br
    description: Producao (target)
  - url: http://localhost:8080
    description: Desenvolvimento local (backend)
tags:
  - name: Empresa
    description: Endpoints de empresa para API publica (alpha; escopo enxuto)
  - name: Fiscal
    description: Endpoints fiscais partner-facing (v1-alpha; placeholders iniciais)
externalDocs:
  description: Changelog da API Publica
  url: https://erp.lompa.com.br/developers/changelog/api-publica
paths:
  /api/public/v1/company/{cnpj}:
    get:
      tags:
        - Empresa
      summary: Consultar empresa por CNPJ (placeholder alpha)
      description: |
        Endpoint placeholder da API publica. Atualmente retorna resposta basica e valida CNPJ com 14 digitos.

        Observacao importante:
        - auth publica final sera OAuth 2.0 + PKCE
        - neste placeholder alpha, o runtime ainda nao exige Bearer token
      operationId: getPublicCompanyByCNPJ
      security: []
      parameters:
        - name: cnpj
          in: path
          required: true
          description: CNPJ com 14 digitos numericos.
          schema:
            type: string
            pattern: '^\d{14}$'
            example: '12345678000199'
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          description: Resposta placeholder de consulta de empresa.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyLookupPlaceholderResponse'
              examples:
                placeholder:
                  value:
                    cnpj: '12345678000199'
                    status: placeholder - consulta CNPJ será implementada
        '400':
          description: CNPJ invalido.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
              examples:
                invalidCnpj:
                  value:
                    code: INVALID_CNPJ
                    message: CNPJ deve conter 14 dígitos numéricos
                    details:
                      field: cnpj
                    request_id: 8bb8d1d3-b4e9-4f59-9608-1fdf7ee6f060
  /api/public/v1/nfe:
    post:
      tags:
        - Fiscal
      summary: Criar NF-e (placeholder alpha)
      description: |
        Endpoint placeholder para futura criacao de NF-e partner-facing.
        Nesta fase retorna apenas uma confirmacao placeholder para consolidar namespace e contrato.
      operationId: createPublicNFePlaceholder
      security: []
      parameters:
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '201':
          description: Resposta placeholder de criacao de NF-e.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NFeCreatePlaceholderResponse'
              examples:
                created:
                  value:
                    message: NF-e creation placeholder
  /api/public/v1/nfe/{id}:
    get:
      tags:
        - Fiscal
      summary: Consultar NF-e (placeholder alpha)
      description: |
        Endpoint placeholder para futura consulta de NF-e partner-facing.
      operationId: getPublicNFePlaceholder
      security: []
      parameters:
        - name: id
          in: path
          required: true
          description: Identificador da NF-e no contrato publico (placeholder).
          schema:
            type: string
            example: 'nfe_123'
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          description: Resposta placeholder de consulta de NF-e.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NFePlaceholderResponse'
              examples:
                placeholder:
                  value:
                    id: nfe_123
                    status: placeholder
components:
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      description: |
        Esquema alvo da API publica (planejado/arquitetado). A implementacao completa sera entregue nas MTs de OAuth.
        Fluxo principal: Authorization Code + PKCE para apps de terceiros.
      flows:
        authorizationCode:
          authorizationUrl: https://erp.lompa.com.br/oauth/authorize
          tokenUrl: https://erp.lompa.com.br/oauth/token
          scopes:
            company:read: Leitura de dados de empresa expostos na API publica
            fiscal:read: Leitura de configuracoes fiscais e naturezas
            fiscal:write: Alteracao de configuracoes fiscais suportadas pela API publica
            marketplace:ml:read: Leitura de status de integracao Mercado Livre
            marketplace:ml:write: Operacoes de conexao/desconexao Mercado Livre
  parameters:
    XRequestId:
      name: X-Request-Id
      in: header
      required: false
      description: |
        Identificador de correlacao opcional enviado pelo cliente.
        Quando enviado, a API publica deve ecoar esse valor em respostas de erro.
      schema:
        type: string
        example: req-abc-123
  headers:
    XRequestId:
      description: Identificador de correlacao da requisicao.
      schema:
        type: string
        example: 8bb8d1d3-b4e9-4f59-9608-1fdf7ee6f060
  schemas:
    PublicErrorResponse:
      type: object
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          example: INVALID_CNPJ
        message:
          type: string
          example: CNPJ deve conter 14 dígitos numéricos
        details:
          description: Contexto adicional estruturado (opcional).
          nullable: true
        request_id:
          type: string
          example: 8bb8d1d3-b4e9-4f59-9608-1fdf7ee6f060
    CompanyLookupPlaceholderResponse:
      type: object
      required:
        - cnpj
        - status
      properties:
        cnpj:
          type: string
          example: '12345678000199'
        status:
          type: string
          example: placeholder - consulta CNPJ será implementada
    NFeCreatePlaceholderResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: NF-e creation placeholder
    NFePlaceholderResponse:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          example: nfe_123
        status:
          type: string
          example: placeholder
