API v2.6 - Documentação

Bem vindo(a) ao manual da API REST Figura Fiscal.

Nas abas acima, você encontra todas as possibilidades de integração (via GET e POST) com nossa base tributária. Os resultados dos acessos são retornados através de um JSON (formato compacto, de padrão aberto independente, de troca de dados simples e rápida entre sistemas) para que possam ser tratados e utilizados em seu sistema de retaguarda.
Importante: A API tem o limite máximo de 50.000 requisições por mês (somatório de qualquer uma das funções disponíveis na API).

Conheça abaixo a URL da API e os parametros obrigatórios para acesso aos dados em qualquer função de integração desejada:

Função: A função de integração desejada. Como uma consulta de tributos de um determinado EAN, monitorar os tributos durante as vendas do cliente, revisar todos os itens da base do cliente, etc (todas listadas nas abas acima).
ID:
(int)		 É o ID do parceiro que administra os tributos do seu cliente. *O cliente recebe este ID ao ser cadastrado.
CNPJ:
(string, 14)		 É o CNPJ do cliente que receberá os dados tributários através de seu sistema de retaguarda.
TOKEN:
(string, 32)		 Token de acesso a API, um campo de validação para permitir as transações. *O cliente recebe este TOKEN ao ser cadastrado.

Os demais parâmetros, deverão ser incrementados de acordo com a função que irá executar. Devem ser enviados via GET ou POST, informados com mais detalhes em cada aba.

Em caso de dúvidas, fale conosco através do email desenvolvimento@avantfiscal.com.br

Ao utilizar qualquer uma de nossas funções (Revisões, Consultas e Monitoramentos), nossa API irá retornar um JSON contendo o status da solicitação efetuada e no caso de sucesso, retornará um array contendo a tributação de cada um dos itens solicitados. Detalhamos abaixo os campos do JSON de retorno:

A consulta por EAN retorna os dados tributários do produto através do array tributos. A consulta deve ser efetuada via GET, enviando os parâmentros EAN e Descrição do Produto (além dos parâmetros obrigatórios informados na introdução).

Ao efetuar a consulta, caso o EAN não seja encontrado em nossa base, utilizaremos a "descrição do produto" (passada na consulta) para solicitar automaticamente o cadastro deste item. A equipe tributária será informada sobre a necessidade do cadastro do item e efetuará o quanto antes.

Sugestão de usabilidade e integração:
  1. No formulário de cadastro de produtos, ao solicitar um novo item (ou na atualização), efetuar a consulta-ean para capturar os tributos do item;
  2. Se o produto for encontrado (o array tributos não é nulo), aplicar os tributos na base de dados do cliente automaticamente. Ou informar que existem tributos do site a serem aplicados ao item, criar uma forma de exibir estes tributos e exigir o "aceite" (forma recomendada);
  3. Em todas as consultas, sempre retornaremos o idsegmento. Este é o segmento tributário ao qual o produto pertence e deve ser armazenado na base do cliente. Desta forma, quando seu sistema receber atualizações tributárias de um determinado segmento, saberá quais são os produtos vinculados ao mesmo e que precisam sofrer as alterações necessárias;
  4. Se o produto não for encontrado (o array tributos é nulo), informar ao cliente que uma solicitação de cadastro foi enviada para a equipe tributária do site;
Fluxograma de funcionamento:

Utilize o formulário abaixo para efetuar testes de consulta em tempo real em nossa API:

Função e parâmetros obrigatórios:
URL para a consulta EAN via GET no Figura Fiscal API:
Estrutura dos parâmetros a serem enviados via GET:
  • ean (string, 14) - Código de Barras do produto a ser consultado (Caso o item não tenha EAN, infome o código interno);
  • descricao (string, 250) - Descrição do Produto (Será utilizado caso o item não conste na base do site e o cadastro seja solicitado);
  • regime (string, 250) - Regime tributario Embora opcional, é recomendável incluir o 'regime' ['simples', 'real' ou 'presumido] nas requisições para assegurar precisão. Caso não informado, utilizaremos o regime informado no ato do cadastro da empresa. Sua colaboração é fundamental para operações livres de erros.;
Parâmetros para teste:

A consulta por NCM retorna os dados tributários dos "segmentos" através do array tributos e seus respectivos produtos vinculados (uma lista com até 100 itens listados em ordem aleatória), através do array produtos. A consulta deve ser efetuada via GET, enviando o parâmentro NCM (além dos parâmetros obrigatórios informados na introdução).

Sugestão de usabilidade e integração:
  1. Após efetuar a consulta-ean sem sucesso (o item não foi encontrado), é possivel efetuar a consulta via NCM (geralmente já conhecido se a família ou segmento deste produto já estiver cadastrada na base do cliente);
  2. Se algum segmento for encontrado (o array tributos não é nulo), sua retaguarda pode exbir uma tela com os segmentos encontrados (e uma lista com aguns itens vinculados a este segmento: array produtos). Assim, o cliente pode decidir se deseja vincular o seu produto a um destes segmentos tributários do site;
Fluxograma de funcionamento:

Utilize o formulário abaixo para efetuar testes de consulta em tempo real em nossa API:

Função e parâmetros obrigatórios:
URL para a consulta NCM via GET no Figura Fiscal API:
Estrutura dos parâmetros a serem enviados via GET:
  • ncm (string, 8) - NCM do segmento de produtos a ser consultado;
Parâmetros para teste:

A consulta por DATA retorna as atualizações tributárias ocorridas nos "segmentos" de produtos.
Ex: Digamos que tenhamos 500 produtos dentro de um mesmo segmento. Todos estes produtos tem exatamente a mesma característica tributária. Desta forma, a API irá listar uma única vez os tributos deste segmento e cabe a sua retaguarda atualizar os produtos vinculados a este segmento. Seja pelo idsegmento (mais indicado) ou NCM.

Importante: Esta consulta deve ser processada diariamente por seu sistema de retaguarda (no começo ou no fim do dia, para checar todas as possíveis alterações tributárias). Caso o cliente tenha tido qualquer problema e não tenha conseguido efetuar esta consulta, é possível informar uma data anterior a até "30 dias". Neste caso, a API irá listar todos as atualizações ocorridas a partir da data informada.

Os tributos são retornados através do array tributos. Pode ocorrer a situação onde um produto fazia parte de um segmento e por algum motivo tributário, teve que ser vinculado a outro segmento. Neste caso, listaremos estes itens atualizados através do array produtos_troca_segmento e informaremos qual era o ID/NCM do antigo segmento e ID/NCM do segmento atual a qual pertence. A consulta deve ser efetuada via GET, enviando o parâmentro DATA (além dos parâmetros obrigatórios informados na introdução).

Sugestão de usabilidade e integração:
  1. Efetuar esta consulta automaticamente 1x por dia, todos os dias;
  2. Em caso de atualizações encontradas ou produto que sofreu troca de segmento, exibir um relatório ao cliente com todos os itens de sua base que foram afetados por essas atualizações;
  3. Criar um botão onde o cliente pode manualmente rodar a verificação de atualização. Desta forma, caso tenha ocorrido qualquer problema na função automática, o cliente continua atualizado;
Fluxograma de funcionamento:

Utilize o formulário abaixo para efetuar testes de consulta em tempo real em nossa API:

Função e parâmetros obrigatórios:
URL Final para a consulta de atualizações por DATA via GET no Figura Fiscal API:
Estrutura dos parâmetros a serem enviados via GET:
  • date (string, 10) - DATA da consulta por atualizações (O sistema pesquisa todas as atualizações ocorridas na data informado e a partir dela);
  • regime (string, 250) - Regime tributario Embora opcional, é recomendável incluir o 'regime' ['simples', 'real' ou 'presumido] nas requisições para assegurar precisão. Caso não informado, utilizaremos o regime informado no ato do cadastro da empresa. Sua colaboração é fundamental para operações livres de erros.;
Parâmetros para teste:

O recurso de Revisão Fiscal permite verificar e corrigir os tributos de todos os itens da base de dados do cliente. A cada envio de um lote com os itens do cliente, a API retorna os tributos do item através do array tributos. Em cada item, caso o NCM, ICMS, Pis ou Cofins seja informado, um campo no retorno identifica se houve divergencia entre os tributos no cadastro do cliente e o informado pelo site. Caso algum item não seja encontrado na base do site, uma solicitação de cadastro sera enviada automaticamente para nossa equipe tributária, que providenciará o cadastro o quanto antes.

Após o termino do envio de todos os itens da base do cliente, sua retaguarda pode chamar nossa URL, para que o cliente tenha acesso a um relatório listando todos os itens revisados neste processo, as divergências encontradas, etc.

Sugestão de usabilidade e integração:
  1. Cada envio para a API deve conter um lote de até 300 itens por vez. Após o retorno da API, envie mais 300 e repita o processo até revisar toda a base de produtos do cliente;
  2. A API irá retornar os dados tributários de cada item no array tributos. Caso você tenha enviado o NCM, ICMS, PIS ou COFINS e alguma dessas informações estejam diferentes da base do site, o campo divergencia será igual a 1;
  3. Em todas as consultas, sempre retornaremos o idsegmento. Este é o segmento tributário ao qual o produto pertence e deve ser armazenado na base do cliente. Desta forma, quando seu sistema receber atualizações tributárias de um determinado segmento, saberá quais são os produtos vinculados ao mesmo e que precisam sofrer as alterações necessárias;
  4. Os itens não encontrados na base do site ficarão na listagem de pendência da equipe tributária e serão cadastrados o quanto antes;
  5. A cada retorno, a API exibirá o campo idrevisao, que passado junto ao token do cliente dá acesso ao relatório de revisão Fiscal em nosso site;
  6. URL relatório de Revisao: https://figurafiscal.com.br/v2.0/?direcionador=revisao-fiscal/relatorio.asp?id=idrevisao&token=token
Fluxograma de funcionamento:

Utilize o formulário abaixo para efetuar testes de consulta em tempo real em nossa API:

Função e parâmetros obrigatórios:
URL para o envio do lote de itens da base do cliente para a Revisão Fiscal via POST no Figura Fiscal API:
Estrutura dos itens a serem enviados via POST:
  • codinterno (string, 15) - Código interno do item na base do cliente. A API irá retonar este mesmo código, para que sua função de buscar o campo no banco tenha mais desempenho no momento de aplicar as tributações;
  • ean (string, 14) - Código de Barras do item (Caso o item não tenha EAN, repita aqui o codinterno);
  • descricao (string, 250) - Descrição do item;
  • icms (float) - Percentual do ICMS de Saída *Se o item tiver FCP (Fundo de Combate a Pobreza), enviar somado ao ICMS! *Opcional para diagnóstico!;
  • ncm (string, 8) - NCM do item *Opcional para diagnóstico!;
  • pis (float) - Percentual do PIS do item *Opcional para diagnóstico!;
  • cofins (float) - Percentual do COFINS do item *Opcional para diagnóstico!;
  • icmsCst (string, 3) - Código do ICMS do item *Opcional para diagnóstico (Caso seja Regime Real ou Regime Presumido)!;
  • csosn (string, 3) - CSOSN do item *Opcional para diagnóstico (Caso seja Regime Simples Nacional)!;
  • cstPisSaida (string, 2) - CST Saída do item *Opcional para diagnóstico!;
  • cfop (string, 4) - CFOP do item *Opcional para diagnóstico!;
  • cest (string, 8) - CEST do item *Opcional para diagnóstico!;
  • regime (string, 250) - Regime tributario Embora opcional, é recomendável incluir o 'regime' ['simples', 'real' ou 'presumido] nas requisições para assegurar precisão. Caso não informado, utilizaremos o regime informado no ato do cadastro da empresa. Sua colaboração é fundamental para operações livres de erros.;
Bloco estrutural de exemplo para envio:
[ {"codinterno":"1A", "ean": "7891000100103", "descricao": "Leite Condensado Moça", "ncm": "04029900", "icms": 20, "pis": 1.650, "cofins": 7.600}, {"codinterno":"2A", "ean": "7891203010056", "descricao": "Pão de Forma Panco", "ncm": "30049029", "icms": 0.00, "pis": 0.00, "cofins": 0.00}, {"codinterno":"3A", "ean": "7891213141516", "descricao": "Descrição de produto não cadastrado no site", "ncm": "", "icms": "", "pis": "", "cofins": ""} ]
Item 1 Parâmetros para teste:

Nosso sistema oferece aos seus clientes o recurso de Monitoramento de Vendas em Tempo Real. Desta forma, caso o cliente efetue vendas no PDV com alguma informação tributária incorreta, nós monitoramos e notificamos sobre os itens que apresentaram problemas na última venda. Desta forma, o cadastro pode ser corrigido e na próxima venda o erro não ocorrerá.

É o fim das vendas com divergências tributárias!

Nesta função, listamos a tributação correta de todos os itens que apresentaram divergências no monitoramento dentro da última hora. Desta forma, é possível atualizar o cadastro do seu cliente e nas próximas vendas, todos os tributos estarão corrigidos. Automatizamos o processo, o cliente não precisará efetuar estas correções manualmente e estes itens não apresentarão mais divergências.

Sugestão de usabilidade e integração:
  1. Efetuar esta consulta de hora em hora;
  2. Atualizar os tributos no cadastro do cliente através do Código de Barras e informar em sua base o nosso idsegmento (sempre importante para futuras chegagens de atualizações tributárias);
Fluxograma de funcionamento:

Utilize o formulário abaixo para efetuar testes de consulta em tempo real em nossa API:

Função e parâmetros obrigatórios:
URL para receber os tributos via GET dos itens que apresentaram divergências nas vendas monitoradas na última hora:

Esta documentação descreve o uso da API de Diferencial de Alíquota ICMS que fornece as informações fiscais para a realização do cálculo do diferencial de alíquota na venda de mercadorias para consumidores finais não contribuintes do ICMS localizados em outro estado.

Diferencial de Alíquota (DIFAL) é a diferença entre a alíquota interna do Estado destinatário e a alíquota interestadual do Estado remetente, para a mercadoria comercializada.

Sugestão de usabilidade e integração:
  1. Cada envio para a API deve conter um lote de até 50 itens por vez. Após o retorno da API, envie mais 50 e repita o processo até revisar os campos de informações do DIFAL, de toda a base de produtos do cliente;
  2. A API irá retornar os dados do DIFAL de cada item no array difal.
  3. Em todas as consultas, sempre retornaremos o ICMSUFOrigem. Para os dados de Origem e ICMSUFDest. Para os dados de Destino
  4. Os itens não encontrados na base do site ficarão na listagem de pendência da equipe tributária e serão cadastrados o quanto antes;
Fluxograma de funcionamento:

Utilize o formulário abaixo para efetuar testes de consulta em tempo real em nossa API:

Função e parâmetros obrigatórios:
URL para o envio do lote de itens da base do cliente para a Revisão Fiscal via POST no Figura Fiscal API:
Estrutura dos itens a serem enviados via POST:
  • codinterno (string, 15) - Código interno do item na base do cliente. A API irá retonar este mesmo código, para que sua função de buscar o campo no banco tenha mais desempenho no momento de aplicar as tributações;
  • ean (string, 14) - Código de Barras do item (Caso o item não tenha EAN, repita aqui o codinterno);
  • descricao (string, 250) - Descrição do item;
  • regime (string, 250) - Regime tributario Embora opcional, é recomendável incluir o 'regime' ['simples, 'real' ou 'presumido] nas requisições para assegurar precisão. Caso não informado, utilizaremos o regime informado no ato do cadastro da empresa. Sua colaboração é fundamental para operações livres de erros.;
Bloco estrutural de exemplo para envio:
[ {"codinterno":"1A", "ean": "7891000100103", "descricao": "Leite Condensado Moça"} ]
Detalhamento de JSON Retorno:
  • “cfop": "6.108": - Código Fiscal de Operações e Prestações das SAÍDAS de mercadorias e bens, em comércio interestadual, para consumidor final não contribuinte do ICMS. (para CRT = 1, 2 e 3);
  • "cst": - Código do CST de SAÍDA do ICMS (associados do Lucro Real, Lucro Presumido e Simples Nacional com Excesso de Sublimite). (para CRT = 2 e 3);
  • "cBenef": - Código do Benefício Fiscal da Unidade Federativa de Origem, quando embasamento legal permite comércio interestadual com benefício. (para CRT = 2 e 3);
  • "motDesICMS": - Motivo da Desoneração do ICMS. (para CRT = 2 e 3);
  • "descMotDesICMS": - Descrição do Motivo da Desoneração do ICMS. (para CRT = 2 e 3);
  • "desconto_icms": - Identifica se o ICMS Desonerado deve ser descontado do produto (desoneracao_descontar_icms = 1). (para CRT = 2 e 3);
  • "pRedBC": - Percentual de Redução da Base de Cálculo do ICMS. (para CRT = 2 e 3);
  • "csosn": - Código do CSOSN de SAÍDA interestadual do ICMS (associados do Simples Nacional). (para CRT = 1);
  • "pST": - Alíquota suportada pelo Consumidor Final: Deve ser informada a alíquota do cálculo do ICMS-ST, já incluso o FCP. Exemplo: alíquota da mercadoria na venda ao consumidor final = 18% e 2% de FCP. A alíquota a ser informada no campo pST deve ser 20%. (para CRT = 1);
  • "pICMSEfet": - Alíquota do ICMS efetiva: Alíquota do ICMS na operação a consumidor final, caso estivesse submetida ao regime comum de tributação. (para CRT = 1);
  • "pICMS_origem->UF": - Percentual da alíquota ICMS utilizada na comercialização interestadual UF origem x UF destino, quando mercadoria nacional (para CRT = 2 e 3);
  • "pICMS_origem->IM": - Percentual da alíquota ICMS utilizada na comercialização interestadual UF origem x UF destino, quando mercadoria importada (para CRT = 2 e 3);
  • "pICMSDeson_origem->UF": - Percentual do ICMS Desonerado (Deve ser somado ao desoneracao_fcp para calcular o "Valor do ICMS Desonerado". (para CRT = 2 e 3);
  • "pICMSUFDest": - percentual do ICMS interno da Unidade Federativa de destino, para a mercadoria. (para CRT = 1, 2 e 3);
  • "pFCPUFDest": - percentual do FCP interno da Unidade Federativa de destino, para a mercadoria. (para CRT = 1, 2 e 3);
  • "pICMSInter": - Percentual do ICMS Interestadual para a Unidade Federativa de destino. (para CRT = 2 e 3);
  • "pRedBC": - percentual de Redução da Base de Cálculo, quando mercadoria possuir benefício fiscal interno na Unidade Federativa de destino. (para CRT = 1, 2 e 3);
  • "aliqICMSEfet: - Alíquota do ICMS efetiva na UF Destino: Alíquota efetiva do ICMS, na UF destino, referente à mercadoria comercializada, caso a mesma esteja alcançada por benefício fiscal de Redução da Base de Cálculo na UF destino.;
  • "pICMSInterPart" (100%): - percentual de partilha do ICMS que cabe à Unidade Federativa de destino, a partir de 2019. (para CRT = 1, 2 ou 3);
  • "pICMSInterPart" (100%): - percentual de partilha do ICMS que cabe à Unidade Federativa de destino, a partir de 2019. (para CRT = 1, 2 ou 3);
  • "icmsLeiDifalDestinoSN": - Embasamento legal referente à alíquota interna do ICMS, na UF destino, quando remetente optante pelo Simples Nacional;
  • "icmsLeiDifalDestinoRN": - Embasamento legal referente à alíquota interna do ICMS, na UF destino, quando remetente do Regime Normal;
  • "baseUnica: - Representada por "1" caso a SEFAZ da UF destino optar por calcular o DIFAL Não Contribuinte, utilizando Base de Cálculo Única. Representada por "0", caso a SEFAZ da UF destino optar por calcular o DIFAL Não Contribuinte, utilizando Base de Cálculo Dupla;
  • "leiBaseICMS: - Embasamento legal referente à opção pela utilização da Base Única ou Base Dupla, pela UF destino;
  • "linkLeiBaseICMS: - Link do embasamento legal referente à opção pela utilização da Base Única ou Base Dupla, pela UF destino;
Item 1 Parâmetros para teste: