Levfone Connect — Partner PDV API (1.0.0)

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.

A Levfone capta CPF e senha na tela de login da Plataforma e encaminha para o PDV Parceiro autenticar — o PDV Parceiro é a fonte da verdade sobre credenciais de vendedor, a Levfone não mantém senha própria.

A resposta é sempre 200

O resultado da autenticação vai no campo data.status, não no código HTTP — mesmo padrão da Sales Authorization API (ver RN-07 em levfone-authorization-api.v1.yaml). Um 401 nesta chamada significa que o token sistema-a-sistema da Levfone (POST /oauth/token) é que é inválido ou expirado — não que o CPF/senha do vendedor está errado.

O storeId (dentro de data.session, presente apenas quando status: AUTHORIZED) é 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.

Recomendamos que a mensagem exibida ao vendedor seja igual para INVALID_PASSWORD e USER_NOT_FOUND (ex. "CPF ou senha incorretos") — o status já deixa os dois distinguíveis para log e suporte, sem expor ao usuário final se o CPF existe ou não no cadastro.

A Levfone consulta este endpoint uma vez por dia para manter seu próprio cadastro de vendedores e gerentes sincronizado.

Retorna apenas funcionários ativos. Um funcionário desligado ou inativado simplesmente deixa de aparecer na lista no dia seguinte — a Levfone detecta a saída pela ausência na sincronização, não é necessário nenhum evento ou campo explícito de desligamento.

A Levfone consulta este endpoint para manter seu próprio cadastro de lojas parceiras sincronizado — nome, endereço e CNPJ de cada loja.

A Levfone consulta este endpoint uma vez por dia e guarda o resultado em cache próprio — não é chamado por transação. Não inclua aqui nada que mude durante o dia (ex. estoque); isso fica em GET /products/barcode e GET /stock, consultados em tempo real.

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.

A Levfone consulta este endpoint uma vez por dia e guarda o catálogo em cache próprio — não é chamado por transação, por isso não retorna estoque (stock), que muda o dia inteiro. Estoque atual é sempre GET /products/barcode ou GET /stock, em tempo real.

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.

Chamado em tempo real, no momento em que o vendedor escaneia o produto — por isso a resposta inclui stock atual, diferente de GET /products (que é cache diário e não tem estoque).

A Levfone consulta este endpoint uma vez por dia e guarda o resultado em cache próprio — não é chamado por transação.

Chamado em tempo real, para saber quantas unidades de um SKU (já conhecido pelo catálogo sincronizado via GET /products) existem agora na loja — sem precisar escanear um código de barras. Use GET /products/barcode em vez deste quando o ponto de partida é a leitura física do produto, não o SKU.

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.

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.