CatalogoProduto
Controlador responsável pelo Catálogo de Produtos e inteligência fiscal da Stone Tax API.
Fornece operações para a identificação e curadoria de mercadorias, permitindo buscas assertivas
baseadas em identificadores globais e descrições comerciais para facilitar o processo de faturamento.
Por meio desta controller é possível obter a tributação de produtos,
utilizando filtros por EAN (GTIN) ou descrição, além de retornar informações de
tributação e classificação fiscal essenciais para a conformidade da emissão.
Todos os recursos disponibilizados exigem autenticação e operam sob o contexto do
Emissor informado no cabeçalho, garantindo que as regras fiscais aplicadas correspondam
ao perfil tributário da entidade solicitante.
Obter tributação do produto.
Busca informações detalhadas referentes a tributação de um produto. Poderá ser utilizado código de barras, descrição ou hash para realizar as buscas.
⚠️ ATENÇÃO: É indicado vincular e salvar o HASH do resultado ao cadastro do produto do sistema consumidor do serviço. O HASH será utilizado para acompanhamento de atualizações futuras da tributação do mesmo.
🧪 TESTE: Em ambiente de desenvolvimento/sandbox, os dados dos tributos retornados são fictícios e gerados automaticamente para testes. Não utilize como fonte da verdade em produção. Já em relação ao EAN, o sistema irá validar normalmente, de maneira que para teste de EANs inválidos ou NÃO ENCONTRADOS, poderá aplicar EANs reais.
🔍 BUSCA POR DESCRIÇÃO: O ideal é utilizar a busca por descrição quando o produto NÃO POSSUI EAN. A busca por EAN apresenda dados assertivos enquanto pela descrição será aplicado um algorítmo para identificar a tributação do produto.
post
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Body
Body
Dados de input para a consulta.
ConsultarProdutoInputModel
Dados para consultar a tributação do produto.
* Additional properties are NOT allowed.
tipoFiltrostringrequired
Tipo de filtro do catálogo de produto.
Allowed values:EanDescricaoSimilarHash
filtrostringrequired
Dado de filtragem para consulta do produto (EAN ou descrição similar).
>= 1 characters
codigoMunicipioDestinostring | null
Código do município do destino. (Necessário somente se o destinatário for de outro município)
finalidadestring
Finalidade da operação fiscal.
Allowed values:VendaConsumidorFinalNaoContribuinteVendaConsumidorFinalContribuinteVendaParaRevendaBonificacaoTransferencia
situacaoEspecialDestinatariostring
Situação especial do destinatário da operação fiscal.
Allowed values:IndustrialDistribuidorAtacadistaProdutorRuralArmazemGeralOrgaoPublico
origemProdutostring
Origem do produto para consulta.
Allowed values:NacionalEstrangeiraImportacaoDiretaEstrangeiraAdquiridaMercadoInternoNacionalConteudoImportacaoSuperior40A70NacionalPPBNacionalConteudoImportacaoInferior40EstrangeiraImportacaoDiretaSemSimilarEstrangeiraAdquiridaMercadoInternoSemSimilarNacionalConteudoImportacaoSuperior70
produtoFabricacaoPropriaboolean | null
Indica se o produto consultado é de fabricação própria ou não. (Default false)
destinatarioSimplesNacionalboolean | null
Indica se o destinatário é optante pelo Simples Nacional. (Default false)
destinatarioSubstitutoTributarioboolean | null
Indica se o destinatário é substituto tributário. (Default false)
mercadoriaProduzidaZFMboolean | null
Indica se a mercadoria é produzida na Zona Franca de Manaus. (Default false)
Response
Response
OK
ConsultarProdutoViewModel
Dados de retorno da consulta da tributação do produto.
* Additional properties are NOT allowed.
hashstring | null
Hash da consulta - identificador do produto dentro da aplicação para lastro de consulta de atualização de tributos.
ncmstring | null
NCM do produto.
descricaoNcmstring | null
Descrição do NCM.
inicioVigenciaNcmstring(date)
Data de início da vigência do NCM.
Example:2025-03-31
finalVigenciaNcmstring | null(date)
Data do fim da vigência do NCM.
ceststring | null
CEST do produto.
cfopstring | null
CFOP da operação.
icmsobject
Dados do ICMS incidentes na operação - Regime “Normal”.
* Additional properties are NOT allowed.
Show Child Parameters
icmssnobject
Dados do ICMSST incidentes na operação - Simples Nacional.
* Additional properties are NOT allowed.
Show Child Parameters
ipiobject
Dados do IPI incidentes na operação.
* Additional properties are NOT allowed.
Show Child Parameters
pisobject
Dados do PIS incidentes na operação.
* Additional properties are NOT allowed.
Show Child Parameters
cofinsobject
Dados do COFINS incidentes na operação.
* Additional properties are NOT allowed.
Show Child Parameters
ibsobject
Dados do IBS incidentes na operação.
* Additional properties are NOT allowed.
Show Child Parameters
cbsobject
Dados do CBS incidentes na operação.
* Additional properties are NOT allowed.
Show Child Parameters
impostoSeletivoobject
Dados do Imposto Seletivo (IS) incidentes na operação.
* Additional properties are NOT allowed.
Show Child Parameters
post/api/v1/CatalogoProduto/Tributacao
Authentication
Headers
Body
{
"tipoFiltro": "Ean",
"filtro": "filtro"
}
Hash de produtos - Buscar.
Permite localizar o identificador único (HASH) de tributação de mercadorias através de sua descrição comercial.
🔗 UTILIZAÇÃO: Este endpoint é fundamental para identificar o vínculo correto de um produto quando o EAN (GTIN) não está disponível, permitindo que o sistema consumidor armazene o HASH para futuras consultas de atualização tributária.
🔍 CRITÉRIO DE BUSCA: A busca é processada por algoritmos de similaridade. Recomenda-se o envio de descrições claras e sem abreviações excessivas para garantir que a listagem de hashes retornada seja condizente com o item desejado.
get
Query Parameters
descricaostring
Descrição comercial ou termo de busca para localizar o produto.
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Response
Response
OK
Dados exibidos na listagem da busca de hash de produtos no catálogo fiscal.
* Additional properties are NOT allowed.
hashstring | null
Hash do produto.
descricaostring | null
Descrição do produto.
ncmstring | null
Ncm do produto.
ceststring | null
Cest do produto.
grupostring | null
Descrição do grupo do produto.
get/api/v1/CatalogoProduto/BuscarHash
Authentication
Query Parameters
Headers
Tributos atualizados - Listar.
Fornece uma lista de produtos cuja tributação sofreu atualização no intervalo de tempo fornecido em filtro. Com base no retorno, o sistema consumidor do serviço deverá utilizar o HASH salvo para atualizar os tributos consultados anteriormente.
get
Query Parameters
hashstring
Filtrar pelo hash de identificação.
ultimaAtualizacaoFiscalInicialstring(date-time)
Filtrar pela data de atualização fiscal “a partir de”.
ultimaAtualizacaoFiscalFinalstring(date-time)
Filtrar pela data de atualização fiscal “até”.
offsetinteger(int32)
Registro inicial para paginação.
Default:1
limitinteger(int32)
Quantidade de registros por página.
Default:10
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Response
Response
OK
ListarTributacaoAlteradaViewModelListPaginationResponse
* Additional properties are NOT allowed.
offsetinteger(int32)
limitinteger(int32)
totalinteger(int32)
dataarray | null[object]
Dados da tributação alterada.
* Additional properties are NOT allowed.
Show Child Parameters
get/api/v1/CatalogoProduto/ListarTributacaoAlterada
Authentication
Query Parameters
Headers
Histórico de consultas - Resumo.
Fornece dados totalizados do histórico de consultas na api. Permite ao usuário fazer o acompanhamento da bilhetagem de consumo dos serviços filtrando por intervalo de datas ou texto de busca genérica.
get
Query Parameters
modoConsultastring
Tipo de consulta realizada pelo emissor.
Allowed values:ConsultaProdutoEmissaoDeNotaFiscal
tipoFiltrostring
Tipo de filtro do catálogo de produto.
Allowed values:EanDescricaoSimilarHash
buscastring
Busca genérica - Filtro ou Hash.
statusConsultastring
Status de retorno da consulta do produto.
Allowed values:SucessoNaoEncontradoFalha
dataConsultaInicialstring(date-time)
Filtrar pela data de consulta “a partir de”.
dataConsultaFinalstring(date-time)
Filtrar pela data de consulta “até”.
Headers
DocumentoEmissorstringrequired
Documento do emissor.
Response
Response
OK
ResumoConsultasProdutoVisaoAplicacaoViewModel
Dados do resumo da consulta realizada pelo emissor exibidos na aplicação.
* Additional properties are NOT allowed.
totalConsultasinteger(int32)
Total de consultas realizadas pelo emissor.
totalSucessointeger(int32)
Total de consultas concluídas com sucesso.
totalNaoEncontradointeger(int32)
Total de consultas cujo produto não foi encontrado.
totalFalhainteger(int32)
Total de consultas que apresentaram falhas no processo.
get/api/v1/CatalogoProduto/Historico/Resumo