# Novidades e compatibilidade

A versão da API vai na URL (`/api/v2`) e no campo `info.version` do [contrato OpenAPI](/api/v2/openapi.json).

## Política de compatibilidade

Dentro da `v2` **só adicionamos**. Isto não quebra o seu cliente e pode acontecer a qualquer momento:

- campos novos em respostas e em eventos de webhook;
- endpoints novos e parâmetros opcionais novos;
- valores novos em enumerações (`status`, `evento`, códigos de erro);
- campos opcionais novos nas requisições.

Por isso o seu cliente deve **ignorar campos que não conhece**, tratar um `status` desconhecido como "não final" e programar contra o `codigo` do erro, não contra a `mensagem`.

Isto **não** acontece dentro da `v2`: remover ou renomear campo, mudar o tipo de um campo, mudar o sentido de um código HTTP, tornar obrigatório um campo que era opcional. Mudanças assim só entram em uma versão nova (`/api/v3`), com aviso prévio e a `v2` mantida em paralelo por um período de transição combinado com cada cliente.

Correções de bug que fazem a API cumprir o que está documentado não contam como quebra.

## 2.1.0

- **Numeração por série:** `GET /empresas/{cnpj}/series` lista as séries da empresa com o último e o próximo número; `PUT /empresas/{cnpj}/series/{serie}` define o próximo número (só para a frente), para quem continua a numeração de outro emissor. Erro novo: `422` `numero_retroativo`.
- **`serie` no corpo da nota:** opcional (0 a 889, padrão 1) em `POST /nfe`; a nota sai nessa série e consome o número dela.

## 2.0.0

Primeira versão publicada da API para ERPs.

- **Contas e chaves:** uma conta por ERP, várias chaves (rotação sem parada), várias empresas (CNPJs) por conta.
- **Empresas:** cadastro, atualização, certificado A1 e troca de ambiente pela própria API.
- **Produtos:** catálogo por empresa (SKU → NCM, origem...), com importação em lote.
- **NF-e:** emissão idempotente por `ref`, consulta, XML, DANFE, cancelamento, carta de correção e inutilização de numeração, com numeração em sequência por empresa e série.
- **Modo híbrido de tributação:** o ERP informa o que sabe (CFOP, situação tributária, alíquotas) e a plataforma calcula e preenche o resto.
- **Webhooks assinados** com HMAC-SHA256, repetição automática (9 tentativas em cerca de 21 horas) e histórico de entregas com reenvio.
- **Operação:** limites por minuto por chave, `X-Request-Id`, log de requisições e o contrato OpenAPI 3.1 público.

O que a plataforma ainda **não** cobre está em [Limitações atuais](10-producao.md#limitacoes-atuais).

## Como acompanhar mudanças

O contrato [`/api/v2/openapi.json`](/api/v2/openapi.json) acompanha sempre a versão em produção: compare-o com a cópia que o seu gerador de cliente usou para saber o que mudou. Dúvidas e pedidos de funcionalidade vão pelo mesmo canal de suporte que lhe entregou a chave de API.