# Conceitos

## Conta, chave de API e empresas

| Conceito | O que é |
|---|---|
| **Conta** | o seu sistema (o ERP) como cliente da API. Uma conta tem chaves de API e empresas |
| **Chave de API** | credencial `nfe_...` da conta. Pode haver várias (uma por ambiente, por sistema...) e cada uma pode ser revogada sozinha |
| **Empresa** | um CNPJ emitente, com regime tributário, endereço, inscrição estadual e **certificado digital A1** próprios. Uma conta pode ter várias |

Uma chave só enxerga as empresas da **própria** conta. Se o seu ERP atende várias lojas (ou vários CNPJs), cadastre cada CNPJ como uma empresa e diga qual emite em cada chamada com `cnpj_emitente`. Quem tem **uma única empresa** pode omitir o campo.

## Ambiente: homologação e produção

Cada empresa está em um de dois ambientes:

- **Homologação**: a SEFAZ de teste. As notas **não têm valor fiscal**, têm numeração própria e levam o texto obrigatório de homologação. É onde toda empresa nasce.
- **Produção**: notas reais, com valor jurídico. A troca é por `PUT /empresas/{cnpj}/ambiente` e só libera com certificado válido, inscrição estadual e as tabelas fiscais da plataforma validadas ([detalhes](03-empresas.md#trocar-de-ambiente)).

As notas ficam presas ao ambiente em que foram emitidas. Ao passar para produção você pode **reaproveitar as mesmas `ref`**: na produção elas começam do zero. As consultas olham sempre o ambiente atual da empresa.

## A `ref`: identificador da nota e proteção contra duplicidade

Toda emissão leva uma `ref` na URL (`POST /nfe?ref=PEDIDO-1001`). É um texto **seu**, de 1 a 60 caracteres (letras, números, ponto, hífen e sublinhado), único por empresa e ambiente. Use o identificador da venda no seu sistema.

A `ref` faz três coisas:

1. **Idempotência.** Se a rede cair e você repetir o `POST` com a mesma `ref` e o mesmo conteúdo, recebe o estado da nota que já existe, **sem emitir outra**. É seguro repetir à vontade.
2. **Consulta.** Você acompanha e opera a nota por ela: `GET /nfe/{ref}`, `DELETE /nfe/{ref}`...
3. **Correção.** Uma nota rejeitada pela SEFAZ aceita o reenvio **corrigido na mesma `ref`**, com o mesmo número fiscal.

Detalhes das regras de reenvio em [Emitir NF-e](05-emitir-nfe.md#reenvio-de-uma-ref).

## Estados da nota

O campo `status` da nota é um destes:

| `status` | Significa | É final? |
|---|---|---|
| `processando_autorizacao` | aceita pela API e na fila, ou enviada e aguardando a SEFAZ | não |
| `autorizado` | a SEFAZ autorizou: a nota existe e vale | sim (aceita eventos) |
| `erro_autorizacao` | a SEFAZ **rejeitou**. `status_sefaz`, `mensagem_sefaz` e `mensagem` dizem por quê. Corrija e reenvie na mesma `ref` | não (reenviável) |
| `erro_validacao` | parou por uma pendência de cálculo ou cadastro, antes de chegar à SEFAZ. `mensagem` diz o que corrigir. Reenvie na mesma `ref` | não (reenviável) |
| `denegado` | a SEFAZ **denegou o uso** (problema fiscal do emitente ou do destinatário): o número foi consumido e a nota não vale | sim |
| `cancelado` | o cancelamento foi registrado | sim |
| `inutilizado` | o número da nota foi inutilizado: ela nunca existiu na SEFAZ | sim |

```text
                 ┌─────────────── erro_autorizacao ◄──────┐
                 │               erro_validacao           │ (reenvio corrigido, mesma ref)
 POST /nfe ─► processando_autorizacao ─► autorizado ─► cancelado
                 │                                   (DELETE /nfe/{ref})
                 └─────────────► denegado
```

## O que é síncrono e o que não é

A API valida **na hora** tudo o que dá para validar sem a SEFAZ e responde `422` antes de gastar um número da série: formato, campos que faltam, tributos que o motor não consegue calcular, totais que não fecham, certificado vencido, produção bloqueada. Quando o `POST /nfe` responde `202`, a nota foi aceita e **já tem número reservado**.

Daí em diante tudo o que depende da SEFAZ é **assíncrono**: emitir, cancelar, corrigir e inutilizar respondem `202` e o resultado chega depois. Você escolhe como saber dele:

- **Webhook** (recomendado): a plataforma chama o seu endereço a cada mudança de estado. Veja [Webhooks](08-webhooks.md).
- **Consulta (polling):** `GET /nfe/{ref}` até o `status` ficar final. Comece a cada 2 segundos e aumente o intervalo.
- **Os dois juntos:** webhook para reagir rápido e uma consulta periódica das notas pendentes como rede de segurança. É o que recomendamos em produção.

## O que a plataforma calcula por você

Você informa a venda (destinatário, itens, valores, pagamento). A plataforma:

- calcula **ICMS, DIFAL, FCP, PIS, COFINS, IPI e IBS/CBS** conforme o regime da empresa e a operação, e define o CFOP;
- monta o XML no leiaute oficial, **assina** com o certificado da empresa e valida contra o XSD;
- reserva o número da NF-e em sequência, **sem buracos nem duplicidade**, mesmo com várias lojas emitindo ao mesmo tempo;
- envia, trata as respostas da SEFAZ (inclusive timeouts: antes de reenviar ela **consulta a chave**, para nunca emitir uma nota duplicada) e gera o DANFE.

Se o seu ERP **já calcula** os tributos, você pode informá-los por item (CFOP, situação tributária, alíquotas) e a plataforma passa a usar o que você mandou: é o [modo híbrido](07-modo-hibrido.md). Os *valores* de imposto (base de cálculo, valor do ICMS...) são sempre calculados pela API.

> **Responsabilidade fiscal:** os parâmetros que você informa valem mais que as regras da plataforma, e a responsabilidade por eles é sua. Cenários que o motor ainda não cobre (por exemplo ICMS-ST como substituto) são recusados com `422 validacao_fiscal`, em vez de a plataforma "chutar".

## Vem do Focus NFe?

A API segue o mesmo estilo (chave por HTTP Basic ou Bearer, `ref` na query, `items[]`, nomes como `nome_destinatario` e `codigo_ncm`, `cnpj_emitente`, `DELETE /nfe/{ref}` com `justificativa`, `POST /nfe/inutilizacao`), então boa parte de um cliente já escrito para ele pode ser reaproveitada. Mas **não é um clone**: confira estas diferenças antes.

| Assunto | Aqui |
|---|---|
| **Cancelar e inutilizar** | **assíncronos**: respondem `202` e o estado muda depois (`GET /nfe/{ref}` ou webhook). Não esperam a SEFAZ |
| **Cancelar** | exige `"confirmo": true` (afirma que a mercadoria **não** saiu) |
| **Campo desconhecido** | **recusado** com `422` e o caminho do campo. Nunca ignorado em silêncio |
| **Valores de imposto** (`icms_valor`, `pis_valor`...) | **recusados**: a API calcula os valores a partir dos parâmetros que você informa ([modo híbrido](07-modo-hibrido.md)) |
| **`valor_total`** | opcional, mas se vier a nota só sai se o total calculado fechar com ele |
| **Campos centrais** | conferem com o estilo do Focus. Os demais (pagamentos, intermediador, parâmetros fiscais além da situação tributária) são desta API, no mesmo estilo: use [Emitir NF-e](05-emitir-nfe.md) como contrato, não a documentação de outro serviço |
| **Estados e códigos** | `status` e `codigo` de erro são os desta documentação ([estados](#estados-da-nota), [erros](09-erros.md)) |