LIFFtax

▸ liff.api / referência

A reforma tributária brasileira como endpoints REST.

Cálculo IBS/CBS/IS, validação de documento fiscal, reconciliação de pagamento e split payment expostos como API HTTP. Idempotente, versionada, com SDK em TypeScript, Python e Java.

v2.41.3https://api.liff.taxpreview

▸ 00 · visão geral

Construído para a transição 2026 — 2033.

A API é a infraestrutura programática que ERPs, integradores e equipes internas usam para implementar reforma tributária sem reconstruir motor próprio. Os endpoints expõem cálculo, validação, reconciliação e split payment em uma superfície REST estável.

Em produção a partir do 2º semestre de 2026. Acesso antecipado em sandbox com dados sintéticos cobrindo regimes atual e novo, transição e split.

Latência p95

< 80ms

cálculo · validação

Rate limit

1.000 req/min

por workspace

SLA

99.95%

produção

▸ 01 · autenticação

API key ou OAuth 2.0.

Todas as requisições autenticam via header Authorization: Bearer …. API keys são criadas no painel; para integrações que agem em nome de múltiplos workspaces, use OAuth 2.0 com escopo por endpoint.

shexemplo · curl
curl -X POST https://api.liff.tax/v1/tax/calculate \
  -H "Authorization: Bearer $LIFF_TAX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${UUID}" \
  -d '{ "amount": 100000, "operation": "venda" }'

▸ 02 · core

Cálculo de IBS, CBS e Imposto Seletivo.

POST/v1/tax/calculate

Recebe uma operação fiscal e devolve o cálculo dos tributos do regime novo (IBS, CBS, IS), com memória de cálculo, base legal aplicada e versão da regra. O motor próprio é validado contra a calculadora oficial da Receita Federal a cada release.

Parâmetros do body

parâmetrotipodescrição
  • amountobrig.
    number
    Valor base da operação em centavos.
  • operationobrig.
    enum
    "venda" · "compra" · "transferência" · "devolução"
  • ncmobrig.
    string
    Código NCM de 8 dígitos.
  • origin.ufobrig.
    string
    UF de origem da operação.
  • destination.ufobrig.
    string
    UF de destino.
  • regime
    string
    Regime aplicável. Default: "lc-214-2025".
  • as_of
    string
    Data de referência ISO 8601. Default: agora.
tsrequest · ts
import { LIFF } from "@liff/tax";
 
const liff = new LIFF({
  apiKey: process.env.LIFF_TAX_KEY!,
});
 
const calc = await liff.tax.calculate({
  amount: 100_000,
  operation: "venda",
  ncm: "61091000",
  origin: { uf: "SP" },
  destination: { uf: "RJ" },
});
 
console.log(calc.total); // 12700
200response · json
{
  "id": "tax_8e1c2af0",
  "ibs": { "rate": 0.075, "amount": 7500 },
  "cbs": { "rate": 0.052, "amount": 5200 },
  "is":  { "rate": 0,     "amount": 0    },
  "total": 12700,
  "net":   87300,
  "memory": {
    "rule_version": "lc-214-2025.r4",
    "base_calc": 100000,
    "credits_applied": 0
  },
  "version": "2.41.3"
}

▸ 03 · ingestão

Validação de documento fiscal.

POST/v1/documents/validate

Valida estrutura, campos de IBS/CBS, classificação fiscal e coerência da NF-e antes da autorização. Retorna erros estruturados que podem voltar para o emissor corrigir antes do envio à SEFAZ.

pyrequest · py
from liff import LIFF
 
liff = LIFF(api_key=os.environ["LIFF_TAX_KEY"])
 
result = liff.documents.validate(
    xml=open("nfe.xml").read(),
    schema="nfe-4.0",
)
 
if not result.ok:
    for err in result.errors:
        print(err.field, err.code, err.message)
200response · json
{
  "ok": false,
  "document_id": "doc_71e5b3c0",
  "errors": [
    {
      "field": "ide.cUF",
      "code": "FISCAL_UF_INCONSISTENT",
      "message": "UF emitente difere do CNPJ"
    }
  ],
  "warnings": [],
  "version": "2.41.3"
}

▸ 04 · reconciliação

Reconciliação NF ↔ pagamento ↔ banco.

POST/v1/reconcile

Vincula documento fiscal a eventos financeiros (Pix, boleto, TED, adquirente, gateway). Retorna match com score de confiança e, quando aplicável, identifica split payment e o valor segregado.

tsrequest · ts
const match = await liff.reconcile({
  fiscal: { id: "doc_71e5b3c0" },
  financial: [
    { source: "pix",    ref: "8e1c2af0", amount: 21_107_14 },
    { source: "credit", ref: "c_aabbcc",  amount:  3_072_86 },
  ],
});
 
if (match.score > 0.95) {
  await liff.reconcile.confirm(match.id);
}
200response · json
{
  "id": "match_d2f1a980",
  "fiscal_id": "doc_71e5b3c0",
  "score": 0.98,
  "split": {
    "detected": true,
    "withheld": 307286,
    "net_received": 2110714
  },
  "links": [
    { "source": "pix", "ref": "8e1c2af0" },
    { "source": "credit", "ref": "c_aabbcc" }
  ],
  "version": "2.41.3"
}

▸ 05 · ledger

Gestão de créditos tributários.

GET/v1/credits

Saldo, origem, prazo e prioridade de uso dos créditos de IBS e CBS. Por design, IBS e CBS são segregados na resposta — não há cross-compensação conforme a LC 214/2025.

200response · json
{
  "ibs": {
    "total_available": 481200,
    "expiring_60d": 12000,
    "by_origin": {
      "compra_insumo": 380000,
      "transferência": 101200
    }
  },
  "cbs": {
    "total_available": 334850,
    "expiring_60d": 0,
    "by_origin": {
      "compra_insumo": 290400,
      "serviço": 44450
    }
  },
  "version": "2.41.3"
}

▸ 06 · realtime

Webhooks.

Eventos importantes (NF ingerida, cálculo concluído, match confirmado, split detectado, exceção aberta) são entregues como webhooks HTTP POST. Entrega ordenada, idempotente, com retry exponencial e assinatura HMAC.

webhookpayload · json
{
  "id": "evt_a91c3490",
  "type": "reconcile.split_detected",
  "created_at": "2026-09-14T14:32:02Z",
  "data": {
    "fiscal_id": "doc_71e5b3c0",
    "withheld": 307286,
    "net_received": 2110714
  },
  "version": "2.41.3"
}
tsverify · ts
import { verify } from "@liff/tax";
 
app.post("/webhooks/liff", (req, res) => {
  const valid = verify({
    payload: req.rawBody,
    signature: req.headers["liff-signature"],
    secret: process.env.LIFF_WEBHOOK_SECRET!,
  });
 
  if (!valid) return res.status(400).end();
 
  // process event…
  res.status(200).end();
});

▸ 07 · erros

Códigos estruturados, mensagens em português.

Erros seguem RFC 9457 (problem details). Cada erro tem código estável, mensagem humana e — quando aplicável — referência à norma aplicada.

parâmetrotipodescrição
  • 400 · INVALID_REQUEST
    client
    Body malformado ou parâmetros faltando.
  • 401 · UNAUTHENTICATED
    client
    API key ausente ou inválida.
  • 403 · FORBIDDEN
    client
    Escopo insuficiente para o endpoint.
  • 409 · IDEMPOTENCY_CONFLICT
    client
    Idempotency-Key reutilizada com payload diferente.
  • 422 · FISCAL_INCONSISTENT
    client
    Documento fiscal inconsistente — ver field/code.
  • 429 · RATE_LIMITED
    client
    Rate limit excedido. Header Retry-After indica espera.
  • 500 · ENGINE_ERROR
    server
    Erro interno. Registramos automaticamente.
  • 503 · UPSTREAM_UNAVAILABLE
    server
    Calculadora oficial indisponível, fallback ativado.

▸ 08 · clientes

SDKs oficiais.

Bibliotecas tipadas, idiomáticas, com retry e idempotência embutidos. Source aberto sob MIT.

  • TypeScript / Node

    @liff/tax

    pnpm add @liff/tax

  • Python

    liff

    pip install liff

  • Java

    ai.liff:sdk

    implementation('ai.liff:sdk:2.41.3')

Quer integrar antes do lançamento público?

Acesso antecipado