openapi: 3.1.0
info:
  title: Levfone Connect — Partner PDV API
  version: 1.0.0
  summary: API implementada pelo PDV Parceiro e consumida pela Levfone.
  description: >
    # Partner PDV API


    Esta especificação define os endpoints que **o PDV Parceiro implementa** e
    que a

    **Levfone consome** durante a jornada de financiamento de smartphones no
    varejo.


    O fluxo inverso — a autorização de venda que o PDV Parceiro consome da
    Levfone —

    está especificado em `levfone-authorization-api.v1.yaml`.


    ## Direção de integração


    | Papel | Sistema |

    |---|---|

    | Provedor (implementa) | PDV Parceiro |

    | Consumidor (chama) | Levfone |


    ## Convenções


    - Todos os valores monetários trafegam como **inteiros em centavos**
    (`Money`).

    - Todas as respostas usam o envelope padrão Levfone Connect.

    - Todos os timestamps são **ISO 8601 em UTC** com milissegundos.

    - Toda requisição envia `X-Request-Id` e `X-Correlation-Id`.
  contact:
    name: Levfone Connect — Partner Integrations
    url: https://developer.levfone.com/support
    email: connect@levfone.com
  license:
    name: Proprietary — Levfone
    identifier: LicenseRef-Levfone-Proprietary
servers:
  - url: https://{host}/v1
    description: Ambiente do PDV Parceiro
    variables:
      host:
        default: sandbox.pdv-parceiro.example.com
        description: Host fornecido pelo PDV Parceiro (sandbox ou produção)
tags:
  - name: Authentication
    description: Autenticação sistema-a-sistema e sessão do vendedor.
  - name: Catalog
    description: Planos, produtos e serviços disponíveis na loja.
  - name: Inventory
    description: Validação de IMEI e disponibilidade em estoque.
  - name: Sales
    description: Consulta de status de venda, faturamento e cancelamento.
security:
  - partnerOAuth: []
paths:
  /oauth/token:
    post:
      tags:
        - Authentication
      operationId: issuePartnerToken
      summary: Emite token de acesso sistema-a-sistema
      description: |
        Autenticação **máquina-a-máquina** entre Levfone e PDV Parceiro,
        via OAuth 2.0 `client_credentials` (RFC 6749 §4.4).

        Este token identifica a **Levfone como aplicação**, não o vendedor.
        A identificação do vendedor é feita em `POST /sellers/session`.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  const: client_credentials
                client_id:
                  type: string
                client_secret:
                  type: string
                  format: password
                  writeOnly: true
                scope:
                  type: string
                  examples:
                    - catalog:read inventory:read sales:read
      responses:
        '200':
          description: Token emitido
          content:
            application/json:
              schema:
                type: object
                required:
                  - access_token
                  - token_type
                  - expires_in
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                    const: Bearer
                  expires_in:
                    type: integer
                    examples:
                      - 3600
                  scope:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /sellers/session:
    post:
      tags:
        - Authentication
      operationId: createSellerSession
      summary: Identifica o vendedor e retorna o contexto de loja
      description: >
        Cria uma sessão de vendedor no PDV Parceiro.


        O `storeId` retornado é **obrigatório em todas as chamadas
        subsequentes** de

        catálogo, estoque e vendas.


        > **Nota de segurança.** Nesta versão a credencial do vendedor trafega
        pela

        > Levfone (*credential passthrough*). A Levfone **não persiste a senha**
        em

        > nenhuma hipótese — o campo é `writeOnly`, nunca é logado e é
        descartado

        > imediatamente após o encaminhamento. O caminho recomendado para a v2 é

        > **OIDC Authorization Code + PKCE hospedado pelo PDV Parceiro**,
        eliminando

        > o trânsito da senha. Ver ADR-001.
      parameters:
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/XCorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  maxLength: 120
                  examples:
                    - vendedor.1234
                password:
                  type: string
                  format: password
                  writeOnly: true
      responses:
        '200':
          description: Sessão criada
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/SellerSession'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /plans:
    get:
      tags:
        - Catalog
      operationId: listPlans
      summary: Lista os planos de operadora disponíveis na loja
      parameters:
        - $ref: '#/components/parameters/StoreIdQuery'
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/XCorrelationId'
      responses:
        '200':
          description: Planos disponíveis
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          plans:
                            type: array
                            items:
                              $ref: '#/components/schemas/Plan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /products:
    get:
      tags:
        - Catalog
      operationId: listProducts
      summary: Lista o catálogo de smartphones elegíveis ao plano
      description: >
        Retorna os smartphones disponíveis na loja para o plano informado.


        A cor **não** é retornada: a Levfone financia o SKU, e a variação de cor
        é

        resolvida no ato da venda pela leitura do IMEI. Ver ADR-006.
      parameters:
        - $ref: '#/components/parameters/StoreIdQuery'
        - name: planId
          in: query
          required: true
          schema:
            type: string
            maxLength: 64
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/XCorrelationId'
      responses:
        '200':
          description: Catálogo retornado
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          products:
                            type: array
                            items:
                              $ref: '#/components/schemas/Product'
                          pagination:
                            $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /products/barcode:
    get:
      tags:
        - Catalog
      operationId: getProductByBarcode
      summary: Consulta produto por código de barras
      description: |
        Endpoint universal de leitura de código de barras. Atende smartphones e
        **qualquer acessório** (capinha, película, cabo, carregador, fone).

        Garantias e seguros **não** são retornados aqui — use `GET /services`.
      parameters:
        - $ref: '#/components/parameters/StoreIdQuery'
        - name: barcode
          in: query
          required: true
          schema:
            type: string
            minLength: 6
            maxLength: 32
          examples:
            ean13:
              value: '7891234567895'
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/XCorrelationId'
      responses:
        '200':
          description: Produto encontrado
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /services:
    get:
      tags:
        - Catalog
      operationId: listServices
      summary: Lista garantias, seguros e proteções aplicáveis a um SKU
      parameters:
        - $ref: '#/components/parameters/StoreIdQuery'
        - name: sku
          in: query
          required: true
          description: SKU do smartphone ao qual o serviço será vinculado.
          schema:
            type: string
            maxLength: 64
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/XCorrelationId'
      responses:
        '200':
          description: Serviços disponíveis
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          services:
                            type: array
                            items:
                              $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /imei/validate:
    get:
      tags:
        - Inventory
      operationId: validateImei
      summary: Resolve o IMEI para produto e indica disponibilidade
      description: >
        Resolve um IMEI lido pelo vendedor no aparelho SKU, marca, modelo,

        descrição e memória, e informa se está disponível na loja.


        O campo `message` é destinado à **exibição direta ao vendedor** e deve

        explicar o motivo da indisponibilidade em linguagem operacional.


        > **Este endpoint não é vinculante.** Ele não reserva o aparelho, não

        > garante disponibilidade e não decide nada. Serve à jornada da Levfone,

        > antes do carrinho existir, para saber qual produto está sendo

        > financiado.

        >

        > A única decisão sobre a venda é `POST /sales/authorize`, na

        > Sales Authorization API — uma chamada única e autocontida. Ver
        ADR-007.
      parameters:
        - $ref: '#/components/parameters/StoreIdQuery'
        - name: imei
          in: query
          required: true
          schema:
            type: string
            pattern: ^[0-9]{15}$
          examples:
            valid:
              value: '356938035643809'
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/XCorrelationId'
      responses:
        '200':
          description: Resultado da validação
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ImeiValidation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /sales/search:
    post:
      tags:
        - Sales
      operationId: searchSaleStatus
      summary: Consulta o status de faturamento e cancelamento de uma venda
      description: |
        Busca a venda por **CPF** ou **IMEI**. Exatamente um dos dois deve ser
        informado.

        Este endpoint é `POST` — e não `GET` — porque o CPF é dado pessoal e não
        pode trafegar em query string, onde seria persistido em logs de acesso,
        CDN e proxies. Ver ADR-004.

        A `nfeAccessKey` (chave de 44 dígitos) permite localizar e baixar a NF-e
        no portal da Receita Federal.
      parameters:
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/XCorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              oneOf:
                - required:
                    - taxId
                - required:
                    - imei
              properties:
                taxId:
                  type: string
                  pattern: ^[0-9]{11}$
                  description: CPF sem máscara.
                imei:
                  type: string
                  pattern: ^[0-9]{15}$
      responses:
        '200':
          description: Vendas encontradas
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          sales:
                            type: array
                            items:
                              $ref: '#/components/schemas/SaleStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  securitySchemes:
    partnerOAuth:
      type: oauth2
      description: OAuth 2.0 client credentials emitido pelo PDV Parceiro.
      flows:
        clientCredentials:
          tokenUrl: https://sandbox.pdv-parceiro.example.com/v1/oauth/token
          scopes:
            catalog:read: Leitura de planos, produtos e serviços
            inventory:read: Validação de IMEI e estoque
            sales:read: Consulta de status de venda
  parameters:
    StoreIdQuery:
      name: storeId
      in: query
      required: true
      description: Identificador da loja, obtido em `POST /sellers/session`.
      schema:
        type: string
        maxLength: 64
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    XRequestId:
      name: X-Request-Id
      in: header
      required: true
      description: UUID v4 único por requisição.
      schema:
        type: string
        format: uuid
    XCorrelationId:
      name: X-Correlation-Id
      in: header
      required: true
      description: UUID v4 que agrupa todas as chamadas de uma mesma jornada de venda.
      schema:
        type: string
        format: uuid
  schemas:
    Envelope:
      type: object
      required:
        - success
        - message
        - timestamp
      properties:
        success:
          type: boolean
        message:
          type: string
          description: >-
            Mensagem apta a ser exibida ao vendedor. Vazia em sucesso
            silencioso.
        timestamp:
          type: string
          format: date-time
        requestId:
          type: string
          format: uuid
        data:
          type: object
        error:
          oneOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >
            Código estável e semântico, em `snake_case`. Nunca muda entre
            versões.
          examples:
            - store_not_found
            - imei_not_in_stock
        legacyCode:
          type: string
          pattern: ^LF[0-9]{4}$
          description: Alias numérico para abertura de chamado no suporte.
          examples:
            - LF0042
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              issue:
                type: string
        docsUrl:
          type: string
          format: uri
    Money:
      type: object
      required:
        - amount
        - currency
      description: |
        Valor monetário em **unidade menor** (centavos), sempre inteiro.
        Ponto flutuante é proibido em toda a plataforma. Ver ADR-003.
      properties:
        amount:
          type: integer
          description: Valor em centavos.
          examples:
            - 129900
        currency:
          type: string
          const: BRL
    Pagination:
      type: object
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        totalItems:
          type: integer
        totalPages:
          type: integer
    SellerSession:
      type: object
      required:
        - sellerId
        - sellerName
        - taxId
        - storeId
        - storeName
        - storeCnpj
        - storeAddress
        - accessToken
        - expiresAt
      properties:
        sellerId:
          type: string
        sellerName:
          type: string
        taxId:
          type: string
          pattern: ^[0-9]{11}$
          description: |
            CPF do vendedor, sem máscara. Usado pela Levfone para vincular a
            sessão ao cadastro interno do vendedor.
        storeId:
          type: string
        storeName:
          type: string
        storeCnpj:
          type: string
          pattern: ^[0-9]{14}$
          description: CNPJ da loja, sem máscara.
        storeAddress:
          $ref: '#/components/schemas/Address'
        role:
          type: string
          examples:
            - SELLER
            - SUPERVISOR
            - MANAGER
        accessToken:
          type: string
          description: Token de sessão do vendedor, escopado à loja.
        expiresAt:
          type: string
          format: date-time
    Address:
      type: object
      required:
        - street
        - city
        - state
        - zipCode
      properties:
        street:
          type: string
          description: Logradouro completo, incluindo número e complemento.
          examples:
            - Av. Paulista, 1000, Sala 12
        city:
          type: string
          examples:
            - São Paulo
        state:
          type: string
          pattern: ^[A-Z]{2}$
          description: UF, duas letras maiúsculas.
          examples:
            - SP
        zipCode:
          type: string
          pattern: ^[0-9]{8}$
          description: CEP sem máscara e sem hífen.
          examples:
            - '01310100'
    Plan:
      type: object
      required:
        - planId
        - name
        - monthlyPrice
      properties:
        planId:
          type: string
        name:
          type: string
          examples:
            - Controle 25GB
        monthlyPrice:
          $ref: '#/components/schemas/Money'
    Product:
      type: object
      required:
        - sku
        - name
        - price
        - stock
      properties:
        sku:
          type: string
        productType:
          type: string
          enum:
            - SMARTPHONE
            - ACCESSORY
        name:
          type: string
        brand:
          type: string
        model:
          type: string
        description:
          type: string
        storage:
          type: string
          description: Capacidade de armazenamento, com unidade.
          examples:
            - 128GB
        price:
          $ref: '#/components/schemas/Money'
        stock:
          type: integer
          minimum: 0
    Service:
      type: object
      required:
        - serviceId
        - name
        - type
        - price
      properties:
        serviceId:
          type: string
        name:
          type: string
          examples:
            - Garantia Estendida 12 meses
        description:
          type: string
        type:
          type: string
          enum:
            - EXTENDED_WARRANTY
            - INSURANCE
            - PROTECTION
        price:
          $ref: '#/components/schemas/Money'
    ImeiValidation:
      type: object
      required:
        - imeiValid
        - inStock
      properties:
        imeiValid:
          type: boolean
        inStock:
          type: boolean
        sku:
          type: string
        name:
          type: string
        brand:
          type: string
        model:
          type: string
        description:
          type: string
        storage:
          type: string
        message:
          type: string
          description: Texto a ser exibido ao vendedor explicando a reprovação.
          examples:
            - IMEI pertence a outra loja.
    SaleStatus:
      type: object
      required:
        - status
        - saleNumber
        - saleDate
      properties:
        status:
          type: string
          enum:
            - PENDING
            - ACTIVE
            - CANCELLED
          description: |
            - `PENDING` — venda iniciada, ainda não faturada.
            - `ACTIVE` — venda faturada, NF-e emitida.
            - `CANCELLED` — venda cancelada e estoque liberado no PDV.
        saleNumber:
          type: string
        orderNumber:
          type: string
        invoiceNumber:
          type: string
        nfeAccessKey:
          type: string
          pattern: ^[0-9]{44}$
          description: Chave de acesso da NF-e (44 dígitos).
        saleDate:
          type: string
          format: date-time
        cancellationDate:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        message:
          type: string
  responses:
    Unauthorized:
      description: Token ausente, inválido ou expirado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
    NotFound:
      description: Recurso não encontrado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
    UnprocessableEntity:
      description: Requisição sintaticamente válida, mas semanticamente inválida.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
    TooManyRequests:
      description: Limite de requisições excedido.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'