# Modo híbrido de tributação

Por padrão você **não informa tributo nenhum**: a plataforma calcula tudo pelo regime da empresa e pela operação. Se o seu ERP **já sabe** como uma mercadoria deve ser tributada (um CFOP específico, uma situação tributária, uma alíquota), você pode informar **por item**, e a plataforma passa a usar o que você mandou. O que você não informa continua sendo calculado.

É o "modo híbrido": campo por campo, **o que você informa vale mais** que as regras da plataforma, e o que falta a plataforma preenche.

> **Responsabilidade fiscal.** Os parâmetros que você informa são seus: a plataforma os usa, mas não os valida do ponto de vista fiscal (isso é a SEFAZ e o seu contador). O que ela garante é que o XML sai no leiaute certo e que as contas (bases e valores) batem com os parâmetros que você mandou.

## Os campos do item

| Campo | Efeito |
|---|---|
| `cfop` | CFOP da linha (4 dígitos). Precisa combinar com a operação: **`5xxx`** em venda dentro do estado, **`6xxx`** em venda para outro estado |
| `icms_situacao_tributaria` | **CSOSN** (3 dígitos) se a empresa é do **Simples Nacional/MEI**; **CST** (2 dígitos) nos outros regimes |
| `icms_aliquota` | alíquota do ICMS, em %, para os CST que tributam (00 e 20) |
| `icms_reducao_base_calculo` | redução da base de cálculo, em % (CST 20) |
| `fcp_aliquota` | alíquota do Fundo de Combate à Pobreza, em %, no DIFAL |
| `icms_difal` | `false` desliga o cálculo do DIFAL neste item |
| `pis_situacao_tributaria`, `pis_aliquota_porcentual` | CST do PIS e alíquota em % |
| `cofins_situacao_tributaria`, `cofins_aliquota_porcentual` | CST da COFINS e alíquota em % |
| `ipi_situacao_tributaria`, `ipi_aliquota` | CST do IPI e alíquota em % (empresa industrial) |

Todos são opcionais e **independentes**: informe só o que precisa mudar.

### Códigos de ICMS suportados

| Regime da empresa | Código | Significado |
|---|---|---|
| Simples Nacional / MEI | `101` | tributada com permissão de crédito (exige `p_cred_sn` no cadastro da empresa) |
| | `102`, `103` | tributada sem crédito; isenção de ICMS para faixa de receita |
| | `300`, `400` | imune; não tributada pelo Simples |
| | `500` | ICMS cobrado antes por substituição tributária (a empresa é a substituída) |
| Demais regimes | `00` | tributada integralmente |
| | `20` | com redução de base de cálculo (exige `icms_reducao_base_calculo`) |
| | `40`, `41` | isenta; não tributada |
| | `60` | ICMS cobrado antes por substituição tributária (a empresa é a substituída) |

Outros códigos (por exemplo CSOSN 201, 202, 203 e 900, ou CST 10, 30, 70 e 90, que envolvem **ICMS-ST como substituto**) ainda não são suportados e voltam `422 validacao_fiscal`.

Informar o código "do regime errado" é recusado com uma mensagem clara: CSOSN (3 dígitos) numa empresa de regime normal, ou CST (2 dígitos) numa empresa do Simples.

## Valores de imposto: nunca

Você informa **parâmetros** (código, alíquota, redução). Os **valores** (base de cálculo, valor do ICMS, do PIS, da COFINS, do IPI) são **sempre calculados pela API** a partir dos parâmetros. Campos como `icms_valor`, `icms_base_calculo`, `pis_valor`, `cofins_valor`, `ipi_valor`, `icms_modalidade_base_calculo` e `valor_total_tributos` são **recusados** com a mensagem *"A API calcula ... a partir da situação tributária e da alíquota informadas; não envie este valor."*

Isso é de propósito: assim o seu ERP não consegue mandar uma nota com a conta errada.

## Exemplos

### CFOP e situação tributária informados (Simples Nacional)

Um item sai com **CSOSN 103** e **CFOP 6949** (outra saída); o outro item não informa nada e segue o cálculo padrão (CSOSN 102, CFOP 6102):

<!-- exemplo:emitir -->
```json
{
  "valor_total": 130.00,
  "nome_destinatario": "COMERCIAL RIO LTDA",
  "cnpj_destinatario": "11.444.777/0001-61",
  "inscricao_estadual_destinatario": "12345678",
  "logradouro_destinatario": "Av Atlantica",
  "numero_destinatario": "500",
  "bairro_destinatario": "Copacabana",
  "municipio_destinatario": "Rio de Janeiro",
  "codigo_municipio_destinatario": "3304557",
  "uf_destinatario": "RJ",
  "cep_destinatario": "22010-000",
  "items": [
    { "codigo_produto": "CAMISA-P", "descricao": "Camiseta basica algodao P", "codigo_ncm": "61091000", "icms_origem": 0,
      "quantidade_comercial": 2, "valor_unitario_comercial": 50.00,
      "cfop": "6949", "icms_situacao_tributaria": "103" },
    { "codigo_produto": "BONE-U", "descricao": "Bone aba curva", "codigo_ncm": "65050090", "icms_origem": 0,
      "quantidade_comercial": 1, "valor_unitario_comercial": 30.00 }
  ],
  "formas_pagamento": [ { "forma_pagamento": "15", "indicador_pagamento": 1 } ]
}
```

### Redução de base de cálculo (regime normal)

Empresa do Lucro Presumido com **CST 20**: alíquota de 12% e **redução de 40%** na base. A API calcula: base de R$ 100,00 reduzida a R$ 60,00 e ICMS de R$ 7,20.

<!-- exemplo:emitir regime=presumido -->
```json
{
  "nome_destinatario": "COMERCIAL RIO LTDA",
  "cnpj_destinatario": "11.444.777/0001-61",
  "inscricao_estadual_destinatario": "12345678",
  "logradouro_destinatario": "Av Atlantica",
  "numero_destinatario": "500",
  "bairro_destinatario": "Copacabana",
  "municipio_destinatario": "Rio de Janeiro",
  "codigo_municipio_destinatario": "3304557",
  "uf_destinatario": "RJ",
  "cep_destinatario": "22010-000",
  "items": [
    { "codigo_produto": "CAMISA-P", "descricao": "Camiseta basica algodao P", "codigo_ncm": "61091000", "icms_origem": 0,
      "quantidade_comercial": 2, "valor_unitario_comercial": 50.00,
      "icms_situacao_tributaria": "20", "icms_aliquota": 12, "icms_reducao_base_calculo": 40 }
  ],
  "formas_pagamento": [ { "forma_pagamento": "15", "indicador_pagamento": 1 } ]
}
```

### PIS e COFINS monofásicos

Para uma mercadoria sujeita ao regime monofásico (PIS/COFINS cobrados na origem), informe a situação tributária `04` (sem alíquota) no PIS e na COFINS; o resto continua calculado:

```json
{ "codigo_produto": "BEBIDA-1", "descricao": "Refrigerante 2L", "codigo_ncm": "22021000", "icms_origem": 0,
  "quantidade_comercial": 6, "valor_unitario_comercial": 8.50,
  "pis_situacao_tributaria": "04", "cofins_situacao_tributaria": "04" }
```

CST `01` e `02` pedem a alíquota (`pis_aliquota_porcentual`, `cofins_aliquota_porcentual`). Os CST `04` a `09` não têm base nem valor. `49` e `99` saem sem destaque de valor.

## Quando o cálculo é recusado

O cenário que o motor não cobre volta como `422 validacao_fiscal`, com o motivo, **antes de gastar um número**:

```json
{ "codigo": "validacao_fiscal", "mensagem": "CSOSN 900 (ICMS-ST como substituto) não é suportado; cadastre a regra com o contador (NCM 61091000)." }
```

Se você receber uma recusa fiscal para um produto que o seu contador garante estar certo, informe os parâmetros do item (CFOP, situação tributária, alíquotas) ou peça à plataforma uma regra para aquele NCM. **A API nunca "chuta"**: sem regra e sem parâmetro, ela recusa.

## Como a plataforma decide o que você não informou

Quando você não informa, valem as regras da plataforma, que em resumo são:

- **Simples Nacional/MEI:** CSOSN `102` (ou `101`, se a empresa tem `p_cred_sn`); PIS e COFINS sem destaque.
- **Regime normal:** ICMS pela alíquota interna da UF da empresa (venda interna) ou pela interestadual (4%, 7% ou 12%); PIS e COFINS pelas alíquotas do regime.
- **CFOP:** venda interna `5102` (ou `5101` se `producao_propria`); interestadual a **contribuinte** `6102`/`6101`; interestadual a **não contribuinte** `6108`/`6107`; mercadoria com ICMS-ST cobrado antes (CSOSN 500 ou CST 60) `5405` (interna) ou `6404` (interestadual).
- **DIFAL e FCP:** calculados sozinhos na venda interestadual a consumidor final **não contribuinte**.
- **IBS/CBS** (reforma tributária): incluídos para as empresas dos regimes obrigados, no período de teste.
- **IPI:** só para empresa `industrial`; exige a situação tributária e a alíquota (no item ou numa regra).

Quem precisa da lista completa e das fórmulas (o contador da empresa, por exemplo) pode pedir à plataforma o documento de regras fiscais.