Documentação API SOAP FarmaFiscal

Sistema de Integração Tributária

Sobre a API

A API SOAP Integração Tributária é um sistema de integração tributária que permite consultar, gerenciar e atualizar informações tributárias de produtos farmacêuticos. Todos os serviços utilizam autenticação por CNPJ e senha, e retornam dados em formato XML.

Nota Importante: Todos os serviços requerem credenciais válidas (CNPJ, senha e regime tributário quando aplicável). Os códigos de retorno seguem um padrão comum onde descID=0 indica sucesso.

Índice de Serviços

1. ConsultaAcesso

+
Valida as credenciais do cliente e retorna o status de acesso ao sistema. Útil para verificar se o CNPJ, senha e regime tributário estão corretos antes de realizar outras operações.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
credencial.regimeTributario int Sim Código do regime tributário

Códigos de Retorno

descID: 0 - Sucesso
descID: 1 - Erro no formato XML
descID: 2 - CNPJ ou senha inválidos
descID: 3 - Cliente bloqueado ou cancelado
descID: 4 - Regime tributário incorreto

2. Integracao

+
Gera um arquivo completo de integração contendo todos os dados tributários dos produtos disponíveis para o cliente. O arquivo é disponibilizado via URL para download.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
credencial.regimeTributario int Sim Código do regime tributário

Retorno de Sucesso

<urlFile>Base64(URL do arquivo)</urlFile>

Códigos de Retorno

descID: 0 - Sucesso
descID: 10 - Não há itens para integração
descID: 11 - Não foi possível gerar arquivo

3. ListarItens

+
Consulta dados tributários de produtos específicos através do código de barras. Retorna informações detalhadas incluindo NCM, CEST, PIS/COFINS, ICMS e dados da reforma tributária para cada item consultado.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
credencial.regimeTributario int Sim Código do regime tributário
itens.barra array[string] Sim Lista de códigos de barras a consultar

Dados Retornados por Item

codgtsys, ncm, piscofins, cest, piscof_ent, piscof_sai,
desonera, reducao, fcp, csticms, csosn, aliqicms,
ibs_cbs_class, ibs_cbs, cbs_aliquota, cbs_reducao,
ibs_aliquota, ibs_reducao, aliq_imposto, red_imposto,
perc_icms, ano_reftrib, ibs_uf, ibs_mun, historicoitem
Nota: Os campos relacionados ao ICMS e reforma tributária estadual (ibs_uf, ibs_mun) são retornados apenas se o estado do cliente possui configuração de ICMS (statusUFICMS=1).

4. AtualizarItens

+
Retorna apenas os itens que sofreram alterações desde o último histórico informado. Ideal para manter a base atualizada sem precisar baixar todos os dados novamente. Gera arquivo TXT criptografado para download.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
credencial.regimeTributario int Sim Código do regime tributário
histAtualizacao int Sim Código do último histórico recebido

Retorno de Sucesso

<statusUFICMS>0 ou 1</statusUFICMS>
<histAtualizacao>Novo código histórico</histAtualizacao>
<urlFile>Base64(URL do arquivo)</urlFile>
Importante: Guarde o novo histAtualizacao retornado para usar na próxima consulta. Este serviço possui limite de requisições por período.

Códigos de Retorno

descID: 0 - Sucesso
descID: 6 - Não há itens para atualização
descID: 12 - Limite de requisições excedido

5. HistoricoItem

+
Retorna o histórico completo de alterações de um produto específico, incluindo data, hora e descrição de cada modificação realizada no cadastro tributário.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
credencial.regimeTributario int Sim Código do regime tributário
codGTSYS int Sim Código do item no sistema farma fiscal

Retorno de Sucesso

<historico codItem="12345">
    <data>01/12/2025</data>
    <hora>14:30:00</hora>
    <descricao>Alteração de NCM</descricao>
</historico>

Códigos de Retorno

descID: 0 - Sucesso
descID: 9 - Item sem histórico

6. NovoItem

+
Registra novos produtos para avaliação e classificação tributária. Se o produto já existir no sistema, retorna seus dados tributários atualizados. Permite enviar múltiplos itens em uma única requisição.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
credencial.regimeTributario int Sim Código do regime tributário
itens.item.barra string Sim Código de barras do produto
itens.item.descricao string Sim Descrição do produto
itens.item.principioativo string Não Princípio ativo do medicamento
itens.item.laboratorio string Não Laboratório fabricante
itens.item.ncm string Não NCM sugerido pelo cliente

Status de Retorno por Item

codStatusItem: 0 - Item registrado para avaliação
codStatusItem: 1 - Item já existe (retorna dados completos)
codStatusItem: 3 - Erro ao registrar
Nota: Quando o item já existe, o serviço retorna todos os dados tributários incluindo campos da reforma tributária.

7. NotificaItem

+
Permite enviar notificações sobre problemas ou dúvidas relacionadas a classificação tributária de produtos. Útil para solicitar revisão de dados ou reportar inconsistências.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
credencial.regimeTributario int Sim Código do regime tributário
notificacao.codGTSYS int Sim Código do item no sistema
notificacao.textoNotificacao string Sim Texto descrevendo a notificação

Códigos de Retorno

descID: 0 - Notificação registrada com sucesso
descID: 2 - Item não localizado
descID: 3 - Erro ao registrar notificação

8. AtualizaCest

+
Retorna informações de CEST (Código Especificador da Substituição Tributária) associados aos NCMs. Pode retornar arquivo completo de associações ou consultar NCMs específicos.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
credencial.regimeTributario int Sim Código do regime tributário
CESTAssoc string Não NCM para consulta (vazio = arquivo completo)

Modos de Operação

Sem CESTAssoc: Retorna arquivo completo com todas associações NCM-CEST
Com CESTAssoc: Retorna XML com associações do NCM específico incluindo código de lista e categoria

Códigos de Retorno

descID: 0 - Sucesso
descID: 10 - Não há dados para atualização
descID: 13 - Erro ao selecionar CEST do NCM

9. ListarNCM

+
Retorna arquivo com a listagem completa de NCMs (Nomenclatura Comum do Mercosul) e suas respectivas configurações tributárias. Inclui dados de PIS/COFINS, ICMS quando aplicável.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
credencial.regimeTributario int Sim Código do regime tributário
atualizaNCM int Não Parâmetro de controle de atualização

Retorno de Sucesso

<statusUFICMS>0 ou 1</statusUFICMS>
<urlFile>Base64(URL do arquivo)</urlFile>

Códigos de Retorno

descID: 0 - Sucesso
descID: 14 - Não há NCM para atualização
descID: 15 - Não foi possível gerar arquivo

10. AtualizaRegimeCliente

+
Permite alterar o regime tributário do cliente. Útil quando há mudança na natureza jurídica da empresa (ex: de Simples Nacional para Lucro Real).

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
codRegimeTributario int Sim Novo código do regime tributário
identUsuarioAlteracao string Sim Identificação do usuário responsável

Códigos de Regime Tributário

1: Simples Nacional (SN)
2: Lucro Presumido (PR)
3: Lucro Real (RE)

Códigos de Retorno

descID: 0 - Regime atualizado com sucesso
descID: 7 - Erro ao atualizar regime

11. EnviarListaIntegracaoInicial

+
Primeiro passo para integração de produtos específicos. Envia lista de códigos de barras e gera um código único que será usado no serviço GerarListaIntegracao para baixar os dados tributários.

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
codigoLista int Sim Código único para identificar esta lista
lista string Sim Códigos de barras separados por ponto e vírgula

Exemplo de Lista

7891234567890;7891234567891;7891234567892

Retorno de Sucesso

<codigoLista>12345</codigoLista>
<qtdItensRegistrados>150</qtdItensRegistrados>
Importante: Guarde o codigoLista retornado para usar no serviço GerarListaIntegracao. A lista expira em 24 horas.

Códigos de Retorno

descID: 0 - Lista registrada com sucesso
descID: 16 - Lista vazia ou inválida

12. GerarListaIntegracao

+
Gera arquivo CSV com dados tributários completos incluindo campos da reforma tributária. Pode ser usado de duas formas: com código de lista (integração inicial) ou com histórico de atualização (atualização incremental).

Parâmetros de Entrada

Parâmetro Tipo Obrigatório Descrição
credencial.CNPJ string Sim CNPJ do cliente
credencial.senha string Sim Senha de acesso
codigoLista int Opcional* Código obtido em EnviarListaIntegracaoInicial
histAtualizacao int Opcional* Código do histórico para atualização incremental
* Importante: Pelo menos um dos parâmetros (codigoLista ou histAtualizacao) deve ser fornecido. Não é possível enviar ambos vazios.

Modos de Operação

Modo 1 - Integração Inicial: Usar apenas codigoLista. Retorna todos os produtos da lista enviada anteriormente.

Modo 2 - Atualização Incremental: Usar apenas histAtualizacao. Retorna apenas produtos alterados desde o histórico informado.

Modo 3 - Ambos: Quando ambos são fornecidos, histAtualizacao tem prioridade e codigoLista é ignorado.

Campos do CSV Gerado

idsgt_item, barraItem, ncm, aliquota_pis, aliquota_cofins, cbf,
piscofins, cest, piscof_sai, piscof_ent, desonera, reducao,
aliqicms, ufaliqicms, fcp, csticms, csosn, idhist,
ibs_cbs_class, ibs_cbs, cbs_aliquota, cbs_reducao,
ibs_aliquota, ibs_reducao, aliq_imposto, red_imposto,
perc_icms, ano_reftrib, ibs_uf, ibs_mun

Retorno de Sucesso

<urlFile>Base64(URL do arquivo CSV.zip)</urlFile>
<histAtualizacao>5432</histAtualizacao> (apenas se usar histórico)

Códigos de Retorno

descID: 0 - Arquivo gerado com sucesso
descID: 7 - Código de lista inválido
descID: 10 - Não há itens para integração ou atualização
Reforma Tributária: O arquivo CSV inclui todos os campos da reforma tributária:
  • Nível Federal (sempre): ibs_cbs_class, ibs_cbs, cbs_aliquota, cbs_reducao, ibs_aliquota, ibs_reducao, aliq_imposto, red_imposto, perc_icms, ano_reftrib
  • Nível Estadual (quando UF configurado): ibs_uf, ibs_mun