# Para software houses

> Como uma software house de ERP integra a API RMF. Casos de uso por segmento, arquitetura do fluxo, segurança, sandbox e onboarding.

O ERP já guarda o que importa para a área fiscal do cliente: o cadastro de produtos com NCM, as notas que ele emite e o SPED que ele entrega todo mês. A API RMF leva a inteligência fiscal da RMF para dentro desse sistema. O ERP pergunta a alíquota na hora de cadastrar ou emitir, simula a Reforma Tributária para o perfil do cliente e manda o SPED para receber um relatório fiscal pronto. Sua software house não precisa montar equipe tributária própria para isso.

Esta página é para quem integra: dev, arquiteto e CTO. O programa comercial de parceria fica em [rmfestrategia.com/software-houses.html](https://rmfestrategia.com/software-houses.html).

## O problema que a API resolve no ERP do cliente

- **Cadastro de produtos com tributação desatualizada.** Cadastro errado gera risco fiscal e recolhimento indevido. Com a API, o ERP confere a alíquota de ICMS de cada NCM na UF, a situação na ST e a confiança do resultado.
- **A Reforma Tributária chegando ao sistema.** O cliente quer saber como CBS, IBS e IS entram no preço dele de 2026 a 2033, e como cada NCM ou NBS é tratado na LC 214/2025. O ERP responde sem planilha paralela.
- **SPED entregue e nunca analisado.** O arquivo que o ERP já gera vira relatório fiscal: ICMS-ST, diagnóstico federal ou o SPED em planilha de análise.
- **Resultado, nunca a regra.** As respostas trazem o valor final e o estado, sem memória de cálculo nem fórmula. O ERP mostra o resultado; quem quiser entender um valor específico fala com a equipe da RMF.

## Casos de uso por segmento

Cada linha é uma operação que existe hoje no contrato v1. O `operationId` é o nome da operação na [referência](/referencia).

### Supermercado e varejo

| No ERP | Operação e rota | Escopo |
|---|---|---|
| Conferir o cadastro de produtos inteiro, em lote (até 500 pares de NCM e UF por chamada) | `consultarAliquotasIcmsEmLote` `POST /v1/icms/aliquotas/consultas` | `consultas:ler` |
| Ver em quais estados a base de ICMS tem cobertura | `consultarCoberturaIcms` `GET /v1/icms/cobertura` | `consultas:ler` |

### Atacado e distribuição

| No ERP | Operação e rota | Escopo |
|---|---|---|
| Antes de emitir, a alíquota interna e a situação na ST do NCM na UF de destino, período a período | `consultarAliquotaIcms` `GET /v1/icms/aliquotas` | `consultas:ler` |
| Enviar o SPED e pedir o relatório de ICMS-ST (`tipo: icms_st`) | `enviarArquivo`, `criarRelatorio` `POST /v1/arquivos`, `POST /v1/relatorios` | `arquivos:enviar`, `relatorios:criar` |

### Indústria

| No ERP | Operação e rota | Escopo |
|---|---|---|
| Simular a transição de 2026 a 2033 (CBS, IBS e IS) pelo perfil e pela receita | `simularTransicao` `POST /v1/reforma/simulacoes/transicao` | `consultas:ler` |
| Mostrar no cadastro como a LC 214/2025 trata o NCM | `consultarNcmReforma` `GET /v1/reforma/ncm/{codigo}` | `consultas:ler` |

### Clínicas e saúde

| No ERP | Operação e rota | Escopo |
|---|---|---|
| Achar o serviço na tabela de NBS da LC 214/2025, por código ou descrição | `buscarNcmReforma` `GET /v1/reforma/ncm` | `consultas:ler` |
| Comparar a carga mensal no Simples, no Presumido e no Real | `simularRegimes` `POST /v1/reforma/simulacoes/regimes` | `consultas:ler` |

### Para todos os segmentos

| No ERP | Operação e rota | Escopo |
|---|---|---|
| Cadastrar as empresas do cliente pelo CNPJ e ver a cobertura de arquivos | `criarEmpresa`, `obterEmpresa` `POST /v1/empresas`, `GET /v1/empresas/{cnpj}` | `empresas:escrever`, `empresas:ler` |
| Diagnóstico federal de PIS e COFINS a partir do SPED enviado (`tipo: diagnostico_federal`) | `criarRelatorio`, `obterRelatorio` `POST /v1/relatorios`, `GET /v1/relatorios/{id}` | `relatorios:criar`, `relatorios:ler` |
| Marcos e ações da Reforma, filtrados por regime e setor | `listarMarcosReforma` `GET /v1/reforma/linha-do-tempo` | `consultas:ler` |

Os tipos de relatório disponíveis para a conta estão em `listarTiposRelatorio` (`GET /v1/relatorios/tipos`). O que cada chave pode chamar depende do plano da conta e dos escopos da chave.

## Arquitetura do fluxo

O ERP chama a API **do servidor**, nunca do navegador do usuário: a produção não aceita chamada do navegador. Consulta é síncrona. Arquivo e relatório são assíncronos: a API responde `202` com `Location` para o job, e um webhook avisa o seu servidor quando o trabalho termina.

O corpo do webhook leva só o identificador, o tipo do evento e o estado, nunca dado fiscal. Para ler o resultado, o ERP chama `GET /v1/arquivos/{id}` ou `GET /v1/relatorios/{id}`. Os eventos do v1 são `arquivo.lido`, `arquivo.rejeitado`, `relatorio.concluido` e `relatorio.falhou`. Sem webhook, o ERP consulta `GET /v1/jobs/{id}`.

## Segurança

**Chaves por escopo.** Toda chamada leva `Authorization: Bearer <chave>`, nunca a chave na URL. A chave começa com `rmf_test_` no sandbox e `rmf_live_` na produção, e uma não funciona no ambiente da outra. Cada chave carrega escopos, vencimento e lista de IPs opcional. Peça uma chave por uso, com o escopo mínimo: para consultar alíquota, basta `consultas:ler`. Até 2 chaves ativas por ambiente, para trocar sem parar. Guarde a chave no cofre de segredos do seu sistema, nunca no instalador do ERP nem na máquina do usuário. Detalhes em [Autenticação e escopos](/comecar/autenticacao) e [Chaves e escopos](/conta/chaves-e-escopos).

**Webhook assinado com HMAC.** As entregas seguem o padrão Standard Webhooks, com HMAC-SHA256 e os cabeçalhos `webhook-id`, `webhook-timestamp` e `webhook-signature`. O segredo `whsec_` vem uma única vez, na criação do webhook. A URL precisa ser HTTPS na porta 443, com nome público. Valide a assinatura em tempo constante e recuse entregas com horário muito distante do seu relógio. O passo a passo, com código nas 7 linguagens, está em [Receber webhook e validar a assinatura](/guias/webhooks).

**Idempotência.** Todo `POST` que cria recurso ou trabalho exige `Idempotency-Key`, guardada por 24 horas, por conta e por operação. Gere um UUID por operação lógica e repita o mesmo UUID em todas as retentativas: assim, uma queda de rede no meio do envio do SPED não cria dois relatórios. Veja [Idempotência](/comecar/idempotencia).

**Erros que dizem o que fazer.** Erros vêm em `application/problem+json`, com `codigo` estável e `request_id`. Trate pelo `codigo`, respeite o `Retry-After` no `429` e guarde o `request_id` para o suporte. Catálogo em [Erros](/comecar/erros).

## Conta de rede ou de parceiro

A conta de API é de um de dois tipos. A conta de **rede** é do cliente direto e enxerga as empresas da própria rede. A conta de **parceiro** enxerga a carteira inteira, a união das redes que ela atende. O plano da conta define os produtos, os escopos que as chaves podem receber e se a planilha de resultado está incluída. `GET /v1/conta` mostra o tipo, o plano e os escopos. O tipo da conta e o plano são definidos com a equipe da RMF. Veja [Planos e acesso](/conta/planos).

## Sandbox

O sandbox é um serviço separado, com banco próprio, em `https://sandbox.api.rmfestrategia.com/v1`. Nada do que você envia lá chega à produção, e nada de lá é dado de cliente. Toda conta nasce com o espelho no sandbox, com o mesmo plano. Os arquivos de exemplo do portal (SPED e ZIP de XML sintéticos) devolvem resultados fixos, e o cabeçalho `X-Sandbox-Simular` provoca `429`, relatório que falha e arquivo rejeitado, para você testar o tratamento de erro do ERP. Use só arquivos sintéticos, nunca SPED real. Veja [Sandbox](/comecar/sandbox).

## Do primeiro contato à produção

1. **Fale com a RMF.** Conheça o programa de parceria em [rmfestrategia.com/software-houses.html](https://rmfestrategia.com/software-houses.html) e combine o tipo de conta e o plano.
2. **Receba a chave de sandbox** (`rmf_test_`). Veja [Como conseguir a chave](/comecar/chave).
3. **Faça a primeira chamada** com o exemplo na linguagem do seu ERP: cURL, TypeScript, Python, PHP, C#, Java ou Delphi. Veja [Primeira chamada em 5 minutos](/comecar/primeira-chamada).
4. **Integre os casos de uso** do seu segmento, com os [guias](/guias/conferir-aliquota-icms), o webhook e o tratamento de erro pelo `codigo`. Para assistentes de código, há `llms.txt`, Markdown por página e MCP em [Use com IA](/use-com-ia).
5. **Teste as situações difíceis** no sandbox com `X-Sandbox-Simular`: `429`, relatório que falha e arquivo rejeitado.
6. **Vá para a produção.** Troque `RMF_API_URL` para `https://api.rmfestrategia.com/v1` e a chave para `rmf_live_`, emitida pela equipe da RMF quando a integração estiver pronta.

## Próximo passo

- [Agendar diagnóstico](https://rmfestrategia.com/#diagnostico) com a RMF, para combinar o tipo de conta, o plano e a chave de sandbox.
- [Ver a referência da API](/referencia), com todas as operações do v1.