API Cálculo em Lote

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

Introdução
Acesso

Método e URLs
Autenticação
Coleção de chamadas

API de solicitação

Descrição dos campos de chamada
Descrição dos campos de retorno
Exemplo de chamada
Exemplos de retorno

API de retorno

Descrição dos campos de retorno
Exemplos de chamada
Exemplos de retorno

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.

Acesso

Método e URLs

Comunicação: REST/JSON

Para acessar a coleção de chamadas Clique Aqui.

Swagger Solicitação de Regras
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

Descrição	Versão	Grupo Swagger	Método	URL Endpoint
Solicitar Regras	v1	SolicitacaoRegra	Post	http://api-diagnosticofiscal. systax.com.br/api/ solicitacao_regra
Consultar Retorno de Regras	v1	SolicitacaoRegra	Get	https://api-diagnosticofiscal. systax.com.br/api/solicitacao_regra/ {cliente_id}/{protocolo}/{offset}/ {quantity}

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.

Acesso

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.

Acesso

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.

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.

Campo	Descrição	Tipo
id_cliente	ID do cliente	String
Informações relativas ao produto
Item	Sequencial	String
codigo_produto	Código	String
origem_produto	Origem do material	String
ncm	NCM	String
ex_tipi	ExTIPI	String
ean	EAN	String
descricao	Descrição	String
data_cálculo	Data de cálculo da regra	String
Informações relativas ao cenário
uf_origem	UF origem	String
uf_destino	UF destino	String
natureza_operacao	Natureza de operação	String
perfil_origem	Perfil de origem	String
perfil_destino	Perfil de destinação	String
finalidade	Finalidade(somente para cenários de entrada)	String
ent_sai	Tipo de entrada e saída	String
municipio_origem	Múnicípio de origem	String
municipio_destino	Múnicípio de destino	String

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":

Código	Tipo entrada/saída
0	Entrada
1	Saída

API de solicitação

Descrição dos campos de retorno

Campo	Descrição	Tipo
protocolo	Número do protocolo	String
data	Data e hora de geração do protocolo	String
success	Status	Boolean
message	Mensagem do status	String

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":

Código de retorno	Descrição	success	message
200	/	true	Consulta enviada com sucesso
400	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)	false	Dados inválidos
400	Cenário inválido - é necessário informar os campos uf_origem, uf_destino, natureza_operacao, perfil_origem, perfil_destino e ent_sai	false	Dados inválidos
401	/	false	Não autorizado

API de solicitação

Exemplo de chamada

Lista de produtos e cenários em JSON:

{
"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": ""
}
}
]
}

API de solicitação

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.

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:

Campo	Descrição	Tipo
data	Dados de retorno do cálculo das regras	String
success	true	Boolean
message	Mensagem de retorno da API	String
record_count	Quantidade de regras calculadas	Numeric

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

Código de retorno	success	message
200	true	Regras processadas
200	true	Regras ainda sendo processadas
400	false	Erro inesperado, tente novamente mais tarde
401	false	Não autorizado

API de retorno

Exemplos de chamada

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.

API de retorno

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
}