v0.2.0: o contrato oficial v1.1.0, com assinatura

@splitbr/client e @splitbr/mock passam a ser gerados do OpenAPI v1.1.0, publicado pelo CGIBS em 24/08/2026. Quebra compatibilidade com a linha 0.1.x.

👉 Guia de migração, campo a campo.

Os quatro headers obrigatórios não existem mais

messageId, correlationId, tenantId e timestamp sumiram de components.parameters, e o Manual de Integração v1.1.0 não os cita uma única vez. No lugar entrou um só: X-JWS-Signature, obrigatório nas 43 operações.

A assinatura, e por que o client não aceita ela pronta

O contrato pede JWS Compact Detached (RFC 7515) sobre o corpo canonicalizado em JCS (RFC 8785), RS256, com sete atributos no protected header.

O b64: false (RFC 7797) é o detalhe que decide o desenho: a assinatura cobre os bytes crus do payload, então quem assina precisa ver exatamente o que vai na rede. Se a assinatura viesse montada de fora, o chamador serializaria o corpo por conta própria, e duas serializações do mesmo objeto divergem em ordem de chave, formato de número ou escaping. O resultado seria uma assinatura válida sobre bytes que ninguém enviou, rejeitada sem pista de por quê.

Então o client canonicaliza, monta o protected header, calcula a entrada e remonta o detached. A operação RS256 sai por um callback seu:

createSplitClient({
  baseUrl,
  kid: "minha-chave-01",
  assinar: (bytes) => hsm.signRS256(bytes),   // a chave privada nunca entra no pacote
})

Existe uma serialização só, e é a que vai na requisição.

O resto do delta

	v0.0.10	v1.1.0
rotas	32	35
schemas	57	78
stream	{idPsp}/tributos	{cnpjRaizPspRecDir}/transacoes
Mecanismo de Ocorrências	—	3 rotas

Campos renomeados: cnpjCpfPagOrig → cnpjPagOrig (que passou a aceitar só CNPJ; pagador pessoa física saiu do contrato), valorTotalCbs/Ibs → vlTotalCbs/Ibs, fromNsu/toNsu → nsuInicial/nsuFinal, tributos → transacoes.

Tipos: numIdentcBaixa e nsuId viraram string. Cuidado com nsuId: comparar NSU com > passou a ordenar lexicograficamente, e "9" > "10" é verdadeiro.

Formatos fixos: numCodBarras com 44 dígitos; idLote = idInfSegr + sequencial (40 posições), o que amarra o lote ao informe no próprio identificador.

Removido: PATCH /api/v1/pix-automatico (o Informe de Transação Atualizada perdeu o Pix Automático).

No mock

As três rotas do MOC estão implementadas, com resposta simulada determinística da RFB/CGIBS, para o ciclo fechar sem a plataforma real.

A assinatura é conferida na forma, sem ser exigida: verificar de verdade obrigaria quem roda npx splitbr-mock a gerar par de chaves antes da primeira resposta, e o valor do mock é não precisar de setup. Conferir a forma pega o erro provável em produção, que é um JWS bem-formado com b64 errado ou com o payload anexado em vez de detached. Para o modo fiel: buildServer({ exigirAssinatura: true }).

Os quatro headers antigos continuam aceitos, e o correlationId segue ecoado por utilidade de depuração, mas nenhum é obrigatório.

Compatibilidade

^0.1.1 não puxa a 0.2.0 sozinho: em 0.x o caret do npm não atravessa o minor. A atualização é deliberada.

Ficou em 0.2.0 e não em 1.0.0 de propósito: pré-1.0 sinaliza quebra no minor, e afirmar estabilidade de API seria falso enquanto três manuais da família não foram publicados, dois seguem em minuta, e o Manual de Segurança (que descreve o JWKS por trás da assinatura) não existe.

Verificação

testes      227  (71 client + 115 mock + 41 detector)   antes: 162
typecheck   0 erros, Node 22 e 24
drift       4/4 MATCH

Full Changelog: v0.1.1...v0.2.0

v0.1.1: o contrato oficial saiu de baixo dos pacotes

Primeira release marcada do repositório. O 0.1.0 foi publicado no npm em julho sem tag nem release, então esta também abre o histórico.

Os pacotes não mudam de comportamento. O que esta release entrega é a descoberta de que o chão se moveu, e o conserto da vigilância que não viu.

O contrato da Plataforma foi para a v1.1.0

Em 24/08/2026 o CGIBS publicou o OpenAPI v1.1.0 da Plataforma Pública, pareado com o Manual de Integração v1.1.0, e moveu a v0.0.10 para "versões anteriores".

	v0.0.10 (o que os pacotes geram)	v1.1.0
rotas	32	35
schemas	57	78 (33 dos 55 comuns alterados)
stream	{idPsp}/tributos/...	{cnpjRaizPspRecDir}/transacoes/...
Mecanismo de Ocorrências	não existe	3 rotas
X-JWS-Signature	ausente	obrigatório nas 43 operações

@splitbr/client e @splitbr/mock continuam fiéis à v0.0.10 e seguem servindo para aprender o mecanismo. Quem integra a plataforma real deve tratar a v1.1.0 como fonte da verdade. A migração é major e está em andamento.

Por que passou 11 dias sem ninguém ver

O detector de drift afirmava, em comentário no próprio código, que esse contrato não tinha fonte pública e por isso não dava para monitorá-lo. O README repetia. Era falso: o CGIBS publica o OAS numa página aberta, sem login e sem mTLS, e o arquivo de lá é byte-idêntico ao que estava vendorado desde julho.

Uma limitação escrita com confiança e nunca testada. O detector agora tem um quarto alvo sobre aquela página, comparando o inventário de artefatos, porque o nome de cada upload carrega timestamp e só a página é alvo estável.

Também nesta release

• Sete artefatos oficiais vendorados: OAS v1.1.0, Manual de Integração v1.1.0, NT 2025.002 v1.51, NT 2026.006 (vinculação NF-e à transação de split), IT 2026.001, PL 010f e a minuta do Manual de Tempos, que quatro documentos davam como inédita e está publicada desde 15/07.
• Contratos da Calculadora re-vendorados, de 36 para 40 rotas, fechando a issue #6.
• CI que não existia. Os 162 testes só rodavam na máquina do mantenedor. Agora build, typecheck e testes em Node 22 e 24.
• prepublishOnly: sem ele, publicar de um clone limpo geraria um tarball apontando para um dist/ inexistente.
• Quadro de estado da regulação reconciliado, e cinco semanas de silêncio em Novidades preenchidas.

Full Changelog: 384bb96...v0.1.1