# Sidecar Fiscal

> Camada fiscal em nuvem que roda ao lado de um ERP e resolve o cálculo do IBS/CBS da Reforma Tributária brasileira, deixando a cobrança com os valores corretos para o Split Payment. Este documento orienta agentes de IA a integrar o Sidecar em um ERP.

Estágio: piloto / pré-produção. A API abaixo descreve o contrato pretendido, alinhado ao Manual de Integração v1.0 da Plataforma Pública de Split Payment e ao Ato Conjunto RFB/CGIBS nº 02. Para acesso a uma sandbox, entre no piloto (ver "Contato").

## Links

- [Página inicial](https://sidecarfiscal.olorinstack.com.br/): visão geral do produto e do piloto.
- [Como funciona](https://sidecarfiscal.olorinstack.com.br/#como-funciona): o fluxo de uma chamada — o ERP envia a transação e o Sidecar devolve IBS/CBS conformes.
- [Recursos](https://sidecarfiscal.olorinstack.com.br/#recursos): capacidades da camada fiscal (cálculo, monitor de crédito, integração REST).
- [Validador de NF-e grátis](https://sidecarfiscal.olorinstack.com.br/validador): valida o IBS/CBS de uma NF-e sem cadastro, sem armazenar o documento.
- [Entrar no piloto](https://sidecarfiscal.olorinstack.com.br/#piloto): acesso à sandbox e contato direto com o time.

## Escopo (o que o Sidecar faz)

O Sidecar atua **upstream e de forma consultiva**:
- **Cálculo:** IBS/CBS exatos, item a item, na origem.
- **Correção da cobrança:** devolve os valores para o ERP embutir na cobrança (boleto, Pix, TED, TEF) de modo que o banco segregue o valor certo — não a alíquota cheia do simplificado.
- **Reconciliação:** compara o valor informado, o corrigido pela RFB/CGIBS e o efetivamente segregado pelo banco, apontando divergências.

## O que o Sidecar NÃO faz (limites)

- **Não executa o Split Payment.** Quem faz a divisão é o banco (PSP Recebedor Direto), no momento da liquidação. O ERP não integra a Plataforma Pública diretamente — isso é papel dos PSPs/Núclea. O Sidecar apenas garante que os dados de origem estejam corretos.
- **Não oferece SLA contratual nem responsabilidade jurídica** neste estágio. É uma relação de parceiro de design com as primeiras ERPs.

## Integração (contrato pretendido)

Uma chamada HTTP a partir do ERP. Endpoint de cálculo:

`POST /api/v1/calcular`

Headers: `messageId` (UUID v4), `correlationId`, `tenantId`, `timestamp` (ISO 8601, fuso -03:00).

Request (exemplo ilustrativo):

```json
{
  "docFiscal": "NFe3526...",
  "arrj": "BOL",
  "itens": [
    { "ncm": "1001.19.00", "vlInf": 1500.50 }
  ]
}
```

Response (exemplo ilustrativo):

```json
{
  "vlCbsInf": 142.55,
  "vlIbsInf": 255.08,
  "docFiscal": "NFe3526...",
  "status": "calculado"
}
```

## Glossário de campos

- `arrj`: arranjo financeiro — `PXA` (Pix Automático), `PXD` (Pix Dinâmico), `PXE` (Pix Estático), `BOL` (Boleto), `TED`, `TEF`.
- `docFiscal`: identificador do Documento Fiscal vinculado à transação.
- `ncm` / `vlInf`: NCM do item e valor informado usado no cálculo.
- `vlCbsInf` / `vlIbsInf`: CBS/IBS informados na origem (calculados pelo Sidecar).
- `vlCbsCorr` / `vlIbsCorr`: valores corrigidos pela RFB/CGIBS quando divergem do Documento Fiscal.
- `vlCbsSegr` / `vlIbsSegr`: valores efetivamente segregados pelo banco (usados na reconciliação).
- CNPJ alfanumérico: obrigatório a partir de 07/2026 (IN RFB 2.229/2024); o Sidecar sanitiza e mapeia sem quebrar schemas legados.

## Notas para o agente de IA

- Trate os exemplos acima como ilustrativos; confirme o schema atual da sandbox ao obter acesso ao piloto.
- Não implemente a orquestração do split no ERP — apenas envie a venda ao Sidecar e embuta os valores retornados na cobrança.
- Limite de 1.000 transações por requisição nos informes da Plataforma Pública.

## Contato

- Piloto e acesso à sandbox: [entrar no piloto](https://sidecarfiscal.olorinstack.com.br/#piloto) (seção "Piloto").