Getting Started

1. Identifique a sua direção de integração

Antes de escrever qualquer linha de código, confirme qual lado você está construindo. Este é o erro mais comum na primeira semana de integração.

Você é	Implementa	Consome
Parceiro de varejo	Partner PDV API — 8 endpoints	Sales Authorization API — 1 endpoint
Levfone	Sales Authorization API	Partner PDV API

2. Ambientes

Ambiente	Base URL Levfone	Base URL PDV Parceiro
Sandbox	https://api.sandbox.levfone.com/v1	Fornecido pelo parceiro
Produção	https://api.levfone.com/v1	Fornecido pelo parceiro

O sandbox usa dados sintéticos e nunca gera contrato real. CPFs de teste são fornecidos no onboarding.

3. Credenciais

Você recebe um par client_id / client_secret por ambiente. Eles não são intercambiáveis entre sandbox e produção.

Nunca versione o client_secret

Guarde em cofre de segredos — Secret Manager, Vault ou equivalente. Nunca em código, nunca em variável de ambiente commitada, nunca em coleção Postman compartilhada.

4. Primeira chamada

Obtenha um token:

curl -X POST https://api.sandbox.levfone.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$LEVFONE_CLIENT_ID" \
  -d "client_secret=$LEVFONE_CLIENT_SECRET" \
  -d "scope=sales:authorize"

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "sales:authorize"
}

Autorize uma venda:

curl -X POST https://api.sandbox.levfone.com/v1/sales/authorize \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: $(uuidgen)" \
  -H "X-Correlation-Id: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "taxId": "12345678909",
    "storeId": "ST-0042",
    "planId": "PL-CTRL-25",
    "imei": "356938035643809",
    "items": [
      {
        "sku": "SKU-9912",
        "productType": "SMARTPHONE",
        "name": "Smartphone 128GB",
        "quantity": 1,
        "unitPrice": { "amount": 129900, "currency": "BRL" },
        "totalPrice": { "amount": 129900, "currency": "BRL" }
      }
    ],
    "services": [
      {
        "serviceId": "SV-EW12",
        "type": "EXTENDED_WARRANTY",
        "price": { "amount": 19900, "currency": "BRL" }
      }
    ],
    "totals": {
      "productsTotal": { "amount": 129900, "currency": "BRL" },
      "servicesTotal": { "amount": 19900, "currency": "BRL" },
      "grandTotal":    { "amount": 149800, "currency": "BRL" }
    }
  }'

{
  "success": true,
  "message": "Venda autorizada.",
  "timestamp": "2026-07-23T14:32:10.412Z",
  "requestId": "7f3c1e8a-2b44-4d19-9f0e-51a2c8d7b6e3",
  "data": {
    "authorized": true,
    "authorizationId": "auth_01J8XK4T7ZQ9",
    "status": "AUTHORIZED",
    "expiresAt": "2026-07-23T14:47:10.412Z",
    "message": "Venda autorizada. Conclua o faturamento."
  },
  "error": null
}

5. Três coisas que quebram na primeira integração

Valores como float. 1299.90 não existe nesta API. Todo valor é inteiro em centavos dentro de um objeto Money: { "amount": 129900, "currency": "BRL" }. Ponto flutuante em sistema de crédito produz divergência de reconciliação meses depois, no fechamento.

Recusa de crédito tratada como erro. Proposta reprovada retorna HTTP 200 com authorized: false. Se o seu código dispara alerta em status != 200, ele vai alertar toda vez que um cliente for reprovado. Erro HTTP significa problema na requisição, não decisão de crédito.

Totais que não fecham. grandTotal deve ser exatamente a soma de items[].totalPrice mais services[].price. Um centavo de diferença retorna total_inconsistent. A Levfone não arredonda.

6. Checklist de homologação

• Token obtido e renovado automaticamente antes de expires_in
• X-Request-Id único por chamada, X-Correlation-Id único por jornada
• Idempotency-Key em toda operação de escrita
• Todos os valores em centavos, sem float em nenhum ponto do código
• authorized: false tratado como fluxo de negócio, não como falha
• Faturamento bloqueado até authorized: true
• expiresAt respeitado — autorização vencida não pode ser faturada
• Confirmação de faturamento enviada via POST /sales/{id}/confirm
• Cancelamento notificado com reason correto
• Nenhum dado pessoal em query string ou log de aplicação

7. Próximos passos

• Authentication — as duas camadas de autenticação
• Business Rules — as onze regras de negócio
• Swagger UI — testar contra o sandbox