Business Rules

As onze regras que governam a integração. Elas são contratuais: um parceiro homologado é um parceiro que implementa todas.

RN-01 — Contexto de loja obrigatório

O storeId retornado na sessão do vendedor é obrigatório em toda chamada de catálogo, estoque e venda. Chamada sem storeId é rejeitada com store_context_required.

RN-02 — Validação de valores na autorização

A Levfone compara o grandTotal do carrinho com o valor aprovado na proposta.

• A soma de items[].totalPrice + services[].price deve ser exatamente igual a totals.grandTotal. Não há arredondamento.
• Divergência entre carrinho e proposta retorna total_mismatch.
• A Levfone não ajusta valores. Se o carrinho mudou, o PDV refaz a chamada.

RN-03 — Cor não é atributo de catálogo

O catálogo não retorna cor. A Levfone financia o SKU; a variação de cor é resolvida na leitura do IMEI, no ato da venda.

Ponto de atenção. Se o PDV Parceiro trabalha com SKU distinto por cor (comum em varejo de telecom), o catálogo já resolve a variação e esta regra é inócua. Se o SKU é único e a cor é atributo separado, o cliente escolhe cor sem que a Levfone saiba qual — e uma troca por cor errada vira cancelamento. Vale confirmar com o parceiro qual dos dois modelos ele usa.

RN-04 — Código de barras é universal, exceto para serviços

GET /products/barcode atende smartphone e qualquer acessório: capinha, película, cabo, carregador, fone. Garantias e seguros não têm código de barras e são obtidos por GET /services.

RN-05 — Consulta de IMEI é resolução, não decisão

GET /imei/validate resolve o IMEI para produto e informa disponibilidade. Ele não reserva, não garante e não decide. É consumido pela Levfone na sua própria jornada, antes de o carrinho existir.

A única decisão sobre a venda é POST /sales/authorize, que é uma chamada única e autocontida — sem passo prévio obrigatório e sem consulta de volta ao PDV Parceiro.

O campo message é exibido diretamente ao vendedor, sem tradução. Deve explicar o motivo em linguagem operacional — "IMEI pertence a outra loja", não "constraint violation on store_id".

RN-06 — Autorização expira

authorizationId tem TTL de 15 minutos. Após expiresAt, a autorização é inválida e o PDV deve solicitar nova autorização.

RN-07 — Recusa de crédito não é erro HTTP

Proposta reprovada retorna HTTP 200 com authorized: false e declineReason. Códigos 4xx e 5xx indicam problema técnico na requisição, não decisão de crédito.

RN-08 — Cancelamento é sempre iniciado no PDV

A Levfone nunca inicia cancelamento. Sequência obrigatória:

1. O vendedor cancela no PDV Parceiro.
2. O PDV cancela o pedido, cancela a nota e libera o estoque.
3. O PDV notifica a Levfone (POST /sales/{id}/cancel) — recomendado.
4. A Levfone confirma via POST /sales/search.
5. Somente após a confirmação na consulta, a Levfone cancela o financiamento.

Em divergência entre a notificação e a consulta, prevalece a consulta.

RN-09 — Troca segue o fluxo do PDV, sem nova análise

Não existe API de troca. A Levfone espelha exatamente o fluxo operacional do PDV Parceiro. Se o PDV trata troca como cancelamento + nova venda, a Levfone faz o mesmo.

A troca não dispara nova análise de crédito. A proposta aprovada original é reaproveitada na nova autorização, nos limites da RN-11.

O PDV Parceiro não muda nada no seu fluxo. Ele cancela e vende de novo, como já faz. A Levfone infere a troca.

RN-10 — Um IMEI, um contrato

Um IMEI não pode estar vinculado a mais de um financiamento ativo. Tentativa retorna imei_already_financed.

RN-11 — Reaproveitamento da proposta

Uma proposta aprovada é reaproveitada, sem nova análise, quando todas as condições abaixo se verificam:

#	Condição	Erro se falhar
1	Mesmo CPF e mesma loja	proposal_not_found
2	Autorização anterior em CANCELLED com reason: EXCHANGE	proposal_already_used
3	Dentro de 7 dias corridos da aprovação original	proposal_reuse_window_expired
4	Novo grandTotal ≤ valor aprovado	proposal_reuse_amount_exceeded
5	Proposta ainda não reutilizada (limite: 1)	proposal_reuse_limit_reached

Se qualquer condição falha, o fluxo cai em nova análise de crédito — que é o comportamento correto para o que não é uma troca.

Os parâmetros de janela, teto e limite de reutilizações são configuráveis sem alteração de contrato.

---

---

Resumo

#	Regra	Impacto
RN-01	Contexto de loja obrigatório	Toda chamada
RN-02	Valores validados sem arredondamento	Autorização
RN-03	Cor não é atributo de catálogo	Catálogo
RN-04	Código de barras universal, exceto serviços	Catálogo
RN-05	Consulta de IMEI é resolução, não decisão	Estoque
RN-06	Autorização expira em 15 minutos	Autorização
RN-07	Recusa de crédito é HTTP 200	Autorização
RN-08	Cancelamento sempre iniciado no PDV	Cancelamento
RN-09	Troca segue o PDV, sem nova análise	Troca
RN-10	Um IMEI, um contrato	Autorização
RN-11	Reaproveitamento da proposta	Troca