openapi: 3.1.0

info:
  title: Levfone Connect — Sales Authorization API
  version: "1.0.0"
  summary: API implementada pela Levfone e consumida pelo PDV Parceiro.
  description: |
    # Sales Authorization API

    Esta é a **única** API do Levfone Connect implementada pela Levfone. O PDV
    Parceiro a consome no momento em que o vendedor seleciona **Levfone** como
    forma de pagamento.

    ## Direção de integração

    | Papel | Sistema |
    |---|---|
    | Provedor (implementa) | Levfone |
    | Consumidor (chama) | PDV Parceiro |

    ## Ciclo de vida da autorização

    ```
    authorize  ──►  AUTHORIZED (com TTL)  ──►  confirm  ──►  CONFIRMED
                          │                                      │
                          ├──► expira (TTL)  ──► EXPIRED         └──► cancel ──► CANCELLED
                          └──► cancel        ──► CANCELLED
    ```

    O `authorizationId` **expira**. Se o PDV Parceiro não confirmar o faturamento
    dentro do TTL, a autorização é invalidada e a proposta de crédito volta a ficar
    disponível. O TTL padrão é de **15 minutos** e vem em `expiresAt`.

    ## Idempotência

    `POST /sales/authorize` **exige** o header `Idempotency-Key`. Repetir a mesma
    chave dentro de 24 horas retorna a resposta original sem reprocessar — protege
    contra timeout de rede, retry automático e duplo clique do vendedor.

  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://api.sandbox.levfone.com/v1
    description: Sandbox
  - url: https://api.levfone.com/v1
    description: Produção

tags:
  - name: Authentication
    description: Emissão de token de acesso para o PDV Parceiro.
  - name: Authorization
    description: Autorização, confirmação e cancelamento de venda financiada.

security:
  - levfoneOAuth: []

paths:

  /oauth/token:
    post:
      tags: [Authentication]
      operationId: issueLevfoneToken
      summary: Emite token de acesso para o PDV Parceiro
      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: ["sales:authorize"] }
      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" }

  /sales/authorize:
    post:
      tags: [Authorization]
      operationId: authorizeSale
      summary: Autoriza uma venda financiada pela Levfone
      description: |
        Chamada pelo PDV Parceiro **após** o carrinho estar montado e a forma de
        pagamento Levfone selecionada.

        ### Chamada única e autocontida

        Não há passo prévio obrigatório. O PDV pede a autorização e recebe ou a
        autorização ou o motivo da recusa, em uma única ida e volta.

        A Levfone **não** consulta o PDV Parceiro durante o processamento desta
        chamada. O PDV é a fonte da verdade sobre estoque e é ele quem está
        afirmando o IMEI nesta requisição — reconsultá-lo seria circular. A
        validação ocorre contra os registros da própria Levfone. Ver ADR-007.

        ### Ordem de validação

        1. Existe proposta **aprovada e vigente** para o CPF na loja informada,
           ou proposta reaproveitável por troca (ver ADR-008).
        2. O `planId` corresponde ao plano da proposta.
        3. Os produtos e serviços estão contemplados pela proposta.
        4. O **valor total** confere com o valor aprovado.
        5. O IMEI tem formato válido e não está vinculado a outro contrato ativo.

        **O PDV Parceiro só pode concluir o faturamento após `authorized: true`.**

        ### Troca

        Se esta requisição for a nova venda de uma troca, a proposta original é
        reaproveitada **sem nova análise de crédito**. A Levfone infere a troca —
        o PDV Parceiro não envia nada diferente e não muda nada no seu fluxo.
        Condições em ADR-008.

        ### Reconciliação de valores

        O campo `totals.grandTotal` deve ser **exatamente** a soma de
        `items[].totalPrice` + `services[].price`. Divergência de qualquer centavo
        retorna `total_mismatch` — a Levfone não arredonda nem ajusta.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XCorrelationId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AuthorizationRequest" }
      responses:
        "200":
          description: |
            Requisição processada. Verifique `data.authorized` — uma **recusa de
            crédito é `200`**, não erro. Códigos 4xx indicam problema na requisição.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AuthorizationResult" }
              examples:
                aprovada:
                  summary: Venda autorizada
                  value:
                    success: true
                    message: "Venda autorizada."
                    timestamp: "2026-07-23T14:32:10.412Z"
                    data:
                      authorized: true
                      authorizationId: "auth_01J8XK4T7ZQ9"
                      status: AUTHORIZED
                      expiresAt: "2026-07-23T14:47:10.412Z"
                      message: "Venda autorizada. Conclua o faturamento."
                    error: null
                recusada:
                  summary: Venda não autorizada
                  value:
                    success: true
                    message: "Venda não autorizada."
                    timestamp: "2026-07-23T14:32:10.412Z"
                    data:
                      authorized: false
                      authorizationId: null
                      status: DECLINED
                      declineReason: total_mismatch
                      message: "Valor do carrinho difere do valor aprovado na proposta."
                    error: null
        "401": { $ref: "#/components/responses/Unauthorized" }
        "409":
          description: |
            `Idempotency-Key` reutilizada com corpo de requisição diferente.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Envelope" }
        "422": { $ref: "#/components/responses/UnprocessableEntity" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /sales/{authorizationId}/confirm:
    post:
      tags: [Authorization]
      operationId: confirmSale
      summary: Confirma o faturamento da venda autorizada
      description: |
        Notifica a Levfone de que a venda foi **efetivamente faturada** no PDV
        Parceiro, encerrando o ciclo da autorização.

        Este endpoint é **recomendado, não obrigatório**. Se o PDV Parceiro não o
        implementar, a Levfone recorre ao polling de `POST /sales/search` na
        Partner PDV API. A confirmação ativa é preferível: elimina a janela em que
        o crédito está comprometido sem que a Levfone saiba o desfecho, e reduz
        drasticamente o volume de polling. Ver ADR-005.
      parameters:
        - $ref: "#/components/parameters/AuthorizationIdPath"
        - $ref: "#/components/parameters/IdempotencyKey"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XCorrelationId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [saleNumber, invoiceNumber, nfeAccessKey, invoicedAt]
              properties:
                saleNumber: { type: string }
                orderNumber: { type: string }
                invoiceNumber: { type: string }
                nfeAccessKey:
                  type: string
                  pattern: "^[0-9]{44}$"
                invoicedAt: { type: string, format: date-time }
      responses:
        "200":
          description: Faturamento registrado
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          authorizationId: { type: string }
                          status: { type: string, const: CONFIRMED }
                          contractId:
                            type: string
                            description: Identificador do crediário formalizado.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: Autorização expirada ou já em estado terminal.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Envelope" }

  /sales/{authorizationId}/cancel:
    post:
      tags: [Authorization]
      operationId: cancelSale
      summary: Notifica o cancelamento de uma venda
      description: |
        Notifica a Levfone de que a venda foi cancelada no PDV Parceiro.

        **A Levfone nunca inicia um cancelamento.** O gatilho é sempre o vendedor,
        no PDV. Este endpoint apenas comunica um cancelamento **já efetivado** —
        pedido cancelado, nota cancelada e estoque liberado.

        A Levfone confirma o cancelamento contra `POST /sales/search` antes de
        cancelar o financiamento. Divergência entre a notificação e a consulta faz
        prevalecer **a consulta**.

        ### Troca

        Não existe endpoint de troca. Se o PDV Parceiro trata troca como
        cancelamento + nova venda, a Levfone faz o mesmo: `cancel` seguido de novo
        `authorize`.

        O valor `reason: EXCHANGE` é o **gatilho do reaproveitamento da proposta**.
        Cancelamento marcado como troca permite que o novo `authorize` reutilize a
        aprovação original sem nova análise de crédito, dentro dos limites do
        ADR-008. Qualquer outro `reason` encerra a proposta.

        Se o PDV Parceiro não distingue troca de cancelamento comum, envie
        `EXCHANGE` sempre que houver venda subsequente ao cliente na mesma visita.
      parameters:
        - $ref: "#/components/parameters/AuthorizationIdPath"
        - $ref: "#/components/parameters/IdempotencyKey"
        - $ref: "#/components/parameters/XRequestId"
        - $ref: "#/components/parameters/XCorrelationId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [cancelledAt, reason]
              properties:
                cancelledAt: { type: string, format: date-time }
                reason:
                  type: string
                  enum: [CUSTOMER_REQUEST, EXCHANGE, OPERATIONAL_ERROR, FRAUD_SUSPICION, OTHER]
                notes: { type: string, maxLength: 500 }
      responses:
        "200":
          description: Cancelamento registrado
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          authorizationId: { type: string }
                          status: { type: string, const: CANCELLED }
                          financingCancelled:
                            type: boolean
                            description: |
                              `false` enquanto a Levfone ainda não confirmou o
                              cancelamento via `POST /sales/search`.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

components:

  securitySchemes:
    levfoneOAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.sandbox.levfone.com/v1/oauth/token
          scopes:
            "sales:authorize": Autorizar, confirmar e cancelar vendas financiadas

  parameters:
    AuthorizationIdPath:
      name: authorizationId
      in: path
      required: true
      schema: { type: string, maxLength: 64 }
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: |
        UUID v4 gerado pelo PDV Parceiro. Retenção de 24 horas.
      schema: { type: string, format: uuid }
    XRequestId:
      name: X-Request-Id
      in: header
      required: true
      schema: { type: string, format: uuid }
    XCorrelationId:
      name: X-Correlation-Id
      in: header
      required: true
      schema: { type: string, format: uuid }

  schemas:

    Envelope:
      type: object
      required: [success, message, timestamp]
      properties:
        success: { type: boolean }
        message: { type: string }
        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, examples: ["proposal_not_found"] }
        legacyCode: { type: string, pattern: "^LF[0-9]{4}$" }
        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]
      properties:
        amount: { type: integer, description: Valor em centavos. }
        currency: { type: string, const: BRL }

    AuthorizationRequest:
      type: object
      required: [taxId, storeId, planId, imei, items, totals]
      properties:
        taxId:
          type: string
          pattern: "^[0-9]{11}$"
          description: CPF do cliente, sem máscara.
        storeId: { type: string }
        sellerId: { type: string }
        planId: { type: string }
        imei:
          type: string
          pattern: "^[0-9]{15}$"
          description: IMEI do smartphone financiado.
        items:
          type: array
          minItems: 1
          items: { $ref: "#/components/schemas/CartItem" }
        services:
          type: array
          items: { $ref: "#/components/schemas/CartService" }
        totals: { $ref: "#/components/schemas/CartTotals" }

    CartItem:
      type: object
      required: [sku, quantity, unitPrice, totalPrice]
      properties:
        sku: { type: string }
        productType: { type: string, enum: [SMARTPHONE, ACCESSORY] }
        name: { type: string }
        quantity: { type: integer, minimum: 1 }
        unitPrice: { $ref: "#/components/schemas/Money" }
        totalPrice: { $ref: "#/components/schemas/Money" }

    CartService:
      type: object
      required: [serviceId, price]
      properties:
        serviceId: { type: string }
        name: { type: string }
        type: { type: string, enum: [EXTENDED_WARRANTY, INSURANCE, PROTECTION] }
        price: { $ref: "#/components/schemas/Money" }

    CartTotals:
      type: object
      required: [productsTotal, grandTotal]
      properties:
        productsTotal: { $ref: "#/components/schemas/Money" }
        servicesTotal: { $ref: "#/components/schemas/Money" }
        discountTotal: { $ref: "#/components/schemas/Money" }
        grandTotal: { $ref: "#/components/schemas/Money" }

    AuthorizationResult:
      type: object
      required: [authorized, status, message]
      properties:
        authorized: { type: boolean }
        authorizationId:
          oneOf:
            - type: string
            - type: "null"
          description: Presente apenas quando `authorized` é `true`.
        status:
          type: string
          enum: [AUTHORIZED, DECLINED, CONFIRMED, CANCELLED, EXPIRED]
        expiresAt:
          oneOf:
            - type: string
              format: date-time
            - type: "null"
        declineReason:
          type: string
          description: Código semântico do motivo da recusa.
          examples: ["proposal_not_found", "total_mismatch", "imei_already_financed"]
        message:
          type: string
          description: Texto pronto para exibição ao vendedor.

  responses:
    Unauthorized:
      description: Token ausente, inválido ou expirado.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Envelope" }
    NotFound:
      description: Autorização não encontrada.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Envelope" }
    UnprocessableEntity:
      description: Requisição 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" }