Cupons, vales, pagamentos e NF-e

Além de vender, o seller (lojista) precisa decidir como recebe, que incentivos oferece e como emite nota fiscal. Esta seção agrupa essas capacidades de autoatendimento, todas restritas ao próprio seller: cupons, vales-presente, formas de pagamento, NF-e e a lista de planos.

Como funciona

Todas estas capacidades são do seller: ele as configura e elas valem só para os produtos dele. Nenhuma depende de aprovação do administrador (cupons, vales e formas de pagamento), exceto a escolha de plano, que é limitada pelos limites do plano.

1. Defina como o seller recebe

   Crie as formas de pagamento que ele oferece (PIX, boleto faturado...).

2. Crie incentivos

   Emita cupons (desconto por código) e vales-presente (crédito pré-pago).

3. Prepare a nota fiscal

   Informe os dados de emitente em NF-e para as notas saírem em nome do seller.

Conceitos-chave

Escopo do seller

O seller é identificado pelo token. Qualquer vendor_id enviado no corpo é ignorado; o registro é sempre do seller do token. Ler ou alterar um registro de outro seller responde como se ele não existisse (404).

Privilégios das sub-contas

Cupons, vales-presente, formas de pagamento e a configuração da NF-e exigem um privilégio de configurações (vendor_settings ou um dos específicos). A lista de notas exige o privilégio financeiro. O dono da loja passa em tudo.

Dinheiro

Centavos inteiros. Percentuais de cupom e de acréscimo em pontos-base. Os vales-presente mostram também uma cópia decimal em texto (amount_str) só por compatibilidade.

Ids

Cupons usam id inteiro; vales-presente e formas de pagamento usam UUID. Um UUID malformado hoje devolve 500, não 400.

Endpoints

Erros comuns

• Enviar value: 15 num cupom percentage esperando 15%. É 0,15%: use 1500.
• Usar um código de cupom que outro seller já usa: 400 ... already exists (o código é único na loja).
• Tentar corrigir o saldo de um vale-presente pelo PUT. Só situação, dados do presente e validade mudam.
• Criar um vale com código repetido e esperar 400. Hoje volta 500.
• Enviar status de forma de pagamento fora de active/inactive. O valor é gravado sem conferir e pode estourar em 500.
• Salvar a configuração da NF-e sem active: true. Sem isso as notas continuam saindo pelos dados da loja.
• Registrar a resposta de /nfe/config em log: ela contém o token da Focus NFe.

Próximos passos