VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Fiscal (NF-e e NFC-e)

Perfis fiscais

Cria e mantém os perfis que definem CST, CSOSN, origem e substituição tributária dos produtos nas notas.

Um perfil fiscal é um conjunto de códigos de imposto que a nota usa para um tipo de produto. Em vez de repetir CST e CSOSN em cada produto, você cria alguns perfis ("revenda com ST", "Simples Nacional sem ST") e os atribui a produtos, categorias ou prefixos de NCM. Um perfil marcado como padrão vale para tudo que não tiver atribuição.

Exigem o módulo focusnfe e o privilégio manage_taxes ou manage_settings.

CódigoPara que serve
csosnCódigo de situação da operação no Simples Nacional (por exemplo 102, 400). Usado por emissores do Simples.
icms_cstCódigo de situação tributária do ICMS no regime normal (por exemplo 00, 60).
pis_cst, cofins_cstCódigo de situação tributária do PIS e da COFINS.
icms_origemOrigem da mercadoria, de 0 (nacional) a 8, conforme a tabela da SEFAZ.
st_enabled, st_retido, st_mva_bpsSubstituição tributária (ICMS ST): se aplica, se o imposto já veio retido e a margem de valor agregado em pontos-base (4000 = 40%).

Quando st_enabled está ligado, o produto precisa ter CEST, ou a validação prévia acusa MISSING_CEST como erro.

Listar perfis

Devolve os perfis não excluídos, do menor priority para o maior e, em empate, por nome.

GET/api/v1/admin/fiscal/profilesAdmin

Lista os perfis fiscais

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/fiscal/profiles" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Perfis devolvidos
json
{
  "items": [
    {
      "id": "be441f7e-9c43-4602-a43c-4724a5d8ce04",
      "name": "Revenda com ST",
      "is_default": false,
      "csosn": "500",
      "icms_cst": "60",
      "pis_cst": "01",
      "cofins_cst": "01",
      "icms_origem": 0,
      "st_enabled": true,
      "st_retido": true,
      "st_mva_bps": 4000,
      "priority": 100,
      "status": "active",
      "created_at": "2026-07-19T08:47:37Z",
      "updated_at": "2026-07-19T08:47:37Z"
    }
  ]
}

Campos da resposta

iduuid
Id do perfil.
namestring
Nome para exibição.
is_defaultboolean
Se é o perfil usado quando nenhuma atribuição casa.
csosnstring
CSOSN.
icms_cststring
CST do ICMS.
pis_cststring
CST do PIS. Pode ser vazio.
cofins_cststring
CST da COFINS. Pode ser vazio.
icms_origeminteger
Origem da mercadoria.
st_enabledboolean
Substituição tributária ligada.
st_retidoboolean
ICMS ST já retido anteriormente na cadeia.
st_mva_bpsinteger
Margem de valor agregado em pontos-base.
priorityinteger
Quanto menor, mais precedência quando mais de um perfil casa.
statusstring
activeinactive
Situação. Só perfis active são usados na emissão.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo
500Falha de consulta{"error":"failed to list profiles","detail":"..."}
401 / 403Sem token, sem privilégio, módulo desligado{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}

Criar um perfil

Cria o perfil. A API não valida o conteúdo dos códigos: confirme CST e CSOSN com o seu contador antes de usar.

POST/api/v1/admin/fiscal/profilesAdmin

Cria um perfil fiscal

Corpo da requisição

namestringobrigatório
Nome do perfil.
is_defaultbooleanpadrão: false
Marca como padrão. Só pode existir um perfil padrão: marcar um segundo falha com 422 enquanto o primeiro existir. Não há rota para trocar o padrão; exclua o atual e crie o novo.
csosnstringpadrão: 102
CSOSN.
icms_cststringpadrão: 00
CST do ICMS.
pis_cststring
CST do PIS.
cofins_cststring
CST da COFINS.
icms_origemintegerpadrão: 0
Origem da mercadoria (0 a 8).
st_enabledbooleanpadrão: false
Substituição tributária.
st_retidobooleanpadrão: false
ST retida.
st_mva_bpsintegerpadrão: 0
MVA em pontos-base.
priorityintegerpadrão: 100
Precedência; menor vence.
statusstringpadrão: active
activeinactive
Situação inicial.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/fiscal/profiles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenda com ST",
    "csosn": "500",
    "icms_cst": "60",
    "pis_cst": "01",
    "cofins_cst": "01",
    "icms_origem": 0,
    "st_enabled": true,
    "st_retido": true,
    "st_mva_bps": 4000
  }'

Resposta

201Perfil criado
json
{
  "id": "be441f7e-9c43-4602-a43c-4724a5d8ce04",
  "name": "Revenda com ST",
  "is_default": false,
  "csosn": "500",
  "icms_cst": "60",
  "pis_cst": "01",
  "cofins_cst": "01",
  "icms_origem": 0,
  "st_enabled": true,
  "st_retido": true,
  "st_mva_bps": 4000,
  "priority": 100,
  "status": "",
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z"
}
A resposta de criação vem incompleta

O corpo devolvido é o que você enviou, mais o id e os padrões de csosn, icms_cst e priority. status e as datas aparecem vazios ("" e 0001-01-01...) mesmo que o perfil seja gravado como active. Para ver o registro real, use a listagem.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid body","detail":"..."}
422Falha ao gravar (por exemplo status fora da lista, ou já existe um perfil padrão){"error":"failed to create profile","detail":"..."}

Alterar um perfil

O PUT regrava todos os códigos

Só o name é preservado quando vazio. csosn, icms_cst, pis_cst, cofins_cst, icms_origem, st_enabled, st_retido, st_mva_bps e priority são regravados com o que vier: omitir csosn apaga o CSOSN e omitir priority grava 0. O PUT não altera is_default nem status. Leia o perfil, mude o que precisa e reenvie tudo.

PUT/api/v1/admin/fiscal/profiles/{id}Admin

Altera um perfil fiscal

Parâmetros de caminho

iduuidobrigatório
Id do perfil.

Corpo da requisição

namestring
Novo nome. Vazio mantém o atual.
csosnstring
CSOSN.
icms_cststring
CST do ICMS.
pis_cststring
CST do PIS.
cofins_cststring
CST da COFINS.
icms_origeminteger
Origem da mercadoria.
st_enabledboolean
Substituição tributária.
st_retidoboolean
ST retida.
st_mva_bpsinteger
MVA em pontos-base.
priorityinteger
Precedência; menor vence.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/fiscal/profiles/be441f7e-9c43-4602-a43c-4724a5d8ce04" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenda com ST",
    "csosn": "500",
    "icms_cst": "60",
    "pis_cst": "01",
    "cofins_cst": "01",
    "icms_origem": 0,
    "st_enabled": true,
    "st_retido": true,
    "st_mva_bps": 3500,
    "priority": 100
  }'

Resposta

200Perfil atualizado
json
{
  "id": "be441f7e-9c43-4602-a43c-4724a5d8ce04",
  "name": "Revenda com ST",
  "is_default": false,
  "csosn": "500",
  "icms_cst": "60",
  "pis_cst": "01",
  "cofins_cst": "01",
  "icms_origem": 0,
  "st_enabled": true,
  "st_retido": true,
  "st_mva_bps": 3500,
  "priority": 100,
  "status": "active",
  "created_at": "2026-07-19T08:47:37Z",
  "updated_at": "2026-10-11T22:40:00Z"
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid body","detail":"..."}
422Perfil inexistente, id que não é UUID{"error":"failed to update profile","detail":"..."}

Um perfil excluído não é alterado, mas a chamada ainda responde 200 com o registro guardado (inativo); confira o status na resposta.

Excluir um perfil

Exclusão lógica: o perfil fica inactive e deixa de ser usado. Atribuições a ele continuam gravadas mas não têm efeito.

DELETE/api/v1/admin/fiscal/profiles/{id}Admin

Exclui um perfil fiscal

Parâmetros de caminho

iduuidobrigatório
Id do perfil.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/fiscal/profiles/be441f7e-9c43-4602-a43c-4724a5d8ce04" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Perfil excluído
text
(sem corpo)

Erros

StatusQuandoCorpo
500Falha ao gravar, ou id que não é UUID{"error":"failed to delete profile","detail":"..."}
Excluir o perfil padrão deixa a loja sem padrão

A API não impede excluir o perfil marcado como padrão nem avisa se algum produto ainda dependia dele. Itens sem perfil resolvido saem com os padrões (5102/6102, CSOSN 400) e a validação prévia mostra o aviso NO_PROFILE.

Veja também

  • Atribuições de perfil
  • Matriz de CFOP
  • Validação prévia
Anterior
Provisionamento no provedor
Próxima
Atribuições de perfil fiscal
Nesta página
  • Listar perfis
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar um perfil
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar um perfil
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir um perfil
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também