API atual/Referência completa/Fiscal (NF-e e NFC-e)

Matriz de CFOP

Lê e ajusta a tabela que escolhe o CFOP de cada operação pelo tipo de venda, destinatário e UFs de origem e destino.

O CFOP (Código Fiscal de Operações e Prestações) é o número de 4 dígitos que a nota leva para dizer a natureza da operação: 5102 é venda dentro do estado, 6102 é venda para outro estado, 5405 é venda com substituição tributária, 1202 é devolução. A matriz de CFOP é a tabela que a plataforma consulta para escolher o código certo em cada nota.

Cada célula é identificada por cinco campos e guarda um CFOP:

Campo	Valores	Significado
`operation_type`	`sale`, `sale_st`, `return`	Venda comum, venda com substituição tributária, devolução.
`scope`	`intra`, `inter`	`intra` quando a UF do emissor é igual à do destinatário, `inter` quando são diferentes.
`recipient`	`final_consumer`, `reseller`	Consumidor final ou revendedor (contribuinte).
`origin_uf`	UF ou `*`	UF do emissor, em maiúsculas. `*` vale para qualquer UF.
`dest_uf`	UF ou `*`	UF do destinatário, em maiúsculas. `*` vale para qualquer UF.

Na hora de emitir, a plataforma procura a célula do par exato de UFs. Se não achar, usa a célula */* do mesmo tipo, escopo e destinatário. Se também não houver, cai nos padrões 5102 (dentro do estado) e 6102 (entre estados). A loja nasce com 12 células */* (as combinações de tipo, escopo e destinatário), então você só acrescenta exceções, como um CFOP especial de SP para MG.

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

Ler a matriz

GET/api/v1/admin/fiscal/cfop-matrixAdmin

Lê a matriz de CFOP

Exemplo de requisição

bash

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

Resposta

200Matriz devolvida

json

{
  "cells": [
    {
      "id": "3dbcb3ca-852a-413b-8fb0-d334870e8672",
      "operation_type": "return",
      "scope": "inter",
      "recipient": "final_consumer",
      "origin_uf": "*",
      "dest_uf": "*",
      "cfop": "2202"
    },
    {
      "id": "1388918f-0c01-4fb4-a3a2-12466fc6a70a",
      "operation_type": "sale",
      "scope": "inter",
      "recipient": "final_consumer",
      "origin_uf": "*",
      "dest_uf": "*",
      "cfop": "6102"
    }
  ]
}

Campos da resposta

cellsarray

Células da matriz, ordenadas por tipo, escopo, destinatário e UFs. A lista real tem as 12 células padrão mais as suas exceções; o exemplo mostra duas.

iduuid

Id da célula.

operation_typestring

salesale_streturn

Tipo de operação.

scopestring

intrainter

Dentro ou entre estados.

recipientstring

final_consumerreseller

Tipo de destinatário.

origin_ufstring

UF do emissor ou *.

dest_ufstring

UF do destinatário ou *.

cfopstring

CFOP aplicado.

Erros

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

Gravar células

Cria ou atualiza as células enviadas. A célula é localizada pela combinação dos cinco campos de identificação: se existir, o CFOP é trocado; se não, ela é criada. A resposta é a matriz inteira já atualizada, no mesmo formato do GET.

PUT/api/v1/admin/fiscal/cfop-matrixAdmin

Grava células da matriz de CFOP

Corpo da requisição

cellsarrayobrigatório

Células a gravar. Só envie as que mudam.

operation_typestringobrigatório

salesale_streturn

Tipo de operação.

scopestringobrigatório

intrainter

Dentro ou entre estados.

recipientstringobrigatório

final_consumerreseller

Tipo de destinatário.

origin_ufstringpadrão: *

UF do emissor, em maiúsculas. Vazio vira *.

dest_ufstringpadrão: *

UF do destinatário, em maiúsculas. Vazio vira *.

cfopstringobrigatório

CFOP de 4 dígitos. O formato não é validado.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/fiscal/cfop-matrix" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cells": [
      {
        "operation_type": "sale",
        "scope": "inter",
        "recipient": "reseller",
        "origin_uf": "SP",
        "dest_uf": "MG",
        "cfop": "6102"
      }
    ]
  }'

Resposta

200Matriz atualizada

json

{
  "cells": [
    {
      "id": "6a2f9c41-0b7d-4e83-a5c6-3d1e8f0b7a92",
      "operation_type": "sale",
      "scope": "inter",
      "recipient": "reseller",
      "origin_uf": "SP",
      "dest_uf": "MG",
      "cfop": "6102"
    }
  ]
}

O exemplo mostra só a célula gravada; a resposta real traz a matriz completa.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid body","detail":"..."}`
422	Tipo, escopo ou destinatário fora das listas	`{"error":"failed to upsert cell","detail":"..."}`

Veja também

API atual/Referência completa/Fiscal (NF-e e NFC-e)

Matriz de CFOP

Lê e ajusta a tabela que escolhe o CFOP de cada operação pelo tipo de venda, destinatário e UFs de origem e destino.

Cada célula é identificada por cinco campos e guarda um CFOP:

Campo	Valores	Significado
`operation_type`	`sale`, `sale_st`, `return`	Venda comum, venda com substituição tributária, devolução.
`scope`	`intra`, `inter`	`intra` quando a UF do emissor é igual à do destinatário, `inter` quando são diferentes.
`recipient`	`final_consumer`, `reseller`	Consumidor final ou revendedor (contribuinte).
`origin_uf`	UF ou `*`	UF do emissor, em maiúsculas. `*` vale para qualquer UF.
`dest_uf`	UF ou `*`	UF do destinatário, em maiúsculas. `*` vale para qualquer UF.

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

Ler a matriz

GET/api/v1/admin/fiscal/cfop-matrixAdmin

Lê a matriz de CFOP

Exemplo de requisição

bash

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

Resposta

200Matriz devolvida

json

{
  "cells": [
    {
      "id": "3dbcb3ca-852a-413b-8fb0-d334870e8672",
      "operation_type": "return",
      "scope": "inter",
      "recipient": "final_consumer",
      "origin_uf": "*",
      "dest_uf": "*",
      "cfop": "2202"
    },
    {
      "id": "1388918f-0c01-4fb4-a3a2-12466fc6a70a",
      "operation_type": "sale",
      "scope": "inter",
      "recipient": "final_consumer",
      "origin_uf": "*",
      "dest_uf": "*",
      "cfop": "6102"
    }
  ]
}

Campos da resposta

cellsarray

Células da matriz, ordenadas por tipo, escopo, destinatário e UFs. A lista real tem as 12 células padrão mais as suas exceções; o exemplo mostra duas.

iduuid

Id da célula.

operation_typestring

salesale_streturn

Tipo de operação.

scopestring

intrainter

Dentro ou entre estados.

recipientstring

final_consumerreseller

Tipo de destinatário.

origin_ufstring

UF do emissor ou *.

dest_ufstring

UF do destinatário ou *.

cfopstring

CFOP aplicado.

Erros

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

Gravar células

PUT/api/v1/admin/fiscal/cfop-matrixAdmin

Grava células da matriz de CFOP

Corpo da requisição

cellsarrayobrigatório

Células a gravar. Só envie as que mudam.

operation_typestringobrigatório

salesale_streturn

Tipo de operação.

scopestringobrigatório

intrainter

Dentro ou entre estados.

recipientstringobrigatório

final_consumerreseller

Tipo de destinatário.

origin_ufstringpadrão: *

UF do emissor, em maiúsculas. Vazio vira *.

dest_ufstringpadrão: *

UF do destinatário, em maiúsculas. Vazio vira *.

cfopstringobrigatório

CFOP de 4 dígitos. O formato não é validado.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/fiscal/cfop-matrix" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cells": [
      {
        "operation_type": "sale",
        "scope": "inter",
        "recipient": "reseller",
        "origin_uf": "SP",
        "dest_uf": "MG",
        "cfop": "6102"
      }
    ]
  }'

Resposta

200Matriz atualizada

json

{
  "cells": [
    {
      "id": "6a2f9c41-0b7d-4e83-a5c6-3d1e8f0b7a92",
      "operation_type": "sale",
      "scope": "inter",
      "recipient": "reseller",
      "origin_uf": "SP",
      "dest_uf": "MG",
      "cfop": "6102"
    }
  ]
}

O exemplo mostra só a célula gravada; a resposta real traz a matriz completa.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid body","detail":"..."}`
422	Tipo, escopo ou destinatário fora das listas	`{"error":"failed to upsert cell","detail":"..."}`