splitbr

Toolkit open source de Split Payment do Brasil (IBS/CBS, LC 214/2025) para Node/TypeScript.

Português · English ↓

O split payment da Reforma Tributária segrega o tributo no momento do pagamento: a parcela de CBS/IBS vai direto ao fisco antes de o valor chegar ao vendedor. Isso afeta todo mundo que vende no Brasil, mas quase ninguém consegue ver o mecanismo funcionando, porque a Plataforma Pública é restrita a PSPs homologados. Este repositório abre essa caixa-preta para qualquer pessoa:

• Quer entender o que muda para a sua empresa? Leia o guia em português claro, sem código.
• Quer ver a plataforma funcionando na sua máquina? npx @splitbr/mock sobe um simulador fiel do contrato oficial em minutos (tutorial); nenhuma licença necessária.
• Integra a plataforma de verdade (PSP homologado)? O @splitbr/client é o SDK tipado do contrato.

Aviso: projeto independente e não oficial. Não é afiliado à RFB, ao Comitê Gestor do IBS, ao Serpro ou à Núclea. A fonte da verdade é sempre o contrato oficial, vendorado aqui com hash pinado (vendor/MANIFEST.md); quando o contrato mudar, os builds recusam artefatos divergentes.

Pacotes

Pacote	Para quem	O que faz
@splitbr/mock	Qualquer dev; nenhuma licença necessária	A plataforma inteira rodando local: os 7 fluxos documentados, matrizes de campos M/O/N-E como dados, segregação em 3 passos com rejeição integral de lote, long polling do Super Inteligente, motor de caos (429/503/circuit breaker) e cenários de divergência RSUP com os dois procedimentos de cálculo.
@splitbr/client	Times que integram a plataforma real (PSPs homologados e provedores de conexão)	SDK TypeScript tipado: tipos gerados do OAS oficial, os 4 headers obrigatórios injetados por middleware, erros RFC 7807 tipados e a fórmula de segregação como função pura (centavos inteiros, truncamento para baixo).

Roadmap (próxima fase, priorizada): validadores NF-e da NT 2025.002, que tocam toda empresa que emite nota no Brasil; depois o client da Calculadora oficial e o simulador de fluxo de caixa.

Começando

npm install @splitbr/client
npx @splitbr/mock --port 8377

Os dois estão publicados no npm: @splitbr/client e @splitbr/mock.

import { createSplitClient } from "@splitbr/client";

const client = createSplitClient({
  baseUrl: "http://127.0.0.1:8377", // mock local; troque pelo ambiente do seu PSP
  tenantId: "12345678000199",
});

Cada pacote tem README próprio com exemplos completos. O mock também roda via Docker (docker build -f packages/mock/Dockerfile -t splitbr/mock .).

Contrato oficial e drift

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, que é onde o contrato da Plataforma é publicado. Divergência vira issue, nunca atualização silenciosa.

O alvo do CGIBS tem uma limitação que vale declarar: www.cgibs.gov.br não aceita conexão do runner do GitHub Actions (connect timeout, enquanto os endpoints em tributos.gov.br respondem do mesmo runner). Na prática, esse alvo só compara de verdade quando o drift-check roda de uma rede que alcança o host, como a máquina do mantenedor. No CI ele reporta indisponibilidade sem reprovar o run. Drift ali continua reprovando, quando alcançável. Por isso a rotina semanal continua sendo a cobertura real desse contrato, e não um complemento opcional. 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.

O contrato da Plataforma está na v1.1.0, e os pacotes acompanham

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". Desde a 0.2.0, @splitbr/client e @splitbr/mock são gerados desse contrato.

A mudança quebra compatibilidade com a linha 0.1.x:

• os quatro headers obrigatórios (messageId, correlationId, tenantId, timestamp) deixaram de existir, e entrou a assinatura X-JWS-Signature em todas as 43 operações;
• as 12 rotas de stream trocaram {idPsp}/tributos por {cnpjRaizPspRecDir}/transacoes;
• entraram 3 rotas do Mecanismo de Ocorrências (/api/v1/moc/*);
• os schemas foram de 57 para 78, com 33 dos 55 comuns alterados.

O guia de migração cobre campo a campo. Sobre a assinatura, a escolha de desenho: o client canonicaliza, monta o JWS e chama um callback seu para a operação RS256. A chave privada nunca entra no pacote, e o corpo enviado é byte a byte o que foi assinado, que é o que faz a assinatura validar do outro lado.

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

Monorepo pnpm: pnpm install && pnpm -r build && pnpm -r test (Node >= 22). Contribuições são bem-vindas depois do lançamento inicial; diretrizes de contribuição e CLA chegam em seguida.

English

splitbr is the first open-source toolkit for Brazil's Split Payment, the withhold-the-tax-at-settlement mechanism introduced by the 2023 consumption-tax reform (the new CBS and IBS taxes, phasing in from 2026). Payment platforms split the tax out of each payment and send it straight to the tax authority before the seller is paid. The official platform is restricted to licensed payment providers (PSPs), so almost no one can see how it actually works. This repo opens that black box:

• @splitbr/mock is a faithful local mock of the whole platform: the 7 documented flows, the exact RFC 7807 error taxonomy, the per-arrangement field matrices as data, three-step segregation, Super Inteligente long-polling, and a chaos + divergence engine. Any developer can npx @splitbr/mock and test against it, no license required.
• @splitbr/client is a typed TypeScript SDK generated from the official OpenAPI contract: the four mandatory headers injected by middleware, typed RFC 7807 errors, and the settlement formula as a pure function.

Engineering notes:

• 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, 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 CGIBS target carries a stated limitation: www.cgibs.gov.br refuses connections from the GitHub Actions runner, so in CI it reports unreachable without failing the run, and it only really compares when run from a network that can reach the host. Drift there still fails when reachable.
• The Platform contract moved to v1.1.0 on 2026-08-24, and the packages followed in 0.2.0. The new spec renames all 12 stream routes ({idPsp}/tributos to {cnpjRaizPspRecDir}/transacoes), adds 3 Mechanism-of-Occurrences routes, replaces the four mandatory headers with a required X-JWS-Signature on all 43 operations, and grows the schema set from 57 to 78. See the migration guide. On signing: the client canonicalises (JCS, RFC 8785), builds the detached JWS, and calls a callback you provide for the RS256 operation, so the private key never enters the package and the bytes sent are exactly the bytes signed. 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 computes every figure with the same published function the SDK ships, so it doubles as a live validation of the packages.

Independent, unofficial project: not affiliated with the Brazilian tax authorities, and not legal or tax advice. The guides and docs are in Portuguese, since the audience is Brazilian companies and developers preparing for the reform.

Licença

MIT. Os documentos oficiais referenciados pertencem aos seus órgãos publicadores.