Para software houses

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.

• REST e JSONCampos em português, contrato OpenAPI 3.1 aberto.
• Sandbox separadoBanco próprio, mesmo plano da conta, resultados fixos.
• Webhooks assinadosStandard Webhooks com HMAC-SHA256, sem dado fiscal no corpo.

Pedir chave de sandboxVer a referência da API

Esta página é para quem integra: dev, arquiteto e CTO. O programa comercial de parceria fica em 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.

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.

Consulta: síncrona, sem dado do cliente

1. ERPPergunta na hora de cadastrar ou emitirGET /v1/icms/aliquotas
2. API RMFResponde com o resultado e o estado200 OK, JSON
3. ERPMostra a alíquota e avisa quando a confianca é a_confirmar

Arquivo e relatório: assíncronos, com job e webhook

1. ERPEnvia o SPED do clientePOST /v1/arquivos
2. API RMFAceita e devolve o job202, Location: /v1/jobs/{id}
3. ERPPede o relatório do períodoPOST /v1/relatorios
4. API RMFAvisa o seu servidor, com assinatura HMACrelatorio.concluido
5. ERPLê o resumo em JSON e a planilhaGET /v1/relatorios/{id}

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 e 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.

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.

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.

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.

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.

Do primeiro contato à produção

1. Fale com a RMF. Conheça o programa de parceria em 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.
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.
4. Integre os casos de uso do seu segmento, com os guias, 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.
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 com a RMF, para combinar o tipo de conta, o plano e a chave de sandbox.
• Ver a referência da API, com todas as operações do v1.