# API Cálculo em Lote

Manual da API Cálculo em Lote - versão 2 - 23/11/2023

# Introdução

As duas APIs contempladas neste documento são responsáveis, respectivamente, por solicitar as regras em lote que serão calculadas através de uma lista de produtos e cenários, e por retornar o resultado do cálculo assíncrono.

# Acesso

Informações de acesso da API.

# Método e URLs

**Comunicação:** REST/JSON  
  
**Para acessar a coleção de chamadas** [Clique Aqui](https://www.dropbox.com/scl/fi/cusk4th66sm7rn0tj2tos/Api-C-lculo-em-Lote.v1.postman_collection.json?rlkey=gdmg7we4wcy5iwukgzsg6mxbb&dl=0).

**Swagger Solicitação de Regras**  
[https://api-diagnosticofiscal.systax.com.br/swagger/index.html?urls.primaryName=Api%20Solicita%C3%A7%C3%A3o%20de%20Regras](https://api-diagnosticofiscal.systax.com.br/swagger/index.html?urls.primaryName=Api%20Solicita%C3%A7%C3%A3o%20de%20Regras)  
  
**Listagem dos Endpoints que contemplam o manual de Solicitação de Regras**

<table border="2" id="bkmrk-descri%C3%A7%C3%A3o-vers%C3%A3o-gru" style="width: 96.5476%;"><thead><tr><th scope="col" style="width: 23.1458%;">Descrição

</th><th scope="col" style="width: 14.1944%;">Versão

</th><th scope="col" style="width: 17.5192%;">Grupo Swagger

</th><th scope="col" style="width: 9.97442%;">Método

</th><th scope="col" style="width: 35.0384%;">URL Endpoint

</th></tr></thead><tbody><tr><td style="width: 23.1458%;">Solicitar Regras

</td><td style="width: 14.1944%;">v1

</td><td style="width: 17.5192%;">SolicitacaoRegra

</td><td style="width: 9.97442%;">Post

</td><td style="width: 35.0384%;">http://api-diagnosticofiscal.  
systax.com.br/api/  
solicitacao\_regra</td></tr><tr><td style="width: 23.1458%;">Consultar Retorno de Regras

</td><td style="width: 14.1944%;">v1

</td><td style="width: 17.5192%;">SolicitacaoRegra</td><td style="width: 9.97442%;">Get

</td><td style="width: 35.0384%;">https://api-diagnosticofiscal.  
systax.com.br/api/solicitacao\_regra/  
{**cliente\_id**}/{**protocolo**}/{**offset**}/  
{**quantity**}</td></tr></tbody></table>

- **cliente\_id**: ID do cliente. Entre em contato com a Systax para obtê-lo;
- **protocolo**: Número de protocolo gerado pela API de solicitação de regras;
- **offset**: quantidade de registros exibidos;
- **quantity**: quantidade de registros á exibir;

**Observação**: Os parâmetros "offset" e "quantity" são usados para a paginação e serão detalhados o longo da documentação.

# Autenticação

A autenticação nas API´s de solicitação e retorno de regras é feita via bearer token. Para mais informações sobre como gerá-lo, consultar a última versão do manual da API de geração de token.

# Coleção de chamadas

{  
 "info": {  
 "\_postman\_id": "05c4a824-65e1-4163-a1ae-823e0e0aa157",  
 "name": "Api - Cálculo em Lote.v1",  
 "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",  
 "\_exporter\_id": "21298242"  
 },  
 "item": \[  
 {  
 "name": "Gerar Token",  
 "item": \[  
 {  
 "name": "Token",  
 "request": {  
 "auth": {  
 "type": "basic",  
 "basic": \[  
 {  
 "key": "password",  
 "value": "",  
 "type": "string"  
 },  
 {  
 "key": "username",  
 "value": "",  
 "type": "string"  
 }  
 \]  
 },  
 "method": "GET",  
 "header": \[\],  
 "url": {  
 "raw": "http://app.systax.com.br/platform/access-token",  
 "protocol": "http",  
 "host": \[  
 "app",  
 "systax",  
 "com",  
 "br"  
 \],  
 "path": \[  
 "platform",  
 "access-token"  
 \]  
 }  
 },  
 "response": \[\]  
 }  
 \]  
 },  
 {  
 "name": "Solicitação de Regra",  
 "item": \[  
 {  
 "name": "Teste 1",  
 "request": {  
 "auth": {  
 "type": "bearer",  
 "bearer": \[  
 {  
 "key": "token",  
 "value": "",  
 "type": "string"  
 }  
 \]  
 },  
 "method": "POST",  
 "header": \[\],  
 "body": {  
 "mode": "raw",  
 "raw": "{\\r\\n \\"id\_cliente\\":\\"\\",\\r\\n \\"produtoCenario\\":\[\\r\\n {\\r\\n \\"produtos\\":\[\\r\\n {\\r\\n \\"item\\":null,\\r\\n \\"codigo\_produto\\":null,\\r\\n \\"origem\_produto\\":\\"7\\",\\r\\n \\"ncm\\":\\"33030010\\",\\r\\n \\"ex\_tipi\\":null,\\r\\n \\"ean\\":\\"\\",\\r\\n \\"descricao\\":null,\\r\\n \\"data\_calculo\\":\\"09-05-2023\\"\\r\\n }\\r\\n \],\\r\\n \\"cenario\\":{\\r\\n \\"uf\_origem\\":\\"SP\\",\\r\\n \\"uf\_destino\\":\\"SP\\",\\r\\n \\"natureza\_operacao\\":\\"121\\",\\r\\n \\"perfil\_origem\\":\\"24,843\\",\\r\\n \\"perfil\_destino\\":\\"140\\",\\r\\n \\"finalidade\\":\\"\\",\\r\\n \\"ent\_sai\\":\\"1\\",\\r\\n \\"municipio\_origem\\":null,\\r\\n \\"municipio\_destino\\":null\\r\\n } \\r\\n }\\r\\n \]\\r\\n}",  
 "options": {  
 "raw": {  
 "language": "json"  
 }  
 }  
 },  
 "url": {  
 "raw": "http://api-diagnosticofiscal.systax.com.br/api/solicitacao\_regra",  
 "protocol": "http",  
 "host": \[  
 "api-diagnosticofiscal",  
 "systax",  
 "com",  
 "br"  
 \],  
 "path": \[  
 "api",  
 "solicitacao\_regra"  
 \]  
 }  
 },  
 "response": \[\]  
 },  
 {  
 "name": "Teste 2",  
 "request": {  
 "auth": {  
 "type": "bearer",  
 "bearer": \[  
 {  
 "key": "token",  
 "value": "",  
 "type": "string"  
 }  
 \]  
 },  
 "method": "POST",  
 "header": \[\],  
 "body": {  
 "mode": "raw",  
 "raw": "{\\r\\n\\"id\_cliente\\":\\"\\",\\r\\n\\"produtoCenario\\":\[\\r\\n{\\r\\n\\"produtos\\":\[\\r\\n{\\r\\n\\"item\\":null,\\r\\n\\"codigo\_produto\\":null,\\r\\n\\"origem\_produto\\":\\"0\\",\\r\\n\\"ncm\\":\\"40103900\\",\\r\\n\\"ex\_tipi\\":null,\\r\\n\\"ean\\":\\"\\",\\r\\n\\"descricao\\":null,\\r\\n\\"data\_calculo\\":\\"01/02/2022 00:00:00\\"\\r\\n}\\r\\n\],\\r\\n\\"cenario\\":{\\r\\n\\"uf\_origem\\":\\"MT\\",\\r\\n\\"uf\_destino\\":\\"MT\\",\\r\\n\\"natureza\_operacao\\":\\"121\\",\\r\\n\\"perfil\_origem\\":\\"2\\",\\r\\n\\"perfil\_destino\\":\\"46\\",\\r\\n\\"finalidade\\":\\"\\",\\r\\n\\"ent\_sai\\":\\"1\\",\\r\\n\\"municipio\_origem\\":null,\\r\\n\\"municipio\_destino\\":null\\r\\n }\\r\\n }\\r\\n \]\\r\\n}",  
 "options": {  
 "raw": {  
 "language": "json"  
 }  
 }  
 },  
 "url": {  
 "raw": "http://api-diagnosticofiscal.systax.com.br/api/solicitacao\_regra",  
 "protocol": "http",  
 "host": \[  
 "api-diagnosticofiscal",  
 "systax",  
 "com",  
 "br"  
 \],  
 "path": \[  
 "api",  
 "solicitacao\_regra"  
 \]  
 }  
 },  
 "response": \[\]  
 }  
 \]  
 },  
 {  
 "name": "Retorno da Regra",  
 "item": \[  
 {  
 "name": "Teste 1",  
 "request": {  
 "auth": {  
 "type": "bearer",  
 "bearer": \[  
 {  
 "key": "token",  
 "value": "",  
 "type": "string"  
 }  
 \]  
 },  
 "method": "GET",  
 "header": \[\],  
 "url": {  
 "raw": "http://api-diagnosticofiscal.systax.com.br/api/solicitacao\_regra/IdCliente/Protocolo/offset/quantity",  
 "protocol": "http",  
 "host": \[  
 "api-diagnosticofiscal",  
 "systax",  
 "com",  
 "br"  
 \],  
 "path": \[  
 "api",  
 "solicitacao\_regra",  
 "IdCliente",  
 "Protocolo",  
 "offset",  
 "quantity"  
 \]  
 }  
 },  
 "response": \[\]  
 },  
 {  
 "name": "Teste 2",  
 "request": {  
 "auth": {  
 "type": "bearer",  
 "bearer": \[  
 {  
 "key": "token",  
 "value": "",  
 "type": "string"  
 }  
 \]  
 },  
 "method": "GET",  
 "header": \[\],  
 "url": {  
 "raw": "http://api-diagnosticofiscal.systax.com.br/api/solicitacao\_regra/IdCliente/Protocolo/offset/quantity",  
 "protocol": "http",  
 "host": \[  
 "api-diagnosticofiscal",  
 "systax",  
 "com",  
 "br"  
 \],  
 "path": \[  
 "api",  
 "solicitacao\_regra",  
 "IdCliente",  
 "Protocolo",  
 "offset",  
 "quantity"  
 \]  
 }  
 },  
 "response": \[\]  
 }  
 \]  
 }  
 \]  
}

# API de solicitação

Chamada, retorno e exemplos da API de solicitação.

# Descrição dos campos de chamada

Um JSON com uma lista de produtos e cenários deve ser informado na chamada da API de solicitação de regras em lote conforme o detalhamento abaixo. Essa API suporta uma lista de 500 regras tributárias.

<table border="1" cellpadding="1" cellspacing="1" id="bkmrk-campo-descri%C3%A7%C3%A3o%C2%A0-tip"><tbody><tr><td>**Campo**</td><td>**Descrição** </td><td>**Tipo**</td></tr><tr><td>id\_cliente</td><td>ID do cliente</td><td>String</td></tr><tr><td colspan="3">**Informações relativas ao produto**</td></tr><tr><td>Item</td><td>Sequencial </td><td>String</td></tr><tr><td>codigo\_produto</td><td>Código</td><td>String</td></tr><tr><td>origem\_produto</td><td>Origem do material</td><td>String</td></tr><tr><td>ncm</td><td>NCM </td><td>String</td></tr><tr><td>ex\_tipi</td><td>ExTIPI </td><td>String</td></tr><tr><td>ean</td><td>EAN </td><td>String</td></tr><tr><td>descricao</td><td>Descrição </td><td>String</td></tr><tr><td>data\_cálculo</td><td>Data de cálculo da regra</td><td>String</td></tr><tr><td colspan="3">**Informações relativas ao cenário**</td></tr><tr><td>uf\_origem</td><td>UF origem </td><td>String</td></tr><tr><td>uf\_destino</td><td>UF destino </td><td>String</td></tr><tr><td>natureza\_operacao</td><td>Natureza de operação </td><td>String</td></tr><tr><td>perfil\_origem</td><td>Perfil de origem</td><td>String</td></tr><tr><td>perfil\_destino</td><td>Perfil de destinação</td><td>String</td></tr><tr><td>finalidade</td><td>Finalidade(somente para cenários de entrada)</td><td>String</td></tr><tr><td>ent\_sai</td><td>Tipo de entrada e saída</td><td>String</td></tr><tr><td>municipio\_origem</td><td>Múnicípio de origem</td><td>String</td></tr><tr><td>municipio\_destino</td><td>Múnicípio de destino</td><td>String</td></tr></tbody></table>

Para obter os códigos de referência para o preenchimentos dos campos de **origem do produto**, **natureza de operação, perfil origem, perfil destino e finalidade,** acesse a última versão do manual de "Tabelas Auxiliares".

**Tabela de referência do campo "ent\_sai":**

<table border="1" cellpadding="1" cellspacing="1" id="bkmrk-c%C3%B3digo-tipo-entrada%2F"><tbody><tr><td>**Código**</td><td>**Tipo entrada/saída**</td></tr><tr><td>0</td><td>Entrada</td></tr><tr><td>1</td><td>Saída</td></tr></tbody></table>

# Descrição dos campos de retorno

<table border="1" cellpadding="1" cellspacing="1" id="bkmrk-campo-descri%C3%A7%C3%A3o-tipo"><tbody><tr><td>**Campo**</td><td>**Descrição**</td><td>**Tipo**</td></tr><tr><td>protocolo</td><td>Número do protocolo</td><td>String</td></tr><tr><td>data</td><td>Data e hora de geração do protocolo</td><td>String</td></tr><tr><td>success</td><td>Status</td><td>Boolean</td></tr><tr><td>message</td><td>Mensagem do status</td><td>String</td></tr></tbody></table>

**Observação**: O protocolo gerado será informado na API de retorno para obter o resultado do cálculo das regras tributárias. Ele deve ser armazenado para consultas posteriores.

**Tabela de referência dos campos "success" e "message":**

<table border="1" cellpadding="1" cellspacing="1" id="bkmrk-c%C3%B3digo-de-retorno-de" style="width: 100%;"><tbody><tr><td style="width: 12.0343%;">**Código de retorno**

</td><td style="width: 65.7964%;">**Descrição**

</td><td style="width: 9.65435%;">**success**

</td><td style="width: 12.5149%;">**message**

</td></tr><tr><td style="width: 12.0343%;">200

</td><td style="width: 65.7964%;">/

</td><td style="width: 9.65435%;">true

</td><td style="width: 12.5149%;">Consulta enviada com sucesso

</td></tr><tr><td style="width: 12.0343%;">400

</td><td style="width: 65.7964%;">Produto inválido - é necessário informar uma das combinações de campos: (codigo\_produto + origem\_produto + ncm + ean) OU (codigo\_produto + origem\_produto) OU (ncm + origem\_produto) OU (ean + origem\_produto)

</td><td style="width: 9.65435%;">false

</td><td style="width: 12.5149%;">Dados inválidos

</td></tr><tr><td style="width: 12.0343%;">400

</td><td style="width: 65.7964%;">Cenário inválido - é necessário informar os campos uf\_origem, uf\_destino, natureza\_operacao, perfil\_origem, perfil\_destino e ent\_sai

</td><td style="width: 9.65435%;">false

</td><td style="width: 12.5149%;">Dados inválidos

</td></tr><tr><td style="width: 12.0343%;">401

</td><td style="width: 65.7964%;">/

</td><td style="width: 9.65435%;">false

</td><td style="width: 12.5149%;">Não autorizado

</td></tr></tbody></table>

# Exemplo de chamada

<u>Lista de produtos e cenários em JSON</u>:

{  
 "id\_cliente": "**id do cliente**",  
 "produtoCenario": \[  
 {  
 "produtos": \[  
 {

 "Item": "1"  
 "codigo\_produto": "**codigo do produto**",  
 "origem\_produto": "1",  
 "ncm": "",  
 "ex\_tipi": "",  
 "ean": "",  
 "descricao": "",  
 "data\_calculo": "2020-01-01"  
 }  
 \],  
 "cenario": {  
 "uf\_origem": "EX",   
 "uf\_destino": "PI",  
 "natureza\_operacao": "43",  
 "perfil\_origem": "682",  
 "perfil\_destino": "1",  
 "finalidade": "43",  
 "ent\_sai": "0",  
 "municipio\_origem": "",  
 "municipio\_destino": ""  
 }  
 }   
 \]  
}

[![Manual_API_Calculo_Lote_001.png](https://documentacao.systax.com.br/uploads/images/gallery/2025-07/scaled-1680-/manual-api-calculo-lote-001.png)](https://documentacao.systax.com.br/uploads/images/gallery/2025-07/manual-api-calculo-lote-001.png)

# Exemplos de retorno

{  
 "data": {  
 "protocolo": "5987a877-cd91-400d-a20d-f8bdbee50993",  
 "data": "2021-03-18T14:13:13.4988597+00:00"  
 },  
 "success": true,  
 "message": "Consulta enviada com sucesso",  
 "record\_count": null  
}

# API de retorno

Retorno e exemplos da API de retorno.

# Descrição dos campos de retorno

Os campos de retorno de tributação das regras calculadas são os mesmos da ferramenta de parametrização fiscal.

Acesse a última versão de documentação no manual de "Conteúdo", no capítulo "Entrega de regras fiscais", página "Detalhamento do retorno da tributação".

**Campos exclusivos da API:**

<table border="1" cellpadding="1" cellspacing="1" id="bkmrk-campo-descri%C3%A7%C3%A3o-tipo"><tbody><tr><td>**Campo**</td><td>**Descrição**</td><td>**Tipo**</td></tr><tr><td>data</td><td>Dados de retorno do cálculo das regras</td><td>String</td></tr><tr><td>success</td><td>true</td><td>Boolean</td></tr><tr><td>message</td><td>Mensagem de retorno da API</td><td>String</td></tr><tr><td>record\_count</td><td>Quantidade de regras calculadas</td><td>Numeric</td></tr></tbody></table>

**Tabela de referência para os campos “success e message”:**

<table border="1" cellpadding="1" cellspacing="1" id="bkmrk-c%C3%B3digo-de-retorno-su"><tbody><tr><td>**Código de retorno**

</td><td>**success**

</td><td>**message**

</td></tr><tr><td colspan="1" rowspan="2">200

</td><td>true

</td><td>Regras processadas

</td></tr><tr><td>true</td><td>Regras ainda sendo processadas</td></tr><tr><td>400</td><td>false</td><td>Erro inesperado, tente novamente mais tarde</td></tr><tr><td>401

</td><td>false

</td><td>Não autorizado

</td></tr></tbody></table>

# Exemplos de chamada

[![Manual_API_Calculo_Lote_002.png](https://documentacao.systax.com.br/uploads/images/gallery/2025-07/scaled-1680-/manual-api-calculo-lote-002.png)](https://documentacao.systax.com.br/uploads/images/gallery/2025-07/manual-api-calculo-lote-002.png)

Para a paginação é necessário combinar os dois parâmetros: "offset" e "quantity" conforme abaixo:

**Requisição 1:**

offset = 0

Quantity = 10

A API irá exibir os primeiros 10 registros da sequência.

**Requisição 2:**

offset = 10

Quantity = 20

Como a API já exibiu os primeiros 10 registros na requisição 1, então atribuímos o valor 10 ao parâmetro "offset" (a API irá desconsiderar os 10 registros listados na requisição anterior), e para o "quantity", a próxima quantidade escolhida para ser exibida, que no exemplo, é de 20.

**Requisição 3:**

offset = 30

Quantity = 10

Como a API já tinha exibido 30 registros nas requisições 1 e 2, então atribuímos o valor 30 ao parâmetro "offset" e foi escolhido mais 10 novos registros para serem exibidos.

**Observação**: Há um limite de 100 regras por requisição.

# Exemplos de retorno

**Regras sendo calculadas:**

{  
 "data": null,  
 "success": true,  
 "message": "Pendente: regras ainda sendo calculadas",  
 "record\_count": 0  
}

**Regras calculadas:**

{  
 "data": {  
 "regras": \[  
 {  
 "status": "Finalizado",  
 "message": "",  
 "produto": {  
 "codigo\_produto": "Código do produto",  
 "origem\_material": "1",  
 "ncm": "",  
 "ex\_tipi": "",  
 "ean": "",  
 "descricao": "",  
 "data\_emissao": "2020-01-01"  
 },  
 "cenario": {  
 "ufOrigem": "EX",  
 "ufDestino": "PI",  
 "natureza\_operacao": "43",  
 "perfil\_origem": "682",  
 "perfil\_destino": "1",  
 "finalidade": "43",  
 "ent\_sai": "0",  
 "municipio\_origem": "",  
 "municipio\_destino": ""  
 },  
 "regra": {  
 "lote": 5728238,  
 "icms": {  
 "cfop": "1556",  
 "cfop\_entrada": "1556",  
 "cest": null,  
 "cst": "00",  
 "bc\_composicao": null,  
 "p\_red\_bc": null,  
 "aliquota": null,  
 "generico": null,  
 "vigencia\_de": null,  
 "dispositivo\_legal": null,  
 "inf\_adicionais": null,  
 "bc\_composicao\_sn\_especial": null,  
 "bc\_composicao\_fcp": null,  
 "percentual\_diferimento": null,  
 "aliquota\_cf": null,  
 "aliquota\_sn\_especial": null,  
 "aliquota\_desonerada": null,  
 "fcp": null,  
 "valor\_pauta": null,  
 "unidade\_pauta": null,  
 "dif\_aliq\_nao\_contrib": null,  
 "vigencia\_ate": null,  
 "observacoes": null,  
 "icms\_st": null,  
 "icms\_uf\_dest": null,  
 "estatistica": null,  
 "severidade": null,  
 "ncm": null,  
 "extipi": null,  
 "orig": null,  
 "cprod": null  
 },  
 "credito\_icms": {  
 "indicador\_credito": "0",  
 "cst\_entrada": "90",  
 "percentual\_credito": null,  
 "vigencia\_de": null,  
 "vigencia\_ate": null,  
 "dispositivo\_legal": null,  
 "generico": null,  
 "observacoes": null  
 },  
 "icms\_uf\_dest": null,  
 "ipi": {  
 "cst": "00",  
 "cenq": null,  
 "bc\_composicao": null,  
 "aliquota": null,  
 "generico": null,  
 "vigencia\_de": null,  
 "vigencia\_ate": null,  
 "dispositivo\_legal": null,  
 "p\_red\_bc": null,  
 "p\_red\_aliq": null,  
 "valor\_por\_unid\_trib": null,  
 "p\_red\_val\_imp": null,  
 "observacoes": null,  
 "inf\_adicionais": null,  
 "estatistica": null,  
 "severidade": null  
 },  
 "credito\_ipi": {  
 "indicador\_credito": "0",  
 "cst\_entrada": "49",  
 "percentual\_credito": null,  
 "generico": null,  
 "vigencia\_de": null,  
 "vigencia\_ate": null,  
 "dispositivo\_legal": null,  
 "observacoes": null  
 },  
 "pis": {  
 "cst": "00",  
 "bc\_composicao": null,  
 "aliquota": null,  
 "vigencia\_de": null,  
 "vigencia\_ate": null,  
 "dispositivo\_legal": null,  
 "p\_red\_bc": null,  
 "aliquota\_especifica": null,  
 "generico": null,  
 "observacoes": null,  
 "inf\_adicionais": null,  
 "codigo\_natureza\_receita": null,  
 "estatistica": null,  
 "severidade": null  
 },  
 "credito\_pis": {  
 "indicador\_credito": "0",  
 "cst\_entrada": "70",  
 "vigencia\_de": null,  
 "vigencia\_ate": null,  
 "dispositivo\_legal": null,  
 "percentual\_credito": null,  
 "generico": null,  
 "observacoes": null  
 },  
 "cofins": {  
 "cst": "00",  
 "bc\_composicao": null,  
 "aliquota": null,  
 "vigencia\_de": null,  
 "vigencia\_ate": null,  
 "dispositivo\_legal": null,  
 "p\_red\_bc": null,  
 "aliquota\_especifica": null,  
 "generico": null,  
 "observacoes": null,  
 "inf\_adicionais": null,  
 "codigo\_natureza\_receita": null,  
 "estatistica": null,  
 "severidade": null  
 },  
 "credito\_cofins": {  
 "indicador\_credito": "0",  
 "cst\_entrada": "70",  
 "vigencia\_de": null,  
 "vigencia\_ate": null,  
 "dispositivo\_legal": null,  
 "percentual\_credito": null,  
 "generico": null,  
 "observacoes": null  
 },  
 "antecipacao": null,  
 "icms\_st": null  
 }  
 }  
 \]  
 },  
 "success": true,  
 "message": "Regras processadas",  
 "record\_count": 1  
}