Novidades e compatibilidade

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

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.

Como acompanhar mudanças

O contrato /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.