Pular para o conteúdo principal
API docs by Redocly

Levfone Connect — Partner PDV API (1.0.0)

Download OpenAPI specification:Download

Levfone Connect — Partner Integrations: connect@levfone.com URL: https://developer.levfone.com/support License: LicenseRef-Levfone-Proprietary

API implementada pelo PDV Parceiro e consumida pela Levfone.

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.

Authentication

Autenticação sistema-a-sistema e sessão do vendedor.

Emite token de acesso sistema-a-sistema

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.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"
client_id
required
string
client_secret
required
string <password>
scope
string

Responses

Response Schema: application/json
access_token
required
string
token_type
required
string
Value: "Bearer"
expires_in
required
integer
scope
string

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "string"
}

Identifica o vendedor e retorna o contexto de loja

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.

Authorizations:
partnerOAuth
header Parameters
X-Request-Id
required
string <uuid>

UUID v4 único por requisição.

X-Correlation-Id
required
string <uuid>

UUID v4 que agrupa todas as chamadas de uma mesma jornada de venda.

Request Body schema: application/json
required
username
required
string <= 120 characters
password
required
string <password>

Responses

Response Schema: application/json
success
required
boolean
message
required
string

Mensagem apta a ser exibida ao vendedor. Vazia em sucesso silencioso.

timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Request samples

Content type
application/json
{
  • "username": "vendedor.1234",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "data": {
    },
  • "error": {
    }
}

Catalog

Planos, produtos e serviços disponíveis na loja.

Lista os planos de operadora disponíveis na loja

Authorizations:
partnerOAuth
query Parameters
storeId
required
string <= 64 characters

Identificador da loja, obtido em POST /sellers/session.

header Parameters
X-Request-Id
required
string <uuid>

UUID v4 único por requisição.

X-Correlation-Id
required
string <uuid>

UUID v4 que agrupa todas as chamadas de uma mesma jornada de venda.

Responses

Response Schema: application/json
success
required
boolean
message
required
string

Mensagem apta a ser exibida ao vendedor. Vazia em sucesso silencioso.

timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "data": {
    },
  • "error": {
    }
}

Lista o catálogo de smartphones elegíveis ao plano

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.

Authorizations:
partnerOAuth
query Parameters
storeId
required
string <= 64 characters

Identificador da loja, obtido em POST /sellers/session.

planId
required
string <= 64 characters
page
integer >= 1
Default: 1
pageSize
integer [ 1 .. 200 ]
Default: 50
header Parameters
X-Request-Id
required
string <uuid>

UUID v4 único por requisição.

X-Correlation-Id
required
string <uuid>

UUID v4 que agrupa todas as chamadas de uma mesma jornada de venda.

Responses

Response Schema: application/json
success
required
boolean
message
required
string

Mensagem apta a ser exibida ao vendedor. Vazia em sucesso silencioso.

timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "data": {
    },
  • "error": {
    }
}

Consulta produto por código de barras

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.

Authorizations:
partnerOAuth
query Parameters
storeId
required
string <= 64 characters

Identificador da loja, obtido em POST /sellers/session.

barcode
required
string [ 6 .. 32 ] characters
Examples:
  • barcode=7891234567895 -
header Parameters
X-Request-Id
required
string <uuid>

UUID v4 único por requisição.

X-Correlation-Id
required
string <uuid>

UUID v4 que agrupa todas as chamadas de uma mesma jornada de venda.

Responses

Response Schema: application/json
success
required
boolean
message
required
string

Mensagem apta a ser exibida ao vendedor. Vazia em sucesso silencioso.

timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "data": {
    },
  • "error": {
    }
}

Lista garantias, seguros e proteções aplicáveis a um SKU

Authorizations:
partnerOAuth
query Parameters
storeId
required
string <= 64 characters

Identificador da loja, obtido em POST /sellers/session.

sku
required
string <= 64 characters

SKU do smartphone ao qual o serviço será vinculado.

header Parameters
X-Request-Id
required
string <uuid>

UUID v4 único por requisição.

X-Correlation-Id
required
string <uuid>

UUID v4 que agrupa todas as chamadas de uma mesma jornada de venda.

Responses

Response Schema: application/json
success
required
boolean
message
required
string

Mensagem apta a ser exibida ao vendedor. Vazia em sucesso silencioso.

timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "data": {
    },
  • "error": {
    }
}

Inventory

Validação de IMEI e disponibilidade em estoque.

Resolve o IMEI para produto e indica disponibilidade

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.

Authorizations:
partnerOAuth
query Parameters
storeId
required
string <= 64 characters

Identificador da loja, obtido em POST /sellers/session.

imei
required
string^[0-9]{15}$
Examples:
  • imei=356938035643809 -
header Parameters
X-Request-Id
required
string <uuid>

UUID v4 único por requisição.

X-Correlation-Id
required
string <uuid>

UUID v4 que agrupa todas as chamadas de uma mesma jornada de venda.

Responses

Response Schema: application/json
success
required
boolean
message
required
string

Mensagem apta a ser exibida ao vendedor. Vazia em sucesso silencioso.

timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "data": {
    },
  • "error": {
    }
}

Sales

Consulta de status de venda, faturamento e cancelamento.

Consulta o status de faturamento e cancelamento de uma venda

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.

Authorizations:
partnerOAuth
header Parameters
X-Request-Id
required
string <uuid>

UUID v4 único por requisição.

X-Correlation-Id
required
string <uuid>

UUID v4 que agrupa todas as chamadas de uma mesma jornada de venda.

Request Body schema: application/json
required
One of
taxId
required
string^[0-9]{11}$

CPF sem máscara.

imei
string^[0-9]{15}$

Responses

Response Schema: application/json
success
required
boolean
message
required
string

Mensagem apta a ser exibida ao vendedor. Vazia em sucesso silencioso.

timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Request samples

Content type
application/json
{
  • "taxId": "string",
  • "imei": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "data": {
    },
  • "error": {
    }
}