Manual Contratos

# Manual de teste — Contratos de prestação de serviço recorrente

> **Chamado 0000569760** · Painel V3ndor · Menu **Contratos** · Módulo de permissão **Contratos**

Como cadastrar um contrato e acompanhar o ciclo completo até a nota fiscal.
Escrito para quem vai testar a funcionalidade pela primeira vez.

---

## Índice

1. [O que a funcionalidade faz](#1-o-que-a-funcionalidade-faz)
2. [Cadastros obrigatórios](#2-cadastros-obrigatórios)
3. [Cadastrar um contrato](#3-cadastrar-um-contrato)
4. [Gerar o faturamento](#4-gerar-o-faturamento)
5. [Tratar pendências](#5-tratar-pendências)
6. [Roteiro de testes](#6-roteiro-de-testes)
7. [Motivos de "pulado"](#7-motivos-de-pulado)
8. [Limitações conhecidas](#8-limitações-conhecidas)
9. [Glossário](#9-glossário)

---

## 1. O que a funcionalidade faz

Leia esta seção antes de testar. Ela explica o modelo por trás das telas — sem isso, vários
comportamentos parecem erro quando são regra.

Um **contrato** é um acordo de serviço que se repete: hospedagem mensal, manutenção trimestral,
consultoria com valor fixo. Em vez de alguém lançar o pedido todo mês na mão, o contrato guarda o
combinado e o sistema gera a cobrança de cada período.

> **A regra mais importante do modelo**
>
> O contrato **não emite nota nem boleto**. Ele gera um **pedido de serviço** por período, e daí
> para a frente é a máquina que já existe no sistema (NFS-e nacional e boleto) que faz o resto.
> Se algo der errado na nota, o problema quase sempre está no cadastro da empresa ou do item de
> serviço — não no contrato.

### Competência: o conceito que organiza tudo

**Competência** é o mês a que a cobrança se refere, no formato `AAAA-MM`. Um contrato mensal
iniciado em janeiro gera a competência `2026-01`, depois `2026-02`, e assim por diante.

Cada competência só pode ser gerada **uma vez** por contrato — o sistema bloqueia a segunda
tentativa. Isso é proposital: é o que impede cobrar o cliente duas vezes pelo mesmo mês.

### As quatro telas

| Tela | Para que serve |
|---|---|
| **Contratos** (listagem) | Lista os contratos, com o próximo vencimento e a última competência gerada. É daqui que se suspende, encerra ou reativa um contrato. |
| **Novo / Editar contrato** (cadastro) | O acordo em si: cliente, vigência, periodicidade e as linhas de serviço. Mostra a prévia fiscal enquanto você preenche. |
| **Gerar faturamento** (operação) | Escolhe a competência, mostra o que será gerado *e o que será pulado com o motivo*, e só então gera. Depois emite as notas em fila. |
| **Pendências de emissão** (acompanhamento) | Competências que foram geradas mas não têm nota autorizada. É a fila de trabalho de quem cuida do fiscal. |

### Acesso

O ambiente de homologação já vem com a funcionalidade instalada. Para chegar nas telas, seu perfil
precisa do módulo **Contratos** com **leitura e gravação**.

> **Se "Contratos" não aparece no menu**
>
> É permissão, não instalação — e vale mesmo para usuário administrador. Peça para liberarem o
> módulo **Contratos** no seu perfil, em **Acessos**.

---

## 2. Cadastros obrigatórios

Sem estes cadastros o contrato até salva, mas a geração o descarta com "cadastro fiscal incompleto"
ou a nota é rejeitada. Vale conferir antes de começar.

### 2.1 Empresa emitente

Em **Configurações › Empresas › Editar**. É a empresa que assina a nota. O sistema verifica estes
campos *antes* de transmitir:

| Campo | Observação |
|---|---|
| **CNPJ** (obrigatório) | Sem ele a nota não é montada. |
| **Endereço com município** (obrigatório) | O município (código IBGE) define onde o ISS é recolhido. |
| **Regime especial de tributação** (obrigatório) | Obrigatório sempre. Se a empresa não tem regime especial, selecione **"Nenhum"** — deixar em branco rejeita. |
| **Regime de apuração do Simples** | Só para empresa optante pelo Simples Nacional. Nesse caso é obrigatório. |
| **Certificado digital** (obrigatório) | Sem certificado válido a emissão para com "Nenhum certificado encontrado para a empresa". |

> **"Regime especial" em branco é a causa mais comum de rejeição**
>
> O padrão da NFS-e exige o campo mesmo quando não há regime especial — nesse caso declara-se o
> código "Nenhum". Empresa com o campo vazio recebe do governo um erro de schema em inglês que não
> diz qual campo falta.

### 2.2 Itens de serviço

Em **Itens › Serviços**. É o item de serviço que carrega a informação fiscal — o contrato apenas
aponta para ele.

| Campo | Observação |
|---|---|
| **Descrição** (obrigatório) | Nome do serviço. |
| **Cód. Tributação Nacional** (obrigatório) | O código da lista de serviços (LC116). É ele que define a tributação da nota. |
| **Alíquota ISS (%)** | Percentual de ISS. Pode ser 0 para serviço isento — 0 é um valor válido, diferente de vazio. |
| **cNBS** | Código NBS. Opcional na maioria dos municípios. |
| **Código de Tributação Municipal** | Código próprio da prefeitura, quando o município exige. |

> **Para testar, crie pelo menos dois itens**
>
> Um com código e alíquota diferentes do outro (por exemplo, um a 2% e outro a 5%). Vários cenários
> do roteiro dependem dessa diferença para mostrar o que têm de mostrar.

### 2.3 Demais cadastros

- **Cliente** — com endereço completo. É o tomador do serviço na nota.
- **Condição de pagamento** — **obrigatória no contrato**. É ela que o pedido gerado carrega e de
  onde sai o parcelamento do título. A forma de pagamento não é pedida no contrato: a condição já
  a determina.
- **Operação fiscal** — **obrigatória no contrato**. É dela que o sistema encontra a situação
  fiscal, que por sua vez define as retenções (IR, INSS, PIS, COFINS, CSLL, ISS).
- **Categoria financeira e centro de custo** — opcionais, para classificação contábil.

---

## 3. Cadastrar um contrato

Menu **Contratos** → botão **Novo contrato**. O formulário tem quatro blocos. Campos marcados com
\* são obrigatórios.

### Identificação

| Campo | Observação |
|---|---|
| **Número** | **Só aparece quando o grupo sincroniza com o ERP Delphi**, e aí é obrigatório. Sem sincronização o número é gerado pelo servidor e o campo nem é exibido. |
| **Descrição** \* | Do que se trata o contrato. |
| **Cliente** \* | Quem contrata o serviço. |
| **Empresa emitente** \* | Quem emite a nota. É o cadastro da seção 2.1. |
| **Vendedor** | Opcional, para comissão e relatório. |

### Vigência e recorrência

| Campo | Observação |
|---|---|
| **Início** \* | Primeira competência possível. |
| **Encerramento** \* | Três opções, detalhadas abaixo. |
| **Frequência** \* | Mensal, Trimestral, Semestral ou Anual. |
| **Dia da geração** \* | Dia do mês em que a cobrança é criada. |
| **Dia do vencimento** \* | Dia em que o título vence. Pode ser diferente do dia da geração. |
| **Status** \* | Ativo, Suspenso ou Encerrado. Só contrato **Ativo** gera competência. |
| **Emissão da nota** \* | Quando a NFS-e sai. Três modos, detalhados abaixo. |

**O campo "Encerramento" tem três modos.** São formas diferentes de dizer quando o contrato para de
cobrar. Escolha **uma** — o formulário não deixa combinar duas.

| Modo | O que faz | Quando usar |
|---|---|---|
| **Sem prazo** | Cobra indefinidamente, até alguém encerrar na mão. | Hospedagem, mensalidade, suporte contínuo. |
| **Após N cobranças** | Cobra N vezes e para. Ao esgotar, o contrato deixa de aparecer com próximo vencimento. | Projeto parcelado em 12x. |
| **Fim da vigência** | Cobra até a data informada. | Contrato com prazo fechado em data. |

### Quando a nota é emitida

| Modo | Comportamento |
|---|---|
| **Emitir na geração** | A nota sai junto com o pedido, no momento da geração do faturamento. |
| **Emitir após a baixa** | A nota só sai quando o título for **quitado**. Baixa parcial não emite. |
| **Emissão manual** | A nota nunca sai sozinha — alguém precisa pedir na tela de pendências. |

### Financeiro e fiscal

| Campo | Observação |
|---|---|
| **Condição de pagamento** \* | É ela que o pedido gerado carrega e de onde sai o parcelamento do título. A forma de pagamento não é pedida: a condição já a determina. |
| **Operação fiscal** \* | O que o operador escolhe. É dela que a situação fiscal é encontrada. |
| **Situação fiscal** | **Não é escolhida** — aparece preenchida a partir da operação fiscal. É ela que define as retenções. |
| **Categoria financeira** | Opcional, para classificação contábil. |
| **Centro de custo** | Opcional. |
| **Observações** | Texto livre; entra na observação do pedido gerado. |

### Linhas de serviço

O que o contrato cobra. Cada linha tem **Papel da linha**, **Item de serviço**, **Descrição na
nota**, **Quantidade** e **Valor unitário**. O papel muda o comportamento:

| Papel | Entra no boleto? | Entra na nota? | Observação |
|---|---|---|---|
| **Principal** | Sim | Sim | É dela que a nota tira o código e a alíquota. **Exatamente uma por contrato** — nem zero, nem duas. |
| **Composição** | Sim | Sim | Soma ao valor da nota. Pode ter quantas quiser. |
| **Reembolso** | Sim | **Não** | Cobra do cliente mas fica fora da nota (ex.: passagem, hospedagem repassada). Não usa item de serviço. |

> **Por isso o contrato tem dois valores diferentes**
>
> **Valor** (do título/boleto) é a soma de *todas* as linhas. **Valor da nota** exclui os
> reembolsos. Um contrato sem reembolso tem os dois valores iguais; com reembolso, eles divergem —
> e isso é o comportamento correto.

### A prévia fiscal

Enquanto você monta as linhas, o painel de prévia mostra o que sairá na nota: o código de
tributação que será usado, a alíquota, o texto da discriminação, as retenções e o valor líquido.

Quando as linhas têm **códigos de tributação diferentes**, a prévia mostra quanto custa a mais (ou
a menos) consolidar tudo sob o código da linha principal. Isso acontece porque a NFS-e nacional
aceita um único serviço por nota — juntar serviços de códigos diferentes é uma decisão que tem
custo em ISS, e ela precisa estar visível *antes* de emitir.

---

## 4. Gerar o faturamento

Menu **Contratos** → botão **Gerar faturamento**. É a operação que transforma contratos em pedidos
e notas.

**1. Escolha a competência.**
O mês a ser faturado, no formato `AAAA-MM`. Vem preenchido com o mês corrente.

**2. Peça a prévia.**
A tela mostra **duas listas**: o que será gerado e o que será **pulado, com o motivo e o que fazer
para resolver**. A segunda lista é tão importante quanto a primeira — é ela que explica por que um
contrato não apareceu.

**3. Confira os totais.**
Valor dos títulos, valor das notas e o ISS da competência. Se algum contrato tiver aviso fiscal, um
ícone de alerta aparece na linha — passe o mouse para ler.

**4. Selecione e confirme.**
Você pode gerar todos ou marcar apenas alguns. Nada é gerado até você confirmar — não existe botão
que gere direto.

**5. Acompanhe a emissão.**
Depois de gerar, as notas são emitidas **uma de cada vez**, com o estado de cada linha atualizando
na tela. Uma falha não interrompe as outras: a linha que falhou ganha o botão "Tentar de novo".

> **Como saber que deu certo**
>
> Cada contrato gerado vira um **pedido** (consultável em Pedidos, pelo número de referência) e um
> **título financeiro** com a parcela na data de vencimento configurada. A nota, quando o modo de
> emissão pede, aparece como **Nota autorizada** com o número.

---

## 5. Tratar pendências

Menu **Contratos** → botão **Pendências**. Competências que foram geradas mas não têm nota
autorizada.

| Situação | O que significa | O que a tela permite |
|---|---|---|
| **Gerada sem nota** | O pedido existe, mas a nota nunca foi pedida — típico de contrato com emissão manual. | **Emitir** |
| **Nota rejeitada** | A nota foi transmitida e o governo recusou. A mensagem do erro fica na linha. | **Reenviar** — corrija o cadastro apontado no erro e reenvie. |
| **Sem status conclusivo** | A nota foi transmitida e a resposta não disse se autorizou ou recusou. | **Nenhuma ação** — e isso é proposital. |

> **Por que "sem status conclusivo" não tem botão de reenviar**
>
> Porque a nota *pode ter sido autorizada* sem o retorno ter chegado. Reenviar nesse estado
> duplicaria a nota — um problema bem pior que esperar. A situação se resolve sozinha quando o
> retorno chega.
>
> **Isso não é bug.** Se o teste registrar "falta o botão reenviar nesta linha", o comportamento
> está correto.

---

## 6. Roteiro de testes

Cenários em ordem de dependência — o primeiro cria a base que os outros usam.

### Base — caminho feliz

- [ ] **1. Cadastrar um contrato mensal simples**
  Descrição, cliente, empresa emitente, início no mês passado, sem prazo, mensal, condição de
  pagamento, operação fiscal, uma linha **Principal** de R$ 100,00, emissão *na geração*.
  **Esperado:** salva sem erro e aparece na listagem com Valor e Valor da nota iguais a R$ 100,00.

- [ ] **2. Gerar a competência do mês corrente**
  Abra Gerar faturamento, peça a prévia, confirme.
  **Esperado:** o contrato aparece em "Será gerado"; após confirmar, é criado um pedido e um título
  com vencimento no dia configurado.

- [ ] **3. Conferir o pedido e o título gerados**
  Abra o pedido em Pedidos e o título no financeiro.
  **Esperado:** pedido com o item do contrato, o valor correto **e a condição de pagamento
  preenchida**; título com uma parcela na data de vencimento.

### Bloqueios — o que deve ser recusado

- [ ] **4. Tentar gerar a mesma competência duas vezes**
  Repita a geração do cenário 2, mesma competência.
  **Esperado:** o contrato aparece como pulado, com o motivo *"Competência já gerada"*. Nenhum
  pedido novo é criado.

- [ ] **5. Suspender o contrato e gerar**
  Mude o status para Suspenso pela listagem e peça a prévia do mês seguinte.
  **Esperado:** pulado com *"Contrato suspenso"*, oferecendo atalho para o contrato. Reative e o
  contrato volta a ser elegível.

- [ ] **6. Gerar uma competência fora da vigência**
  Peça a prévia de um mês anterior ao início do contrato.
  **Esperado:** pulado com *"Fora da vigência"*.

- [ ] **7. Contrato trimestral nos meses intermediários**
  Crie um contrato trimestral e peça a prévia de um mês que não é múltiplo do trimestre.
  **Esperado:** pulado com *"Fora da periodicidade"*, informando qual é a próxima competência
  válida.

- [ ] **8. Contrato com número de cobranças esgotado**
  Crie um contrato com **2 cobranças** e gere as duas competências.
  **Esperado:** na terceira tentativa, pulado com *"Cobranças contratadas concluídas"*. Na
  listagem, o contrato deixa de mostrar próximo vencimento.

### Fiscal — o núcleo do chamado

- [ ] **9. Contrato com linha de reembolso**
  Adicione ao contrato uma linha **Reembolso** de R$ 50,00 (sem item de serviço, só descrição).
  **Esperado:** **Valor** = R$ 150,00 e **Valor da nota** = R$ 100,00. A prévia da geração mostra
  "reembolso fora da nota". A nota emitida sai com R$ 100,00; o boleto, com R$ 150,00.

- [ ] **10. Contrato com códigos de tributação divergentes**
  Duas linhas apontando para itens de serviço com **códigos e alíquotas diferentes** (ex.: 2% e 5%).
  **Esperado:** a prévia fiscal avisa que os códigos divergem e mostra **quanto consolidar custa a
  mais ou a menos** de ISS. Confira se o texto diz "a mais" quando é mais caro e "a menos" quando é
  mais barato.

- [ ] **11. Empresa com cadastro fiscal incompleto**
  Apague o *Regime especial de tributação* da empresa emitente e peça a prévia.
  **Esperado:** pulado com *"Cadastro fiscal incompleto"*, dizendo exatamente qual campo falta e
  onde corrigir. Restaure o campo depois do teste.

- [ ] **12. Emissão manual e fila de pendências**
  Crie um contrato com emissão **manual** e gere a competência.
  **Esperado:** o pedido é criado mas nenhuma nota é emitida. A competência aparece em Pendências
  como *"Gerada sem nota"*, com botão Emitir.

> **Ao registrar um problema**
>
> Anote o **número do contrato**, a **competência** e a **mensagem exata** que apareceu na tela.
> Com esses três dados o caso é reproduzível; sem eles, normalmente não é.

---

## 7. Motivos de "pulado"

A lista completa dos motivos pelos quais um contrato não entra numa competência. A tela sempre
mostra o motivo e o que resolve — esta tabela é referência rápida.

| Motivo | O que aconteceu | Como resolver |
|---|---|---|
| **Contrato suspenso** | O status não é Ativo. | Reative pela listagem. *Contrato encerrado* usa o mesmo motivo, com rótulo próprio. |
| **Fora da vigência** | A competência é anterior ao início ou posterior ao fim. | Ajuste início ou fim da vigência, se for o caso. |
| **Fora da periodicidade** | A frequência não prevê esta competência (ex.: trimestral no mês do meio). | Nada a corrigir — a tela informa qual é a próxima competência válida. |
| **Competência já gerada** | Já existe pedido deste contrato neste mês. | Nada a corrigir. É a proteção contra cobrança duplicada. |
| **Cobranças contratadas concluídas** | O contrato tinha N cobranças e as N já foram geradas. | Aumente o número de cobranças ou troque o encerramento para "Sem prazo". |
| **Sem linha principal** | Nenhuma linha está marcada como Principal. | Marque uma linha como Principal — é dela que vêm o código e a alíquota. |
| **Cadastro fiscal incompleto** | Falta algum dado obrigatório da empresa emitente. | A mensagem diz qual campo e onde. Veja a seção 2.1. |

---

## 8. Limitações conhecidas

Comportamentos já identificados. Se encontrar algum destes, não precisa abrir ocorrência — já estão
mapeados.

- **Sem certificado digital, a emissão para.** Em ambientes sem certificado configurado na empresa
  emitente, a nota falha com "Nenhum certificado encontrado para a empresa". Todo o caminho até ali
  (contrato, pedido, título) funciona normalmente.

- **Número do pedido.** Nas telas de contrato o pedido aparece pela *referência*, que é o mesmo
  identificador exibido na listagem de Pedidos. O número sequencial do ERP só existe em ambientes
  com sincronização.

- **Regerar uma competência cancelada.** Se o pedido de uma competência for cancelado, aquele mês
  continua marcado como já gerado. Regerar exige liberar o vínculo no pedido antigo primeiro.

---

## 9. Glossário

| Termo | Significado |
|---|---|
| **Competência** | O mês a que a cobrança se refere, no formato `AAAA-MM`. Não é a data de emissão nem a de vencimento. |
| **Linha principal** | A linha de serviço que define o código de tributação e a alíquota da nota. Exatamente uma por contrato. |
| **Consolidar** | Juntar várias linhas de serviço sob o código da linha principal, porque a nota aceita um só serviço. Tem impacto no ISS quando os códigos diferem. |
| **Discriminação** | O texto descritivo que sai na nota, listando as linhas do contrato. |
| **Retenções** | Tributos descontados do valor da nota (IR, INSS, PIS, COFINS, CSLL, ISS). Vêm da situação fiscal, que sai da operação fiscal. |
| **Condição de pagamento** | Define o parcelamento do título e, por consequência, a forma de pagamento. É o que o pedido gerado carrega. |
| **Título** | O lançamento financeiro (boleto) gerado junto com o pedido. Inclui os reembolsos; a nota não. |
| **Prévia** | Simulação sem efeito: mostra o que aconteceria sem criar nada. Existe tanto na fiscal quanto na geração. |

---

Manual de teste do chamado 0000569760 — contratos de prestação de serviço recorrente. Em caso de
divergência entre este documento e o comportamento do sistema, registre o caso com número do
contrato, competência e mensagem exata.