Authentication

O Levfone Connect usa duas camadas de autenticação, com propósitos distintos. Confundi-las é a causa mais frequente de erro 401 na integração inicial.

Camada	Endpoint	O que autentica	Validade
Sistema	`POST /oauth/token`	A aplicação	1 hora
Vendedor	`POST /sellers/session`	O funcionário e sua loja	Definida pelo PDV Parceiro

Camada 1 — Autenticação de sistema

OAuth 2.0 client_credentials, conforme RFC 6749 §4.4. Autentica a aplicação, não a pessoa.

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=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=sales:authorize"

Escopos

Escopo	API	Permite
`catalog:read`	Partner PDV	Planos, produtos e serviços
`inventory:read`	Partner PDV	Consulta de IMEI
`sales:read`	Partner PDV	Status de venda
`sales:authorize`	Sales Authorization	Autorizar, confirmar e cancelar

Solicite apenas os escopos que você usa. Escopo excedente é achado de auditoria.

Renovação

Renove o token antes de expires_in, com margem de pelo menos 60 segundos. Não renove a cada chamada: isso multiplica o custo por nada e derruba você no rate limit de emissão.

Camada 2 — Sessão do vendedor

Identifica o funcionário e retorna o contexto de loja. Implementada pelo PDV Parceiro, consumida pela Levfone.

curl -X POST https://{host}/v1/sellers/session \
  -H "Authorization: Bearer $SYSTEM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: $(uuidgen)" \
  -H "X-Correlation-Id: $(uuidgen)" \
  -d '{ "username": "vendedor.1234", "password": "..." }'

{
  "success": true,
  "message": "",
  "timestamp": "2026-07-23T14:10:02.118Z",
  "data": {
    "sellerId": "SL-8891",
    "sellerName": "Vendedor Exemplo",
    "taxId": "12345678909",
    "storeId": "ST-0042",
    "storeName": "Loja Exemplo",
    "storeCnpj": "12345678000199",
    "storeAddress": {
      "street": "Av. Paulista, 1000, Sala 12",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100"
    },
    "role": "SELLER",
    "accessToken": "sess_...",
    "expiresAt": "2026-07-23T22:10:02.118Z"
  },
  "error": null
}

O storeId é obrigatório em todas as chamadas seguintes de catálogo, estoque e vendas. Chamada sem ele retorna store_context_required.

O taxId (CPF do vendedor, sem máscara) é o que a Levfone usa para vincular a sessão ao cadastro interno do vendedor — o PDV Parceiro precisa ter esse dado disponível para retorná-lo.

storeCnpj e storeAddress (logradouro, cidade, UF, CEP — todos obrigatórios) identificam a loja para fins de cadastro e contrato do lado da Levfone. O PDV Parceiro precisa ter esses dados de cadastro da loja disponíveis para devolvê-los nesta mesma resposta.

Tratamento da credencial

Nesta versão a credencial do vendedor trafega pela Levfone. Isso é uma decisão consciente e temporária, com restrições contratuais:

A senha é writeOnly. Nunca é persistida pela Levfone, em nenhum meio.
Nunca é registrada em log, nem em log de depuração, nem em APM.
É descartada imediatamente após o encaminhamento.
TLS 1.2 ou superior é obrigatório. mTLS é recomendado.

Caminho para a v2

A v2 substitui o encaminhamento de credencial por OIDC Authorization Code + PKCE hospedado pelo PDV Parceiro: o vendedor autentica em tela do próprio PDV e a senha nunca passa pela Levfone. Parceiros que já suportam OIDC podem adotar o fluxo antecipadamente — fale com o time de integração.

Headers obrigatórios

Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
X-Request-Id: <uuid-v4>
X-Correlation-Id: <uuid-v4>
Idempotency-Key: <uuid-v4>

Header	Quando	Papel
`X-Request-Id`	Toda chamada	Identifica uma requisição. Novo a cada retry.
`X-Correlation-Id`	Toda chamada	Identifica uma jornada de venda inteira. O mesmo do início ao fim.
`Idempotency-Key`	POST de escrita	Impede execução dupla. Retenção de 24 horas.

A distinção entre os dois primeiros importa no suporte: com o X-Correlation-Id reconstruímos a jornada completa do cliente em segundos. Sem ele, cada chamada é um evento isolado e a investigação leva horas.

Erros de autenticação

Código	HTTP	Causa provável
`missing_token`	401	Header `Authorization` ausente
`invalid_token`	401	Token malformado ou assinatura inválida
`expired_token`	401	Renove antes de `expires_in`
`insufficient_scope`	403	Token válido, escopo insuficiente
`invalid_client`	401	Credencial de outro ambiente
`store_context_required`	400	`storeId` ausente

Catálogo completo em Errors.

Camada 1 — Autenticação de sistema​

Escopos​

Renovação​

Camada 2 — Sessão do vendedor​

Tratamento da credencial​

Headers obrigatórios​

Erros de autenticação​