Integração API OrionTax
Guia técnico completo para integração do seu ERP com a plataforma de saneamento tributário da OrionTax — consultoria especializada em tributação para supermercados.
Visão Geral
O que é a API OrionTax e como ela funciona no contexto tributário.
A API OrionTax é o canal de integração entre o seu ERP e a plataforma de consultoria tributária. Ela permite que os produtos de revenda sejam enviados periodicamente à OrionTax, onde passam por um processo de saneamento e validação fiscal. Após o processamento, os dados corrigidos ficam disponíveis para consulta.
A integração é assíncrona: o envio confirma o recebimento imediatamente, e o processamento fiscal ocorre em background. O resultado é consultado em uma chamada separada.
Base URL
https://oriontax.f5sys.com.br/api
Endpoints disponíveis
| Método | Rota | URL completa | Descrição |
|---|---|---|---|
| POST | /v2/enviar/ |
/api/v2/enviar/ |
Envio em lote de produtos para saneamento tributário |
| GET | /v2/receber/ |
/api/v2/receber/ |
Consulta dos produtos já processados e corrigidos |
Autenticação
Todos os endpoints requerem autenticação via Bearer Token.
A OrionTax utiliza autenticação por Token. O token é gerado por cliente
e deve ser enviado no cabeçalho Authorization em todas as requisições.
O token é fornecido diretamente pela OrionTax no cadastro do cliente.
Como usar o token nas requisições
Authorization: Bearer seu_token_aqui_fornecido_pela_oriontax
Content-Type: application/json
import requests
TOKEN = "seu_token_aqui"
BASE_URL = "https://oriontax.f5sys.com.br/api"
headers = {
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json"
}
<?php
$token = "seu_token_aqui";
$baseUrl = "https://oriontax.f5sys.com.br/api";
$headers = [
"Authorization: Bearer {$token}",
"Content-Type: application/json",
];
const TOKEN = "seu_token_aqui";
const BASE_URL = "https://oriontax.f5sys.com.br/api";
const headers = {
"Authorization": `Bearer ${TOKEN}`,
"Content-Type": "application/json"
};
Fluxo de Integração
Como o processo completo de saneamento tributário acontece do início ao fim.
do Cliente
OrionTax
Inclui NCM, CFOP, CST ICMS/PIS/COFINS e campos IBS/CBS (Reforma Tributária).
job_id para rastreamento.O processamento fiscal ainda não ocorreu neste momento.
c_class_trib), aplica reduções (p_red_aliq_ibs /
p_red_aliq_cbs) e define o CST IBS/CBS.
?page=1&page_size=500 para catálogos grandes.
inf_ad_fisco, reduções de BC e muito mais.
Os itens consultados são marcados como sincronizados internamente.
Tabela resumo do fluxo
| Etapa | Quem executa | Ação | Frequência |
|---|---|---|---|
| 1 — Envio | ERP do Cliente | POST /v2/enviar/ com todos os produtos destinados a venda |
Diária |
| 2 — Confirmação | OrionTax | Retorna job_id + HTTP 201. Processamento não iniciado ainda. |
Imediato (síncrono) |
| 3 — Processamento | OrionTax | Saneamento: ICMS · PIS/COFINS · IBS/CBS · cBenef · NCM · Reduções | Assíncrono (minutos) |
| 4 — Consulta | ERP do Cliente | GET /v2/receber/ — busca diária dos produtos saneados |
Diária |
| 5 — Sincronização | ERP do Cliente | Atualiza cadastro fiscal interno com dados retornados pela OrionTax | Sempre após a consulta |
Enviar Produtos
Envio em lote de produtos para saneamento tributário.
Recebe um array JSON com os produtos do cliente e os enfileira para
processamento fiscal assíncrono. A resposta confirma o recebimento imediatamente com um
job_id — o saneamento tributário ocorre em background.
Campos do Body (array de objetos)
| Campo | Tipo | Status | Descrição |
|---|---|---|---|
| codigo | string | Obrigatório | Código interno do produto no ERP |
| descricao | string | Obrigatório | Descrição completa do produto |
| ncm | string | Obrigatório | Nomenclatura Comum do Mercosul — 8 dígitos (ex: "10063021") |
| cfop | integer | Obrigatório | Código Fiscal de Operações (ex: 5102) |
| icms_cst | integer | Obrigatório | CST do ICMS (ex: 0, 20, 40, 60) |
| icms_aliquota | integer | Obrigatório | Alíquota nominal do ICMS em % (ex: 18) |
| pis_cst | integer | Obrigatório | CST do PIS (ex: 1, 49) |
| pis_aliquota | float | Obrigatório | Alíquota do PIS em % (ex: 1.65) |
| cofins_aliquota | float | Obrigatório | Alíquota da COFINS em % (ex: 7.6) |
| codigo_barras | string | Opcional | Código EAN/GTIN (ex: "7891234567890") |
| cest | string | Opcional | Código CEST — substituição tributária (ex: "0100100") |
| cbenef | string | Opcional | Código de benefício fiscal (ex: "PY01234567") |
| icms_aliquota_reduzida | float | Opcional | Alíquota efetiva após redução de BC. Calculada automaticamente se percentual_redbcde informado. |
| percentual_redbcde | float | Opcional | % de redução da base de cálculo. Calcula icms_aliquota_reduzida automaticamente. |
| natureza_receita | integer | Opcional | Código da natureza de receita para PIS/COFINS |
| protege | integer | Opcional | Flag de proteção especial (padrão: 0) |
| Campos da Reforma Tributária — IBS/CBS | |||
| cst_ibs_cbs | string | Opcional | CST IBS/CBS — 3 dígitos (ex: "000", "010") |
| c_class_trib | string | Opcional | Classificação tributária — 8 dígitos (ex: "00012345") |
| aliquota_ibs | float | Opcional | Alíquota do IBS em % (ex: 12.5) |
| aliquota_cbs | float | Opcional | Alíquota da CBS em % (ex: 9.25) |
| p_red_aliq_ibs | float | Opcional | % de redução da alíquota IBS |
| p_red_aliq_cbs | float | Opcional | % de redução da alíquota CBS |
| inf_ad_fisco | boolean | Opcional | true quando sujeito à redução de benefícios (LC 224/2025). Só aplicável com PIS/COFINS = 0. |
Exemplos de Requisição
import requests
TOKEN = "seu_token_aqui"
BASE_URL = "https://oriontax.f5sys.com.br/api"
produtos = [
{
"codigo": "PROD001",
"codigo_barras": "7891234567890",
"descricao": "Arroz Integral 1kg",
"ncm": "10063021",
"cest": "0100100",
"cfop": 5102,
"icms_cst": 0,
"icms_aliquota": 18,
"cbenef": "PY01234567",
"pis_cst": 1,
"pis_aliquota": 1.65,
"cofins_aliquota": 7.6,
"cst_ibs_cbs": "000",
"c_class_trib": "00012345",
"aliquota_ibs": 12.5,
"aliquota_cbs": 9.25,
"p_red_aliq_ibs": 0.0,
"p_red_aliq_cbs": 0.0,
"inf_ad_fisco": False,
},
{
"codigo": "PROD002",
"descricao": "Feijão Preto 1kg",
"ncm": "07133100",
"cfop": 5102,
"icms_cst": 0,
"icms_aliquota": 18,
"pis_cst": 1,
"pis_aliquota": 1.65,
"cofins_aliquota": 7.6,
"percentual_redbcde": 30.0, # calcula icms_aliquota_reduzida automaticamente
}
]
response = requests.post(
f"{BASE_URL}/v2/enviar/",
json=produtos,
headers={
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json"
}
)
print(response.status_code) # 201
print(response.json())
# {"message": "Arquivo recebido. Processamento em background.", "job_id": "42_20241110_153045"}
<?php
$token = "seu_token_aqui";
$baseUrl = "https://oriontax.f5sys.com.br/api";
$produtos = [
[
"codigo" => "PROD001",
"codigo_barras" => "7891234567890",
"descricao" => "Arroz Integral 1kg",
"ncm" => "10063021",
"cest" => "0100100",
"cfop" => 5102,
"icms_cst" => 0,
"icms_aliquota" => 18,
"cbenef" => "PY01234567",
"pis_cst" => 1,
"pis_aliquota" => 1.65,
"cofins_aliquota" => 7.6,
"cst_ibs_cbs" => "000",
"c_class_trib" => "00012345",
"aliquota_ibs" => 12.5,
"aliquota_cbs" => 9.25,
"p_red_aliq_ibs" => 0.0,
"p_red_aliq_cbs" => 0.0,
"inf_ad_fisco" => false,
]
];
$ch = curl_init("{$baseUrl}/v2/enviar/");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($produtos),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$token}",
"Content-Type: application/json",
],
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $httpCode; // 201
echo $response; // {"message": "...", "job_id": "..."}
const TOKEN = "seu_token_aqui";
const BASE_URL = "https://oriontax.f5sys.com.br/api";
const produtos = [
{
codigo: "PROD001",
codigo_barras: "7891234567890",
descricao: "Arroz Integral 1kg",
ncm: "10063021",
cest: "0100100",
cfop: 5102,
icms_cst: 0,
icms_aliquota: 18,
cbenef: "PY01234567",
pis_cst: 1,
pis_aliquota: 1.65,
cofins_aliquota: 7.6,
cst_ibs_cbs: "000",
c_class_trib: "00012345",
aliquota_ibs: 12.5,
aliquota_cbs: 9.25,
p_red_aliq_ibs: 0.0,
p_red_aliq_cbs: 0.0,
inf_ad_fisco: false,
}
];
const response = await fetch(`${BASE_URL}/v2/enviar/`, {
method: "POST",
headers: {
"Authorization": `Bearer ${TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify(produtos),
});
const data = await response.json();
console.log(response.status); // 201
console.log(data.job_id); // "42_20241110_153045"
curl -X POST "https://oriontax.f5sys.com.br/api/v2/enviar/" \
-H "Authorization: Bearer seu_token_aqui" \
-H "Content-Type: application/json" \
-d '[
{
"codigo": "PROD001",
"codigo_barras": "7891234567890",
"descricao": "Arroz Integral 1kg",
"ncm": "10063021",
"cest": "0100100",
"cfop": 5102,
"icms_cst": 0,
"icms_aliquota": 18,
"cbenef": "PY01234567",
"pis_cst": 1,
"pis_aliquota": 1.65,
"cofins_aliquota": 7.6,
"cst_ibs_cbs": "000",
"c_class_trib": "00012345",
"aliquota_ibs": 12.5,
"aliquota_cbs": 9.25,
"p_red_aliq_ibs": 0.0,
"p_red_aliq_cbs": 0.0,
"inf_ad_fisco": false
}
]'
Respostas
{
"message": "Arquivo recebido. Processamento em background.",
"job_id": "42_20241110_153045"
}
// Campo obrigatório ausente em um item:
{
"error": "Campo ncm é obrigatório. Item: PROD001"
}
// Erros de validação em múltiplos campos:
{
"errors": {
"ncm": ["Este campo é obrigatório."],
"descricao": ["Este campo não pode ser vazio."]
}
}
{
"detail": "Credenciais de autenticação não foram fornecidas."
}
Receber Produtos Processados
Consulta dos produtos com dados fiscais validados e corrigidos pela OrionTax.
Retorna todos os produtos do cliente que já passaram pelo saneamento tributário. Suporta paginação opcional. Ao ser consumida, os itens com status "novo" são automaticamente marcados como "sincronizados" na base OrionTax.
Parâmetros de Query (opcionais)
page. Padrão: 100 · Máximo: 500.Com paginação (
?page=1): retorna objeto com
count, total_pages, page, page_size e results.
Para catálogos grandes, use page_size=500.
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| codigo | string | Código interno do produto |
| codigo_barras | string | Código EAN/GTIN |
| descricao | string | Descrição do produto |
| ncm | string | NCM validado (8 dígitos) |
| cest | string | Código CEST (vazio se não aplicável) |
| cfop | integer | CFOP da operação |
| icms_cst | integer | CST do ICMS após saneamento |
| icms_aliquota | integer | Alíquota nominal do ICMS (%) |
| icms_aliquota_reduzida | float | Alíquota efetiva após redução de BC |
| redbcde | float | % de redução da base de cálculo (calculado pela OrionTax) |
| redbcpara | float | % da BC após redução (calculado pela OrionTax) |
| cbenef | string | Código de benefício fiscal (vazio se não aplicável) |
| protege | integer | Flag de proteção especial |
| pis_cst | string | CST do PIS (formato string com 2 dígitos: "01", "49") |
| pis_aliquota | float | Alíquota do PIS após saneamento (%) |
| cofins_cst | string | CST da COFINS |
| cofins_aliquota | float | Alíquota da COFINS após saneamento (%) |
| natureza_receita | string | Código da natureza de receita (vazio se não aplicável) |
| Campos da Reforma Tributária — IBS/CBS | ||
| cst_ibs_cbs | string | null | CST IBS/CBS definido pela OrionTax |
| c_class_trib | string | null | Classificação tributária — 8 dígitos |
| aliquota_ibs | float | null | Alíquota do IBS (%) |
| aliquota_cbs | float | null | Alíquota da CBS (%) |
| p_red_aliq_ibs | float | null | % de redução da alíquota IBS |
| p_red_aliq_cbs | float | null | % de redução da alíquota CBS |
| inf_ad_fisco | boolean | true quando o produto requer informação no campo infAdFisco da NF-e (LC 224/2025) |
Exemplos de Requisição
import requests
TOKEN = "seu_token_aqui"
BASE_URL = "https://oriontax.f5sys.com.br/api"
response = requests.get(
f"{BASE_URL}/v2/receber/",
headers={"Authorization": f"Bearer {TOKEN}"}
)
produtos = response.json() # lista de produtos
print(f"Total: {len(produtos)} produtos")
for p in produtos:
print(f"{p['codigo']} — {p['descricao']}")
print(f" ICMS CST {p['icms_cst']} | {p['icms_aliquota']}% → reduzida {p['icms_aliquota_reduzida']}%")
print(f" PIS {p['pis_cst']} ({p['pis_aliquota']}%) | COFINS {p['cofins_cst']} ({p['cofins_aliquota']}%)")
if p.get("cst_ibs_cbs"):
print(f" IBS/CBS: {p['cst_ibs_cbs']} | IBS {p['aliquota_ibs']}% | CBS {p['aliquota_cbs']}%")
if p.get("inf_ad_fisco"):
print(f" ⚠ inf_ad_fisco = True — informar no campo infAdFisco da NF-e")
<?php
$token = "seu_token_aqui";
$baseUrl = "https://oriontax.f5sys.com.br/api";
$ch = curl_init("{$baseUrl}/v2/receber/");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$token}",
],
]);
$response = curl_exec($ch);
curl_close($ch);
$produtos = json_decode($response, true);
foreach ($produtos as $p) {
echo "{$p['codigo']} — {$p['descricao']}\n";
echo " ICMS: CST {$p['icms_cst']} | {$p['icms_aliquota']}%\n";
echo " PIS: {$p['pis_cst']} ({$p['pis_aliquota']}%)\n";
echo " COFINS: {$p['cofins_cst']} ({$p['cofins_aliquota']}%)\n";
}
const TOKEN = "seu_token_aqui";
const BASE_URL = "https://oriontax.f5sys.com.br/api";
const response = await fetch(`${BASE_URL}/v2/receber/`, {
headers: { "Authorization": `Bearer ${TOKEN}` },
});
const produtos = await response.json();
console.log(`${produtos.length} produtos sincronizados`);
for (const p of produtos) {
console.log(`${p.codigo} — ${p.descricao}`);
console.log(` ICMS: CST ${p.icms_cst} (${p.icms_aliquota}%)`);
if (p.inf_ad_fisco) {
console.warn(` ⚠ ${p.codigo}: inf_ad_fisco = true`);
}
}
# Sem paginação — retorna todos os produtos de uma vez
curl "https://oriontax.f5sys.com.br/api/v2/receber/" \
-H "Authorization: Bearer seu_token_aqui"
# Com paginação — página 1, 500 itens por página
curl "https://oriontax.f5sys.com.br/api/v2/receber/?page=1&page_size=500" \
-H "Authorization: Bearer seu_token_aqui"
import requests
TOKEN = "seu_token_aqui"
BASE_URL = "https://oriontax.f5sys.com.br/api"
def buscar_todos_paginado():
"""Busca todos os produtos usando paginação de 500 por vez."""
todos = []
page = 1
page_size = 500
while True:
resp = requests.get(
f"{BASE_URL}/v2/receber/",
params={"page": page, "page_size": page_size},
headers={"Authorization": f"Bearer {TOKEN}"}
)
data = resp.json()
todos.extend(data["results"])
print(f"Página {data['page']}/{data['total_pages']} "
f"— {len(data['results'])} itens recebidos")
if page >= data["total_pages"]:
break
page += 1
print(f"\nTotal sincronizado: {len(todos)} produtos")
return todos
produtos = buscar_todos_paginado()
# Página 1/3 — 500 itens recebidos
# Página 2/3 — 500 itens recebidos
# Página 3/3 — 347 itens recebidos
# Total sincronizado: 1347 produtos
Respostas
[
{
"codigo": "PROD001",
"codigo_barras": "7891234567890",
"descricao": "Arroz Integral 1kg",
"ncm": "10063021",
"cest": "0100100",
"cfop": 5102,
"icms_cst": 0,
"icms_aliquota": 18,
"icms_aliquota_reduzida": 12.6,
"redbcde": 30.0,
"redbcpara": 70.0,
"cbenef": "PY01234567",
"protege": 0,
"pis_cst": "01",
"pis_aliquota": 1.65,
"cofins_cst": "01",
"cofins_aliquota": 7.6,
"natureza_receita": "101",
"cst_ibs_cbs": "000",
"c_class_trib": "00012345",
"aliquota_ibs": 12.5,
"aliquota_cbs": 9.25,
"p_red_aliq_ibs": 0.0,
"p_red_aliq_cbs": 0.0,
"inf_ad_fisco": false
}
]
{
"count": 1347,
"total_pages": 3,
"page": 1,
"page_size": 500,
"results": [
{ "codigo": "PROD001", "descricao": "Arroz Integral 1kg", ... },
{ "codigo": "PROD002", "descricao": "Feijão Preto 1kg", ... }
]
}
[]
Códigos de Erro
Referência de todos os códigos HTTP retornados pela API.
| Código | Status | Quando ocorre | Como resolver |
|---|---|---|---|
| 201 | Created | Produtos recebidos com sucesso | Salve o job_id para rastreamento |
| 200 | OK | Consulta realizada com sucesso | — |
| 400 | Bad Request | Campo obrigatório ausente ou valor inválido | Verifique o campo indicado na mensagem e corrija o payload |
| 401 | Unauthorized | Token ausente, inválido ou expirado | Verifique o cabeçalho Authorization: Bearer … |
| 403 | Forbidden | Token válido, mas sem permissão para este recurso | Contate a OrionTax para revisar permissões do cliente |
| 500 | Server Error | Erro interno no servidor OrionTax | Aguarde e tente novamente. Persistindo, acione o suporte técnico |
Boas Práticas
Recomendações para uma integração robusta, segura e eficiente.
Frequência de envio e consulta
Envie sempre a lista completa de produtos ativos
Paginação para grandes catálogos
/v2/receber/
com page_size=500. Isso previne timeouts e garante estabilidade mesmo em
catálogos com dezenas de milhares de itens.
Reforma Tributária — IBS/CBS
Tratamento do campo inf_ad_fisco
inf_ad_fisco = true (LC 224/2025), o produto exige que o campo
infAdFisco da NF-e seja preenchido com a observação sobre benefício fiscal
exigida pela legislação estadual. Garanta que seu ERP trate esse campo na emissão do documento fiscal.
Retry em erros de servidor
Implemente backoff exponencial para erros 5xx (ex: aguarde 1min, 2min, 4min).
Para erros 400, corrija o payload — não faça retry imediato com os mesmos dados.
Segurança do token
Armazene o token em variáveis de ambiente ou em um cofre de segredos (ex: AWS Secrets Manager, Vault, .env não versionado). Nunca inclua o token em logs, código-fonte versionado ou respostas de API.
Suporte Técnico
Para dúvidas técnicas, geração ou renovação de token, entre em contato com a equipe OrionTax. Atendimento em dias úteis.