Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: ci
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
build-and-test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
# Os pacotes prometem engines node >= 22 no package.json. Testar so no
# 24 deixaria a promessa do 22 sem nenhuma evidencia por tras dela.
node-version: [22, 24]
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm -r build
- run: pnpm -r typecheck
- run: pnpm -r test
# Os testes do detector de drift vivem em scripts/ e nao pertencem a
# nenhum pacote, entao `pnpm -r test` nao os alcanca.
- run: pnpm run test:scripts
18 changes: 15 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,22 @@ Cada pacote tem README próprio com exemplos completos. O mock também roda via

## Contrato oficial e drift

Os artefatos oficiais (OAS v0.0.10, manuais, NTs) estão em `vendor/` com SHA-256 pinado em `vendor/MANIFEST.md`. Um workflow semanal compara os contratos hospedados da Calculadora com os vendorados por conteúdo normalizado; divergência vira issue, nunca atualização silenciosa. A Calculadora oficial não é redistribuída (a distribuição não declara licença); use `scripts/download-calculadora.sh`.
Os artefatos oficiais (o OAS da Plataforma, manuais, NTs) estão em `vendor/` com SHA-256 pinado em `vendor/MANIFEST.md`. Um workflow semanal compara quatro alvos com os vendorados: os três contratos hospedados da família Calculadora, por conteúdo normalizado, e o inventário de artefatos da [página do Split Payment no CGIBS](https://www.cgibs.gov.br/split-payment), que é onde o contrato da Plataforma é publicado. Divergência vira issue, nunca atualização silenciosa. A Calculadora oficial não é redistribuída (a distribuição não declara licença); use `scripts/download-calculadora.sh`.

A severidade é por alvo: portal e api-split reprovam o run tanto em divergência quanto em indisponibilidade; o piloto sinaliza sem reprovar, porque é infraestrutura de teste com janela até 31/12/2026 e mudar antes do portal é o comportamento esperado dele.

**Limite de cobertura conhecido**: o contrato que gera `@splitbr/client` e `@splitbr/mock` é `vendor/swagger/openapi-v0_0_10.json`, e ele **não** é monitorado por esse workflow. Não existe endpoint público para compará-lo: as URLs candidatas de `api-docs` da plataforma redirecionam para login e o acesso é restrito a PSP homologado. A integridade local dele é garantida de outra forma, pelo hash pinado que `packages/client/scripts/codegen.mjs` confere antes de gerar os tipos; o que não temos é detecção automática de mudança upstream nesse arquivo. Mudanças nele dependem da [rotina semanal de acompanhamento](docs/watch-routine.md).
### O contrato da Plataforma está em v1.1.0; os pacotes ainda geram do v0.0.10

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 o v0.0.10 para "versões anteriores". A mudança quebra o contrato:

- as 12 rotas de stream trocaram `{idPsp}/tributos` por `{cnpjRaizPspRecDir}/transacoes`;
- entraram 3 rotas do Mecanismo de Ocorrências (`/api/v1/moc/*`);
- o header `X-JWS-Signature` virou obrigatório nas 43 operações;
- os schemas foram de 57 para 78, com 33 dos 55 comuns alterados.

O v1.1.0 está vendorado aqui (`vendor/swagger/openapi-v1_1_0.json`), mas **ainda não alimenta o codegen**: `@splitbr/client` e `@splitbr/mock` continuam gerados do v0.0.10 e, portanto, implementam o contrato anterior. Migrar é um major bump nos dois pacotes e tem task própria. Até lá, quem integra a plataforma real deve ler o v1.1.0 como fonte da verdade.

**Correção de rota, registrada de propósito**: até 04/09/2026 este README afirmava que não existia fonte pública para esse contrato e que por isso ele não era monitorável. Era falso. O CGIBS publica o OAS numa página aberta, sem login e sem mTLS, e o zip de lá é byte-idêntico ao que já estava vendorado. O custo do engano foi medido: o v1.1.0 ficou 11 dias sem detecção. O detector agora observa aquela página como quarto alvo.

## Desenvolvimento

Expand All @@ -64,7 +75,8 @@ Monorepo pnpm: `pnpm install && pnpm -r build && pnpm -r test` (Node >= 22). Con

Engineering notes:

- The official contracts are vendored with a **pinned SHA-256**; a weekly CI diffs the live Calculadora contracts against the vendored copies and **opens an issue on drift** instead of updating silently. Severity is per target: the production endpoints fail the run, the pilot one reports without failing (it is test infrastructure and moving ahead is its job). The spec the packages are generated from has no public endpoint to poll, so it is covered by a pinned-hash check at codegen time rather than by this workflow; that gap is stated above rather than left implied.
- The official contracts are vendored with a **pinned SHA-256**; a weekly CI diffs four targets against the vendored copies and **opens an issue on drift** instead of updating silently: the three live Calculadora contracts, by normalised content, plus the artifact inventory of the [CGIBS Split Payment page](https://www.cgibs.gov.br/split-payment), which is where the Platform contract itself is published. Severity is per target: the production endpoints fail the run, the pilot one reports without failing (it is test infrastructure and moving ahead is its job).
- **The Platform contract moved to v1.1.0 on 2026-08-24; the packages still generate from v0.0.10.** The new spec renames all 12 stream routes (`{idPsp}/tributos` to `{cnpjRaizPspRecDir}/transacoes`), adds 3 Mechanism-of-Occurrences routes, makes the `X-JWS-Signature` header required on all 43 operations, and grows the schema set from 57 to 78. v1.1.0 is vendored here but does not feed codegen yet: migrating is a major bump for both packages and has its own task. Until then, treat v1.1.0 as the source of truth if you integrate the real platform. Until 2026-09-04 this README claimed that spec had no public endpoint and so could not be monitored; that was false, and the error cost 11 days of undetected drift.
- Money math is **integer cents only** (BigInt), never floating point, truncated toward zero to match the official rounding.
- The interactive [demo](https://mozurok.github.io/splitbr/) computes every figure with the **same published function the SDK ships**, so it doubles as a live validation of the packages.

Expand Down
2 changes: 1 addition & 1 deletion docs/site/base-legal.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Dois fatos de contrato do Manual de Integração ajudam a situar quem entra ness

## O que ainda não foi publicado

A família documental do Split Payment tem 6 manuais. Até jul/2026, o Manual de Integração está em versão final (v1.0) e o Manual de Operações existe apenas como minuta (jun/2026). Os outros quatro ainda não saíram: os Manuais de Tempos, de Redes, de Segurança e de Onboarding. Acompanhe o [CGIBS](https://www.cgibs.gov.br/) para as próximas publicações.
A família documental do Split Payment tem 6 manuais. Em set/2026, o Manual de Integração está na v1.1.0 (agosto/2026, que substituiu a v1.0 e trouxe o Mecanismo de Ocorrências, os headers padrão com assinatura `X-JWS-Signature` obrigatória e os requisitos de rastreabilidade). O Manual de Operações (jun/2026) e o Manual de Tempos (15/07/2026) circulam como minuta. Faltam três: os Manuais de Redes, de Segurança e de Onboarding. Acompanhe a [página do Split Payment no CGIBS](https://www.cgibs.gov.br/split-payment) para as próximas publicações.

## Para ir além

Expand Down
28 changes: 16 additions & 12 deletions docs/site/estado-regulacao.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Estado da regulação

# Estado da regulação

Este quadro mostra, em uma olhada, a superfície regulatória atual do Split Payment e da Reforma Tributária do Consumo que o splitbr acompanha: cada artefato oficial, sua versão vigente, a data e a fonte. Última verificação: 20/07/2026. As fontes são checadas toda segunda-feira, e qualquer diferença em relação a este quadro vira registro em [Novidades](/novidades).
Este quadro mostra, em uma olhada, a superfície regulatória atual do Split Payment e da Reforma Tributária do Consumo que o splitbr acompanha: cada artefato oficial, sua versão vigente, a data e a fonte. Última verificação: 04/09/2026. As fontes são checadas toda segunda-feira, e as diferenças encontradas são registradas em [Novidades](/novidades).

As siglas do quadro: **IBS** (Imposto sobre Bens e Serviços) e **CBS** (Contribuição sobre Bens e Serviços) são os tributos novos da reforma; **CGIBS** é o Comitê Gestor do IBS; **NT** é Nota Técnica e **IT** é Informe Técnico do Portal NF-e; **PL** é Pacote de Liberação de esquemas XML.

Expand All @@ -14,32 +14,36 @@ As siglas do quadro: **IBS** (Imposto sobre Bens e Serviços) e **CBS** (Contrib

| Artefato | Versão atual | Data | Fonte oficial |
|---|---|---|---|
| NT 2025.002 (leiaute NF-e/NFC-e para a Reforma Tributária do Consumo) | v1.50 | 03/06/2026 | [Portal NF-e, Notas Técnicas](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=04BIflQt1aY=) |
| NT 2025.002 (leiaute NF-e/NFC-e para a Reforma Tributária do Consumo) | v1.51 | 04/08/2026 | [Portal NF-e, Notas Técnicas](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=04BIflQt1aY=) |
| IT 2025.002 (Informe Técnico, tabelas de classificação) | v1.60 | 23/06/2026 | [Portal NF-e, Informes Técnicos](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=hXzemuyNHW4=) |
| NT 2026.004 (CNPJ alfanumérico) | v1.01 | 08/06/2026 | [Portal NF-e, Notas Técnicas](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=04BIflQt1aY=) |
| Pacote de Liberação de esquemas XML | PL 010e v1.02 | 10/07/2026 | [Portal NF-e, Esquemas XML](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=BMPFMBoln3w=) |
| Pacote de Liberação de esquemas XML | PL 010f v1.04 | 31/08/2026 | [Portal NF-e, Esquemas XML](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=BMPFMBoln3w=) |
| PL 010d (esquemas para CNPJ alfanumérico) | v1.03 | 10/07/2026 | [Portal NF-e, Esquemas XML](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=BMPFMBoln3w=) |
| Esquema dos eventos RTC | era da NT 2025.002 v1.30 | atualizado em 2025 | [Portal NF-e, Esquemas XML](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=BMPFMBoln3w=) |
| Calculadora de Tributos (componente api-regime-geral) | 1.2.4 | 10/07/2026 (obtenção) | [Endpoint de versão dos dados abertos](https://consumo.tributos.gov.br/servico/calcular-tributos-consumo/api/calculadora/dados-abertos/versao) |
| OpenAPI da Plataforma de Split Payment | OAS 3.1, v0.0.10, 32 rotas | obtido em 19/07/2026 | consumo.tributos.gov.br, menu Manuais (URL exata em confirmação) |
| OpenAPI da Calculadora (produção) | OAS 3.1.0, 36 rotas | capturado em 20/07/2026 | [api-docs no portal](https://consumo.tributos.gov.br/servico/calcular-tributos-consumo/api/api-docs) |
| OpenAPI da Calculadora (piloto RTC) | OAS 3.1.0, 36 rotas | capturado em 20/07/2026 | [api-docs no piloto](https://piloto-cbs.tributos.gov.br/servico/calculadora-consumo/api/api-docs) |
| Calculadora de Tributos (ambiente de produção) | app 1.3.1, banco V0043 | 31/08/2026 | [Endpoint de versão dos dados abertos](https://consumo.tributos.gov.br/servico/calcular-tributos-consumo/api/calculadora/dados-abertos/versao) |
| OpenAPI da Plataforma de Split Payment | OAS 3.1, **v1.1.0**, 35 rotas | 24/08/2026 | [página do Split Payment no CGIBS](https://www.cgibs.gov.br/split-payment) |
| OpenAPI da Calculadora (produção) | OAS 3.1.0, 40 rotas | capturado em 04/09/2026 | [api-docs no portal](https://consumo.tributos.gov.br/servico/calcular-tributos-consumo/api/api-docs) |
| OpenAPI da Calculadora (piloto RTC) | OAS 3.1.0, 40 rotas | capturado em 04/09/2026 | [api-docs no piloto](https://piloto-cbs.tributos.gov.br/servico/calculadora-consumo/api/api-docs) |
| OpenAPI do Split Payment Simplificado (api-split) | OAS 3.1.0, 2 rotas | capturado em 20/07/2026 | [api-docs do api-split](https://consumo.tributos.gov.br/servico/calcular-tributos-consumo/api-split/api-docs) |
| Manual de Integração da Plataforma Pública de Split Payment | v1.0 | obtido em 19/07/2026 | consumo.tributos.gov.br, menu Manuais (URL exata em confirmação) |
| Manual de Operações do Split Payment | minuta | jun/2026 | [cgibs.gov.br](https://www.cgibs.gov.br/) (uploads, URL exata em confirmação) |
| Manual de Integração da Plataforma Pública de Split Payment | v1.1.0 | agosto/2026 | [página do Split Payment no CGIBS](https://www.cgibs.gov.br/split-payment) |
| Manual de Operações do Split Payment | minuta | jun/2026 | [página do Split Payment no CGIBS](https://www.cgibs.gov.br/split-payment) |
| Manual de Tempos do Split Payment | minuta | 15/07/2026 | [página do Split Payment no CGIBS](https://www.cgibs.gov.br/split-payment) |
| NT 2026.006 (vinculação NF-e x transação de split payment) | v1.00 | 25/08/2026 | [Portal NF-e, Notas Técnicas](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=04BIflQt1aY=) |
| IT 2026.001 (tabela de meios de pagamento) | v1.01 | 25/08/2026 | [Portal NF-e, Informes Técnicos](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=hXzemuyNHW4=) |
| Resolução CGIBS nº 6/2026 (regulamenta o IBS) | 6/2026 | 30/04/2026 | [PDF na CGIBS](https://www.cgibs.gov.br/upload/arquivos/202604/30084927-res-cgibs-n-6-30-abr-2026-regulamenta-o-ibs.pdf) |

A distribuição offline da Calculadora vendorada no repositório (componente `api-regime-geral` 1.2.4, banco V0039, obtida em 10/07/2026) está atrás da produção desde 31/08/2026. O `@splitbr/client` e o `@splitbr/mock` continuam gerados do OpenAPI **v0.0.10**, não do v1.1.0: a migração é uma quebra de contrato e está em aberto.

## O que ainda não existe

Em 20/07/2026, estes itens da família Split Payment ainda não foram publicados:
Em 04/09/2026, estes itens da família Split Payment ainda não foram publicados:

- **Manual de Tempos**: não publicado. Esperado em [cgibs.gov.br](https://www.cgibs.gov.br/).
- **Manual de Redes**: não publicado. Esperado em [cgibs.gov.br](https://www.cgibs.gov.br/).
- **Manual de Segurança**: não publicado. Esperado em [cgibs.gov.br](https://www.cgibs.gov.br/).
- **Manual de Onboarding**: não publicado. Esperado em [cgibs.gov.br](https://www.cgibs.gov.br/).
- **Percentuais do Split Payment Simplificado**: ainda não definidos.

Além disso, o Manual de Operações existe apenas como minuta (jun/2026). A publicação de qualquer um desses itens muda este quadro.
Além disso, o Manual de Operações (jun/2026) e o Manual de Tempos (15/07/2026) existem apenas como minuta. A publicação de qualquer um desses itens muda este quadro.

## Acompanhe as mudanças

Expand Down
24 changes: 24 additions & 0 deletions docs/site/novidades.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,30 @@ Ordem: mais recente primeiro. Semana sem mudança não gera entrada.

Registro, em ordem cronológica inversa, das mudanças oficiais que afetam o Split Payment e a Reforma Tributária do Consumo: notas técnicas e informes do Portal NF-e, manuais e resoluções do Comitê Gestor do IBS (CGIBS), publicações da Receita Federal e versões da Calculadora de Tributos. Fontes oficiais verificadas toda segunda-feira às 9h (horário de Brasília); semanas sem mudança não geram entrada.

## 2026-08-31: Calculadora vai para o banco V0043 e sai o Pacote de Liberação 010f

- O que mudou: o endpoint público de versão da Calculadora passou a responder `versaoApp` 1.3.1 e `versaoDb` V0043, datado de 31/08/2026, com a descrição oficial "Ajustes na vigência das tabelas CLASSIF_NBS_INDOP_LC e INDICADOR_OPERACAO_IBS_CBS". A referência anterior registrada aqui era o componente 1.2.4 com o banco V0039. No mesmo dia, o Portal NF-e publicou o Pacote de Liberação 010f (NT 2025.002 v1.50 e NT 2026.007 v1.00) e moveu o 010e v1.02 para a lista de versões em desuso.
- Impacto: quem roda a Calculadora offline está com as tabelas de vigência de NBS e de indicador de operação atrás da produção e deve reinstalar. Quem valida XML de NF-e ou NFC-e contra esquema precisa migrar do 010e v1.02 para o 010f.
- Fonte: [endpoint de versão da Calculadora](https://consumo.tributos.gov.br/servico/calcular-tributos-consumo/api/calculadora/dados-abertos/versao) e [Esquemas XML no Portal NF-e](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=BMPFMBoln3w=)

## 2026-08-25: NT 2026.006 amarra a NF-e à transação de split payment

- O que mudou: o Portal NF-e publicou a NT 2026.006 v1.00, que cria o grupo YC na NF-e e NFC-e e o evento 110300, para vincular o documento fiscal à transação financeira sujeita ao split payment. No mesmo dia saiu o IT 2026.001 v1.01, com a tabela de meios de pagamento usada nessa vinculação. Implantação em homologação em 05/10/2026 e em produção em 03/11/2026.
- Impacto: é a peça que faltava entre a camada NF-e e a Plataforma Pública. Sem a vinculação não há como apurar corretamente o débito do fornecedor nem conceder o crédito ao adquirente, então quem emite nota e quem processa pagamento passam a compartilhar um contrato comum.
- Fonte: [Notas Técnicas](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=04BIflQt1aY=) e [Informes Técnicos](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=hXzemuyNHW4=) no Portal NF-e

## 2026-08-24: contrato da Plataforma Pública vai para a v1.1.0 e quebra o v0.0.10

- O que mudou: o CGIBS publicou o OpenAPI **v1.1.0** da Plataforma Pública de Split Payment junto com o Manual de Integração v1.1.0, e moveu o v0.0.10 para "versões anteriores". A mudança quebra o contrato: as 12 rotas de stream trocaram `{idPsp}/tributos` por `{cnpjRaizPspRecDir}/transacoes`, entraram três rotas do Mecanismo de Ocorrências (`/api/v1/moc/*`), o header `X-JWS-Signature` passou a ser obrigatório nas 43 operações e os schemas foram de 57 para 78, com 33 dos 55 comuns alterados. O manual acrescenta ainda que o Informe de Transação Atualizada perdeu o Pix Automático, que `numCodBarras` ficou fixo em 44 caracteres e que `dtHrRepasse` ganhou prazo-limite de envio.
- Impacto: quem integra a plataforma real precisa migrar. O `@splitbr/client` e o `@splitbr/mock` continuam gerados do v0.0.10 e, portanto, implementam o contrato anterior; o v1.1.0 já está vendorado no repositório, mas a migração é um major bump nos dois pacotes e ainda está em aberto.
- Fonte: [página do Split Payment no CGIBS](https://www.cgibs.gov.br/split-payment)

## 2026-08-04: NT 2025.002 sai para a v1.51

- O que mudou: a NT 2025.002 chegou à versão 1.51, com alteração de regras de validação (entre elas UB13-30, UB13-40, UB18-10, UB22-20 e VC02-30) e mudança no cronograma de implantação da UB12-10. A v1.50, de 03/06/2026, saiu da lista de documentos vigentes. A aprovação veio pelo Ato Técnico Conjunto RFB/CGIBS nº 1, de 31/07/2026, um veículo novo: as notas técnicas de Reforma Tributária passaram a ser formalmente aprovadas por esse tipo de ato.
- Impacto: quem valida NF-e contra as regras da NT precisa conferir a lista de validações alteradas antes das datas de corte de 01/09/2026 e 05/10/2026.
- Fonte: [Notas Técnicas no Portal NF-e](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=04BIflQt1aY=)

## 2026-08-03: piloto da Calculadora converge para a produção; divergência do `cTribNac` acabou

- O que mudou: no contrato do piloto, o campo `cTribNac` passou a aceitar só 4 dígitos (`^\d{4}$`), igual ao da produção, e a descrição do campo acompanhou. A divergência registrada aqui em 20/07/2026 deixou de existir, e na direção contrária à esperada: o piloto recuou para o comportamento da produção em vez de antecipar uma mudança dela. O contrato do piloto foi re-capturado e re-pinado no registro do splitbr.
Expand Down
Loading
Loading