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/mocksobe 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.
| 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.
npm install @splitbr/client
npx @splitbr/mock --port 8377Os 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 .).
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.
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.
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.
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/mockand 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 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.
- 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.
MIT. Os documentos oficiais referenciados pertencem aos seus órgãos publicadores.