Pular para o conteúdo principal
API docs by Redocly

Levfone Connect — Sales Authorization 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 pela Levfone e consumida pelo PDV Parceiro.

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.

Authentication

Emissão de token de acesso para o PDV Parceiro.

Emite token de acesso para o PDV Parceiro

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"
}

Authorization

Autorização, confirmação e cancelamento de venda financiada.

Autoriza uma venda financiada pela Levfone

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.

Authorizations:
levfoneOAuth
header Parameters
Idempotency-Key
required
string <uuid>

UUID v4 gerado pelo PDV Parceiro. Retenção de 24 horas.

X-Request-Id
required
string <uuid>
X-Correlation-Id
required
string <uuid>
Request Body schema: application/json
required
taxId
required
string^[0-9]{11}$

CPF do cliente, sem máscara.

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

IMEI do smartphone financiado.

required
Array of objects (CartItem) non-empty
required
object (CartTotals)
sellerId
string
Array of objects (CartService)

Responses

Response Schema: application/json
success
required
boolean
message
required
string
timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Request samples

Content type
application/json
{
  • "taxId": "string",
  • "storeId": "string",
  • "sellerId": "string",
  • "planId": "string",
  • "imei": "string",
  • "items": [
    ],
  • "services": [
    ],
  • "totals": {
    }
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "Venda autorizada.",
  • "timestamp": "2026-07-23T14:32:10.412Z",
  • "data": {
    },
  • "error": null
}

Confirma o faturamento da venda autorizada

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.

Authorizations:
levfoneOAuth
path Parameters
authorizationId
required
string <= 64 characters
header Parameters
Idempotency-Key
required
string <uuid>

UUID v4 gerado pelo PDV Parceiro. Retenção de 24 horas.

X-Request-Id
required
string <uuid>
X-Correlation-Id
required
string <uuid>
Request Body schema: application/json
required
saleNumber
required
string
invoiceNumber
required
string
nfeAccessKey
required
string^[0-9]{44}$
invoicedAt
required
string <date-time>
orderNumber
string

Responses

Response Schema: application/json
success
required
boolean
message
required
string
timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Request samples

Content type
application/json
{
  • "saleNumber": "string",
  • "orderNumber": "string",
  • "invoiceNumber": "string",
  • "nfeAccessKey": "string",
  • "invoicedAt": "2019-08-24T14:15:22Z"
}

Response samples

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

Notifica o cancelamento de uma venda

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.

Authorizations:
levfoneOAuth
path Parameters
authorizationId
required
string <= 64 characters
header Parameters
Idempotency-Key
required
string <uuid>

UUID v4 gerado pelo PDV Parceiro. Retenção de 24 horas.

X-Request-Id
required
string <uuid>
X-Correlation-Id
required
string <uuid>
Request Body schema: application/json
required
cancelledAt
required
string <date-time>
reason
required
string
Enum: "CUSTOMER_REQUEST" "EXCHANGE" "OPERATIONAL_ERROR" "FRAUD_SUSPICION" "OTHER"
notes
string <= 500 characters

Responses

Response Schema: application/json
success
required
boolean
message
required
string
timestamp
required
string <date-time>
requestId
string <uuid>
object
Error (object) or null

Request samples

Content type
application/json
{
  • "cancelledAt": "2019-08-24T14:15:22Z",
  • "reason": "CUSTOMER_REQUEST",
  • "notes": "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": {
    }
}