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 (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 com os vendorados por conteúdo normalizado; divergência quebra o build e 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.

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 contract is vendored with a pinned SHA-256; a weekly CI diffs the live contract against the vendored copy and breaks the build on drift instead of updating silently.
• 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.