Central de Atendimento

Visão Geral

A entidade NotaISSRest representa uma Nota Fiscal de Serviços (NFS-e) no sistema ERP Easy. Esta classe contém todas as informações fiscais, tributárias e comerciais relacionadas a prestação ou tomada de serviços.

Versão da API: 1.1
Última Atualização: Dezembro 2025
Conformidade: Lei Complementar 214/2025 (Reforma Tributária - IBS/CBS)

✨ Novidades da versão 1.1:

• Documentação completa de Situação Tributária (ST) IBS/CBS
• Documentação completa de Classificação Tributária IBS/CBS
• Novos exemplos práticos com alíquotas reduzidas
• Guia de cenários de uso com 8 situações comuns
• Seção de validação e relacionamentos IBS/CBS

Endpoint da API

Base URL: /v1/notaISS

Métodos disponíveis:

• GET /v1/notaISS/{id} - Consultar nota por ID
• GET /v1/notaISS - Listar notas com filtros
• POST /v1/notaISS - Criar nova nota
• PUT /v1/notaISS/{id} - Atualizar nota existente
• DELETE /v1/notaISS/{id} - Excluir nota

Índice

1. Identificação da Nota
2. Dados do Remetente (Prestador)
3. Dados do Destinatário (Tomador)
4. Informações Tributárias
5. Tributos Federais (ISS, PIS, COFINS, INSS, IRRF, CSLL)
6. Totalizadores
7. IBS/CBS - Reforma Tributária
8. Informações Adicionais de Obra e Construção
9. Informações de Pagamento e Faturamento
10. Informações Complementares
11. Relacionamentos
12. Configurações e Controles
13. Exemplos de Uso
14. Validações e Códigos de Erro

1. Identificação da Nota

Códigos de Tipo

• 0 - Nota de Entrada (Tomador do Serviço)
• 1 - Nota de Saída (Prestador do Serviço)

Códigos de Status

• 1 - Fechada - Nota finalizada e contabilizada
• 2 - Cancelada - Nota cancelada
• 3 - Aberta - Nota em edição
• 4 - Em Processamento - Aguardando processamento
• 5 - Autorizada - Nota autorizada pela prefeitura

2. Dados do Remetente (Prestador do Serviço)

Códigos de Regime Tributário

• 0 - Simples Nacional - Optante pelo Simples Nacional
• 1 - Lucro Presumido - Tributação pelo Lucro Presumido
• 2 - Lucro Real - Tributação pelo Lucro Real
• 3 - Outros - Outros regimes especiais

3. Dados do Destinatário (Tomador do Serviço)

4. Informações Tributárias

Códigos de Tipo de Tributação

• 1 - Tributável no município - Serviço prestado no município do prestador
• 2 - Tributável fora do município - Serviço prestado em outro município
• 3 - Tributável no estado - Operação tributável no estado
• 4 - Fora do estado - Isento - Operação isenta fora do estado
• 5 - No estado - Imune - Operação imune dentro do estado
• 6 - Fora do estado - Imune - Operação imune fora do estado
• 7 - Exportação - Serviço exportado
• 8 - No estado - Exigibilidade suspensa - Suspensa por decisão judicial/administrativa
• 9 - Fora do estado - Exigibilidade suspensa

Códigos de Exigibilidade do ISS

• 1 - Exigível - ISS exigível normalmente
• 2 - Não incidência - Não há incidência do ISS
• 3 - Isenção - Operação isenta de ISS
• 4 - Exportação - Serviço exportado (não tributado)
• 5 - Imunidade - Operação imune
• 6 - Suspensa por decisão judicial - Exigibilidade suspensa judicialmente
• 7 - Suspensa por processo administrativo - Exigibilidade suspensa administrativamente

Códigos de Município de Prestação

• 0 - Município do remetente - Local do prestador
• 1 - Município do destinatário - Local do tomador
• 2 - Outro município - Município diferente

5. Tributos Federais

5.1. ISS (Imposto Sobre Serviços)

5.2. PIS (Programa de Integração Social)

5.3. COFINS (Contribuição para Financiamento da Seguridade Social)

5.4. INSS (Instituto Nacional do Seguro Social)

5.5. IRRF (Imposto de Renda Retido na Fonte)

5.6. CSLL (Contribuição Social sobre o Lucro Líquido)

6. Totalizadores

Fórmula:

valorReceber = valorContabil - retencao
retencao = valorISSRetido + valorPISRetido + valorCOFINSRetido + valorINSSRetido + valorIRRFRetido + valorCSLLRetido + outrasRetencoes

7. IBS/CBS - Reforma Tributária

A Lei Complementar 214/2025 instituiu o IBS (Imposto sobre Bens e Serviços) e a CBS (Contribuição sobre Bens e Serviços), que substituirão gradualmente os tributos atuais.

7.1. Informações Básicas IBS/CBS

Situação Tributária IBS/CBS (stIBSCBS)

Códigos principais da Situação Tributária:

Classificação Tributária IBS/CBS (classificacaoIBSCBS)

Códigos principais da Classificação Tributária (exemplos):

Observação: A classificação tributária determina automaticamente:

• A situação tributária (ST) aplicável
• Os percentuais de redução de alíquota (quando aplicável)
• Quais grupos de informação devem ser preenchidos

7.2. IBS - Componente UF (Estadual)

Grupo: gIBSUF

7.3. IBS - Componente Municipal

Grupo: gIBSMun

7.4. CBS (Contribuição sobre Bens e Serviços)

Grupo: gCBS

7.5. Tributação Regular

Grupo: gTribRegular - Informações de tributação regular (não simplificada)

7.6. Compras Governamentais

Grupo: gTribCompraGov - Composição do IBS e CBS em compras governamentais

7.7. Tributação Monofásica

7.7.1. Tributação Monofásica Padrão

Grupo: gMonoPadrao

7.7.2. Tributação Monofásica Sujeita à Retenção

Grupo: gMonoRent

7.7.3. Tributação Monofásica Retida Anteriormente

Grupo: gMonoRet

7.7.4. Diferimento da Tributação Monofásica

Grupo: gMonoDif

7.7.5. Totalizadores da Tributação Monofásica

7.8. Transferências de Crédito

Grupo: gTransfCred

7.9. Ajuste de Competência

Grupo: gAjusteCompet

7.10. Estorno de Crédito

Grupo: gEstornoCred

7.11. Crédito Presumido da Operação

Grupo: gCredPresOper

7.11.1. Crédito Presumido - IBS

Grupo: gIBSCredPres

7.11.2. Crédito Presumido - CBS

Grupo: gCBSCredPres

7.12. Crédito Presumido IBS - Zona Franca de Manaus (ZFM)

Grupo: gCredPresIBSZFM - Art. 450, § 1º, LC 214/25

7.13. Cenários de Uso IBS/CBS

? Cenário 1: Tributação Integral (Consultoria/TI)

• ST: 000 - Tributação integral
• Classificação: 000001 - Situações tributadas integralmente
• Características: Alíquotas cheias, sem reduções ou benefícios
• Exemplo: Serviços de consultoria, desenvolvimento de software

? Cenário 2: Alíquota Reduzida 60% (Saúde/Educação)

• ST: 200 - Alíquota reduzida
• Classificações:
  • 200028 - Serviços de educação
  • 200029 - Serviços de saúde humana
  • 200032 - Medicamentos
• Características: Redução de 60% nas alíquotas de IBS e CBS
• Campos adicionais: percentualRedAliqIBSUF, percentualRedAliqIBSMun, percentualRedAliqCBS

? Cenário 3: Alíquota Reduzida 100% (Alimentos Básicos)

• ST: 200 - Alíquota reduzida
• Classificações:
  • 200003 - Produtos para alimentação humana (Anexo I)
  • 200009 - Medicamentos (Anexo XIV)
  • 200014 - Produtos hortícolas, frutas e ovos
• Características: Redução de 100% (alíquota zero)

? Cenário 4: Isenção/Imunidade

• ST: 400 - Isenção
• ST: 410 - Imunidade e não incidência
• Classificações:
  • 400001 - Transporte público coletivo
  • 410004 - Exportações de bens e serviços
  • 410005 - Fornecimentos pela administração pública
• Características: Sem tributação

? Cenário 5: Diferimento

• ST: 510 - Diferimento
• ST: 515 - Diferimento com redução de alíquota
• Classificações:
  • 510001 - Operações com energia elétrica
  • 515001 - Insumos agropecuários para produtor rural
• Características: Postergação do pagamento do tributo
• Campos adicionais: percentualDiferimentoIBSUF, percentualDiferimentoIBSMun, percentualDiferimentoCBS

? Cenário 6: Tributação Monofásica (Combustíveis)

• ST: 620 - Tributação monofásica
• Classificações:
  • 620001 - Tributação monofásica sobre combustíveis
  • 620002 - Com responsabilidade pela retenção
  • 620003 - Com tributos retidos por responsabilidade
• Características: Tributação concentrada em uma única etapa
• Grupos relacionados: gMonoPadrao, gMonoRent, gMonoRet, gMonoDif

? Cenário 7: Suspensão (Regimes Especiais)

• ST: 550 - Suspensão
• Classificações:
  • 550001 - Exportações de bens materiais
  • 550002 - Regime de Trânsito
  • 550008 - Repetro-Temporário
  • 550014 - Zona de Processamento de Exportação
• Características: Suspensão temporária da tributação

? Cenário 8: Transferência de Crédito

• ST: 800 - Transferência de crédito
• Classificações:
  • 800001 - Fusão, cisão ou incorporação
  • 800002 - Transferência de crédito de cooperativas
• Características: Transferência de créditos tributários entre contribuintes
• Campos relacionados: valorIbsTransferido, valorCbsTransferida

7.14. Validação e Relacionamentos

Regras de validação importantes:

1. ST e Classificação devem ser compatíveis:

   • A classificação escolhida deve ter a ST correspondente
   • Exemplo: Classificação 200029 (ST=200) requer stIBSCBS="200"

2. Campos obrigatórios por cenário:

   • Tributação Normal (ST=000): baseCalculoIBSCBS, alíquotas e valores
   • Alíquota Reduzida (ST=200): Campos acima + percentuais de redução
   • Diferimento (ST=510/515): Campos acima + percentuais de diferimento
   • Monofásico (ST=620): Grupos gMonoPadrao, gMonoRent, gMonoRet conforme classificação

3. Cálculos automáticos:

   • aliquotaEfetiva = aliquotaNominal × (1 - percentualReducao/100)
   • valor = baseCalculo × aliquotaEfetiva / 100
   • valorIBS = valorIBSUF + valorIBSMun

8. Informações Adicionais de Obra e Construção

9. Informações de Pagamento e Faturamento

10. Informações Complementares

11. Relacionamentos

12. Configurações e Controles

Exemplos de Uso

Exemplo 1: Consulta Simples (GET)

Request:

GET /v1/notaISS/12345

Response 200 OK:

{
  "id": 12345,
  "empresaId": 1,
  "tipo": 1,
  "numero": 1001,
  "serie": "A",
  "status": 5,
  "statusAnterior": 3,
  "dataEmissao": "2024-12-17T10:30:00",
  "codigoRemetente": "001",
  "razaoSocialNomeRemetente": "EMPRESA PRESTADORA LTDA",
  "cnpjCpfRemetente": "12.345.678/0001-90",
  "inscricaoMunicipalRemetente": "123456",
  "cepEnderecoRemetente": "01310-100",
  "logradouroEnderecoRemetente": "Avenida Paulista",
  "numeroEnderecoRemetente": "1000",
  "bairroEnderecoRemetente": "Bela Vista",
  "municipioEnderecoRemetente": "São Paulo",
  "codigoMunicipalEnderecoRemetente": "3550308",
  "ufEnderecoRemetente": "SP",
  "regimeTributacaoRemetente": 0,
  "emailContatoRemetente": "contato@empresa.com.br",
  "codigoDestinatario": "002",
  "razaoSocialNomeDestinatario": "CLIENTE TOMADOR LTDA",
  "cnpjCpfDestinatario": "98.765.432/0001-10",
  "cepEnderecoDestinatario": "04543-011",
  "logradouroEnderecoDestinatario": "Av. Brigadeiro Faria Lima",
  "numeroEnderecoDestinatario": "3400",
  "bairroEnderecoDestinatario": "Itaim Bibi",
  "municipioEnderecoDestinatario": "São Paulo",
  "codigoMunicipalEnderecoDestinatario": "3550308",
  "ufEnderecoDestinatario": "SP",
  "regimeTributacaoDestinatario": 1,
  "tipoTributacao": 1,
  "municipioPrestacaoServico": 0,
  "exigibilidade": 1,
  "tipoPrestacaoServicoCodigo": "01.07",
  "nbs": "1.0701.10.00",
  "discriminacao": "Serviços de desenvolvimento de software customizado conforme especificação técnica anexa.",
  "coc": {
    "id": 5,
    "codigo": "TI-001",
    "descricao": "Centro de Custo TI"
  },
  "valorContabil": 10000.00,
  "baseISS": 10000.00,
  "aliquotaISS": 2.00,
  "valorISS": 200.00,
  "valorISSRetido": 0.00,
  "reterISS": false,
  "retencao": 0.00,
  "valorReceber": 10000.00,
  "protocolo": "2024123100001",
  "codigoVerificacao": "ABC12345",
  "calculoAutomatico": true,
  "compoeValorDuplicata": true
}

Observação: Campos nulos não aparecem na resposta devido à configuração @JsonInclude(NON_NULL).

Exemplo 2: Criação de Nota Simples (POST)

Request:

POST /v1/notaISS
Content-Type: application/json

Body:

{
  "empresaId": 1,
  "tipo": 1,
  "numero": 1002,
  "serie": "A",
  "status": 3,
  "statusAnterior": 3,
  "dataEmissao": "2024-12-17T14:00:00",
  "codigoRemetente": "001",
  "razaoSocialNomeRemetente": "EMPRESA PRESTADORA LTDA",
  "cnpjCpfRemetente": "12.345.678/0001-90",
  "cepEnderecoRemetente": "01310-100",
  "logradouroEnderecoRemetente": "Avenida Paulista",
  "numeroEnderecoRemetente": "1000",
  "bairroEnderecoRemetente": "Bela Vista",
  "municipioEnderecoRemetente": "São Paulo",
  "codigoMunicipalEnderecoRemetente": "3550308",
  "ufEnderecoRemetente": "SP",
  "regimeTributacaoRemetente": 0,
  "codigoDestinatario": "003",
  "razaoSocialNomeDestinatario": "NOVO CLIENTE LTDA",
  "cnpjCpfDestinatario": "11.222.333/0001-44",
  "cepEnderecoDestinatario": "22640-102",
  "logradouroEnderecoDestinatario": "Av. das Américas",
  "numeroEnderecoDestinatario": "500",
  "bairroEnderecoDestinatario": "Barra da Tijuca",
  "municipioEnderecoDestinatario": "Rio de Janeiro",
  "codigoMunicipalEnderecoDestinatario": "3304557",
  "ufEnderecoDestinatario": "RJ",
  "regimeTributacaoDestinatario": 1,
  "tipoTributacao": 2,
  "municipioPrestacaoServico": 1,
  "exigibilidade": 1,
  "tipoPrestacaoServicoCodigo": "01.07",
  "discriminacao": "Consultoria em TI - Projeto XYZ\nIncluindo análise de requisitos e documentação técnica.",
  "informacoesAdicionais": "Pagamento em 30 dias após emissão",
  "coc": {
    "id": 5
  },
  "valorContabil": 15000.00,
  "calculoAutomatico": true
}

Response 201 Created:

{
  "id": 67890,
  "empresaId": 1,
  "tipo": 1,
  "numero": 1002,
  "serie": "A",
  "status": 3,
  "dataEmissao": "2024-12-17T14:00:00",
  ...
}

Exemplo 3: Nota com IBS/CBS (Reforma Tributária)

Request:

POST /v1/notaISS
Content-Type: application/json

Body:

{
  "empresaId": 1,
  "tipo": 1,
  "numero": 2025,
  "serie": "B",
  "status": 3,
  "statusAnterior": 3,
  "dataEmissao": "2025-01-15T09:00:00",
  "codigoRemetente": "001",
  "razaoSocialNomeRemetente": "EMPRESA PRESTADORA LTDA",
  "cnpjCpfRemetente": "12.345.678/0001-90",
  "cepEnderecoRemetente": "01310-100",
  "logradouroEnderecoRemetente": "Avenida Paulista",
  "numeroEnderecoRemetente": "1000",
  "bairroEnderecoRemetente": "Bela Vista",
  "municipioEnderecoRemetente": "São Paulo",
  "codigoMunicipalEnderecoRemetente": "3550308",
  "ufEnderecoRemetente": "SP",
  "regimeTributacaoRemetente": 1,
  "codigoDestinatario": "005",
  "razaoSocialNomeDestinatario": "CLIENTE FUTURO SA",
  "cnpjCpfDestinatario": "55.666.777/0001-88",
  "cepEnderecoDestinatario": "01310-100",
  "logradouroEnderecoDestinatario": "Avenida Paulista",
  "numeroEnderecoDestinatario": "2000",
  "bairroEnderecoDestinatario": "Bela Vista",
  "municipioEnderecoDestinatario": "São Paulo",
  "codigoMunicipalEnderecoDestinatario": "3550308",
  "ufEnderecoDestinatario": "SP",
  "regimeTributacaoDestinatario": 2,
  "tipoTributacao": 1,
  "municipioPrestacaoServico": 0,
  "exigibilidade": 1,
  "tipoPrestacaoServicoCodigo": "01.07",
  "nbs": "1.0701.10.00",
  "discriminacao": "Serviços de consultoria em transformação digital",
  "coc": {
    "id": 5
  },
  "valorContabil": 50000.00,
  "stIBSCBS": "000",
  "classificacaoIBSCBS": "000001",
  "baseCalculoIBSCBS": 50000.00,
  "aliquotaIBSUF": 8.50,
  "valorIBSUF": 4250.00,
  "aliquotaEfetIBSUF": 8.50,
  "aliquotaIBSMun": 3.50,
  "valorIBSMun": 1750.00,
  "aliquotaEfetIBSMun": 3.50,
  "valorIBS": 6000.00,
  "aliquotaCBS": 12.00,
  "valorCBS": 6000.00,
  "aliquotaEfetCBS": 12.00,
  "valorReceber": 38000.00,
  "calculoAutomatico": true
}

Observações sobre o Exemplo 3:

✅ Campos obrigatórios para IBS/CBS:

• stIBSCBS: Situação Tributária IBS/CBS - Define o regime de tributação
• classificacaoIBSCBS: Classificação Tributária - Define o tipo específico de operação e % de redução
• baseCalculoIBSCBS: Base de cálculo comum para IBS e CBS

✅ Componentes do IBS:

• IBS UF (Estadual): aliquotaIBSUF, valorIBSUF, aliquotaEfetIBSUF
• IBS Municipal: aliquotaIBSMun, valorIBSMun, aliquotaEfetIBSMun
• Total: valorIBS = valorIBSUF + valorIBSMun

✅ CBS (Contribuição sobre Bens e Serviços):

• aliquotaCBS: Alíquota da CBS
• valorCBS: Valor calculado da CBS
• aliquotaEfetCBS: Alíquota efetiva após reduções/benefícios

Campos de alíquota efetiva (aliquotaEfetIBSUF, aliquotaEfetIBSMun, aliquotaEfetCBS):

• Representam a alíquota final após aplicação de reduções e benefícios fiscais
• Podem diferir da alíquota nominal quando há reduções (ex: classificação com 60% de redução)

No exemplo acima:

• ST 000 = Tributação integral (sem benefícios)
• Classificação 000001 = Situações tributadas integralmente pelo IBS e CBS
• Alíquotas efetivas = Alíquotas nominais (sem reduções)

Exemplo 3.1: Nota com IBS/CBS e Alíquota Reduzida (Serviços de Saúde)

Request:

POST /v1/notaISS
Content-Type: application/json

Body:

{
  "empresaId": 1,
  "tipo": 1,
  "numero": 2026,
  "serie": "B",
  "status": 3,
  "statusAnterior": 3,
  "dataEmissao": "2025-01-15T09:00:00",
  "codigoRemetente": "001",
  "razaoSocialNomeRemetente": "CLÍNICA MÉDICA ABC LTDA",
  "cnpjCpfRemetente": "12.345.678/0001-90",
  "cepEnderecoRemetente": "01310-100",
  "logradouroEnderecoRemetente": "Avenida Paulista",
  "numeroEnderecoRemetente": "1000",
  "bairroEnderecoRemetente": "Bela Vista",
  "municipioEnderecoRemetente": "São Paulo",
  "codigoMunicipalEnderecoRemetente": "3550308",
  "ufEnderecoRemetente": "SP",
  "regimeTributacaoRemetente": 1,
  "codigoDestinatario": "006",
  "razaoSocialNomeDestinatario": "PACIENTE XYZ",
  "cnpjCpfDestinatario": "123.456.789-00",
  "cepEnderecoDestinatario": "01310-100",
  "logradouroEnderecoDestinatario": "Avenida Paulista",
  "numeroEnderecoDestinatario": "2000",
  "bairroEnderecoDestinatario": "Bela Vista",
  "municipioEnderecoDestinatario": "São Paulo",
  "codigoMunicipalEnderecoDestinatario": "3550308",
  "ufEnderecoDestinatario": "SP",
  "regimeTributacaoDestinatario": 2,
  "tipoTributacao": 1,
  "municipioPrestacaoServico": 0,
  "exigibilidade": 1,
  "tipoPrestacaoServicoCodigo": "04.01",
  "nbs": "1.0401.10.00",
  "discriminacao": "Consulta médica especializada",
  "coc": {
    "id": 5
  },
  "valorContabil": 1000.00,
  "stIBSCBS": "200",
  "classificacaoIBSCBS": "200029",
  "baseCalculoIBSCBS": 1000.00,
  "aliquotaIBSUF": 8.50,
  "percentualRedAliqIBSUF": 60.00,
  "aliquotaEfetIBSUF": 3.40,
  "valorIBSUF": 34.00,
  "aliquotaIBSMun": 3.50,
  "percentualRedAliqIBSMun": 60.00,
  "aliquotaEfetIBSMun": 1.40,
  "valorIBSMun": 14.00,
  "valorIBS": 48.00,
  "aliquotaCBS": 12.00,
  "percentualRedAliqCBS": 60.00,
  "aliquotaEfetCBS": 4.80,
  "valorCBS": 48.00,
  "valorReceber": 904.00,
  "calculoAutomatico": true
}

Observações sobre o Exemplo 3.1:

? Serviços de Saúde com Redução de 60%:

• ST 200 = Alíquota reduzida
• Classificação 200029 = Fornecimento dos serviços de saúde humana (Anexo III)
• Redução de 60% nas alíquotas de IBS e CBS

? Cálculo das Alíquotas Efetivas:

• IBS UF: 8.50% × (1 - 60%) = 3.40% → Valor: R$ 34,00
• IBS Mun: 3.50% × (1 - 60%) = 1.40% → Valor: R$ 14,00
• CBS: 12.00% × (1 - 60%) = 4.80% → Valor: R$ 48,00

? Totalizadores:

• Valor Contábil: R$ 1.000,00
• Total IBS: R$ 48,00 (UF + Municipal)
• Total CBS: R$ 48,00
• Valor a Receber: R$ 904,00

Outros serviços com redução de 60%:

• Educação (Anexo II) - Classificação 200028
• Dispositivos médicos (Anexo IV) - Classificação 200030
• Medicamentos (Anexo VI) - Classificação 200033
• Alimentos para consumo humano (Anexo VII) - Classificação 200034

Validações e Códigos de Erro

Campos Obrigatórios

Todos os campos marcados como "Sim" na coluna "Obrigatório" devem ser preenchidos:

✅ Identificação: empresaId, tipo, numero, serie, status, statusAnterior, dataEmissao
✅ Remetente: codigoRemetente, razaoSocialNomeRemetente, cepEnderecoRemetente, logradouroEnderecoRemetente, numeroEnderecoRemetente, bairroEnderecoRemetente, municipioEnderecoRemetente, codigoMunicipalEnderecoRemetente, ufEnderecoRemetente, regimeTributacaoRemetente
✅ Destinatário: codigoDestinatario, razaoSocialNomeDestinatario, cepEnderecoDestinatario, logradouroEnderecoDestinatario, numeroEnderecoDestinatario, bairroEnderecoDestinatario, municipioEnderecoDestinatario, codigoMunicipalEnderecoDestinatario, ufEnderecoDestinatario, regimeTributacaoDestinatario
✅ Tributação: tipoTributacao, municipioPrestacaoServico, exigibilidade
✅ Centro de Custo: coc (objeto)

Validações de Intervalo

Validações de Valores

• Todos os campos do tipo Double para valores devem ser positivos ou zero (@PositiveOrZero)
• Campos @Min(1): numero
• Percentuais devem estar entre 0 e 100

Formato de Datas

• DateTime: yyyy-MM-dd'T'HH:mm:ss
  • Exemplo: 2024-12-17T14:30:00
• Date: yyyy-MM-dd
  • Exemplo: 2025-01-15

Códigos de Erro HTTP

Exemplos de Erros

Erro 400 - Campo Obrigatório:

{
  "timestamp": "2024-12-17T15:30:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "empresaId",
      "message": "notaISS.empresa.notNull"
    },
    {
      "field": "numero",
      "message": "must be greater than or equal to 1"
    }
  ]
}

Erro 409 - Nota Duplicada:

{
  "timestamp": "2024-12-17T15:30:00",
  "status": 409,
  "error": "Conflict",
  "message": "Nota fiscal com mesmo número, série e empresa já existe"
}

Regra de Unicidade

A combinação dos seguintes campos deve ser única no sistema:

• empresaId
• numero
• serie
• codigoRemetente

Não é possível criar duas notas com a mesma combinação desses valores.

Comportamento da API

Omissão de Campos Nulos

A API está configurada com @JsonInclude(NON_NULL), o que significa:

✅ Campos null não aparecem na resposta JSON
✅ Reduz significativamente o tamanho das respostas
✅ Melhora a performance e legibilidade

Exemplo:

Se a nota não possui complementoEnderecoRemetente nem emailContatoRemetente, esses campos não aparecerão no JSON de resposta.

Cálculo Automático de Tributos

Quando calculoAutomatico = true:

1. O sistema calcula automaticamente os valores dos tributos baseado nas alíquotas
2. Recalcula o valor líquido (valorReceber)
3. Recalcula as retenções totais

Quando calculoAutomatico = false:

• Os valores informados são mantidos
• Permite ajustes manuais

Observações Importantes

1. Reforma Tributária (IBS/CBS)

Os campos de IBS/CBS foram implementados conforme a Lei Complementar 214/2025. Durante o período de transição (2026-2032), tanto os tributos atuais (ISS, PIS, COFINS) quanto os novos (IBS, CBS) podem coexistir na nota fiscal.

2. Relacionamentos

Os objetos relacionados (itens, duplicatas, XML) são gerenciados em endpoints específicos:

• Itens: /v1/notaISS/{notaId}/itens
• Duplicatas: /v1/notaISS/{notaId}/duplicatas
• XML: /v1/notaISS/{notaId}/xml

3. Auditoria

Todas as operações são auditadas automaticamente:

• Criação de nota
• Alterações de status
• Cancelamento
• Autorizações manuais

4. Integração com Prefeituras

A autorização da nota (mudança de status 3 → 5) envolve comunicação com os sistemas das prefeituras, retornando:

• protocolo
• codigoVerificacao
• numeroReal (número da nota no sistema da prefeitura)
• hash
• chaveAcesso

Glossário

Suporte

Para dúvidas, sugestões ou problemas com a API:

E-mail: suporte@compels.net
Portal: https://www.compels.net/contato

Histórico de Versões

© Copyright 1991 - 2025 | Compels Informática LTDA . Compels, ERP Easy | All Right Reserved

Esta documentação está sujeita a atualizações conforme evolução da legislação tributária brasileira e melhorias no sistema.