Naturezas de Operação

Visão Geral

O módulo Naturezas de Operação gerencia as operações fiscais do sistema, definindo os CFOPs aplicáveis a cada tipo de movimentação (venda, compra, devolução, transferência, etc.). Cada natureza de operação configura os CFOPs para saída e entrada nos âmbitos estadual, interestadual e exterior, além de controlar a movimentação de estoque e a geração de financeiro.

Base URL

/api/naturezas-operacao

Endpoints

GET /api/naturezas-operacao

Descrição: Retorna uma lista paginada de naturezas de operação cadastradas, com filtro por descrição e tipo.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`descricao`	string	query	—	Filtra por descrição
`tipo`	string	query	—	Filtra por tipo (`S` = Saída, `E` = Entrada)
`property`	string	query	—	Campo de ordenação
`orderBy`	string	query	—	Direção: `asc` ou `desc`
`pageNumber`	integer	query	—	Número da página (padrão: `1`)
`pageSize`	integer	query	—	Registros por página (padrão: `20`)

Resposta de Sucesso `200`

{
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "pageSize": 20,
    "totalCount": 5,
    "hasPrevious": false,
    "hasNext": false
  },
  "data": [
    {
      "id": 1,
      "descricao": "Venda de Mercadoria",
      "tipo": "S",
      "cfopSaidaEstadual": 5102,
      "cfopSaidaInterestadual": 6102,
      "cfopSaidaExterior": 7102,
      "cfopEntradaEstadual": null,
      "cfopEntradaInterestadual": null,
      "cfopEntradaExterior": null,
      "sobrescreverCfopProduto": false,
      "movimentarEstoque": true,
      "finalidade": 1,
      "tipoPlanoConta": "venda",
      "gerarFinanceiro": true,
      "tpNFDebito": null,
      "tpNFCredito": null
    }
  ],
  "summary": null
}

Campos da Resposta — `data[]`

Campo	Tipo	Descrição
`id`	integer (int64)	Identificador da natureza de operação
`descricao`	string	Nome da operação
`tipo`	string	`S` = Saída, `E` = Entrada
`cfopSaidaEstadual`	integer	CFOP para saída estadual
`cfopSaidaInterestadual`	integer	CFOP para saída interestadual
`cfopSaidaExterior`	integer	CFOP para saída exterior
`cfopEntradaEstadual`	integer	CFOP para entrada estadual
`cfopEntradaInterestadual`	integer	CFOP para entrada interestadual
`cfopEntradaExterior`	integer	CFOP para entrada exterior
`sobrescreverCfopProduto`	boolean	Substitui o CFOP definido no produto
`movimentarEstoque`	boolean	Indica se gera movimentação de estoque
`finalidade`	integer	Finalidade da NF-e (`1` = Normal, `2` = Complementar, etc.)
`tipoPlanoConta`	string	Tipo de operação no plano de contas. Ver Parâmetros Base
`gerarFinanceiro`	boolean	Indica se gera título financeiro

Códigos de Erro

Código	Descrição
`401`	Token ausente ou inválido
`500`	Erro interno do servidor

Exemplos de Código

cURL

curl -X GET "https://api.app.hooked.com.br/api/naturezas-operacao" \
  -H "Authorization: Bearer {token}"

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/naturezas-operacao', {
  headers: { 'Authorization': 'Bearer {token}' }
});
const data = await response.json();

Python

import requests

data = requests.get(
    'https://api.app.hooked.com.br/api/naturezas-operacao',
    headers={'Authorization': 'Bearer {token}'}
).json()

import (
    "io"
    "net/http"
)

req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/naturezas-operacao", nil)
req.Header.Set("Authorization", "Bearer {token}")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)

PHP

$ch = curl_init('https://api.app.hooked.com.br/api/naturezas-operacao');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}'],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — GET /api/naturezas-operacao",
  "nodes": [
    {
      "parameters": {
        "method": "GET",
        "url": "https://api.app.hooked.com.br/api/naturezas-operacao",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer SEU_TOKEN_AQUI"
            }
          ]
        },
        "options": {}
      },
      "id": "node-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        250,
        300
      ]
    }
  ],
  "connections": {},
  "pinData": {}
}

POST /api/naturezas-operacao

Descrição: Cadastra uma nova natureza de operação fiscal.

Corpo da Requisição

{
  "descricao": "Devolução de Compra",
  "tipo": "S",
  "cfopSaidaEstadual": 5201,
  "cfopSaidaInterestadual": 6201,
  "cfopSaidaExterior": null,
  "cfopEntradaEstadual": null,
  "cfopEntradaInterestadual": null,
  "cfopEntradaExterior": null,
  "sobrescreverCfopProduto": false,
  "movimentarEstoque": true,
  "finalidade": 1,
  "tipoPlanoConta": "venda",
  "gerarFinanceiro": false,
  "tpNFDebito": null,
  "tpNFCredito": null
}

Campo	Tipo	Obrigatório	Regras	Descrição
`descricao`	string	✓	mín. 1 caractere	Nome da operação
`tipo`	string	✓	mín. 1 caractere	`S` = Saída, `E` = Entrada
`finalidade`	integer (int32)	✓	—	Finalidade da NF-e (`1` = Normal, `2` = Complementar, etc.)
`tipoPlanoConta`	string	✓	mín. 1 caractere	Tipo de operação. Ver Parâmetros Base
`cfopSaidaEstadual`	integer (int32)	—	nullable	CFOP para saída estadual
`cfopSaidaInterestadual`	integer (int32)	—	nullable	CFOP para saída interestadual
`cfopSaidaExterior`	integer (int32)	—	nullable	CFOP para saída exterior
`cfopEntradaEstadual`	integer (int32)	—	nullable	CFOP para entrada estadual
`cfopEntradaInterestadual`	integer (int32)	—	nullable	CFOP para entrada interestadual
`cfopEntradaExterior`	integer (int32)	—	nullable	CFOP para entrada exterior
`sobrescreverCfopProduto`	boolean	—	nullable	Substitui o CFOP definido no produto
`movimentarEstoque`	boolean	—	nullable	Indica se gera movimentação de estoque
`gerarFinanceiro`	boolean	—	nullable	Indica se gera título financeiro
`tpNFDebito`	string	—	nullable	Tipo de NF para lançamento de débito
`tpNFCredito`	string	—	nullable	Tipo de NF para lançamento de crédito

Parâmetros Base

Campo	Valores conhecidos
`tipoPlanoConta`	string textual minúscula: `"venda"`, `"compra"`, `"servico"`, `"transferencia"`

Resposta de Sucesso `200`

Retorna a natureza de operação criada.

Códigos de Erro

Código	Descrição
`400`	Dados inválidos
`401`	Token ausente ou inválido
`500`	Erro interno do servidor

Exemplos de Código

cURL

curl -X POST "https://api.app.hooked.com.br/api/naturezas-operacao" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"descricao":"Devolução de Compra","tipo":"S","cfopSaidaEstadual":5201,"cfopSaidaInterestadual":6201,"cfopSaidaExterior":null,"cfopEntradaEstadual":null,"cfopEntradaInterestadual":null,"cfopEntradaExterior":null,"sobrescreverCfopProduto":false,"movimentarEstoque":true,"finalidade":1,"tipoPlanoConta":"D","gerarFinanceiro":false}'

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/naturezas-operacao', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "descricao": "Devolução de Compra",
  "tipo": "S",
  "cfopSaidaEstadual": 5201,
  "cfopSaidaInterestadual": 6201,
  "cfopSaidaExterior": null,
  "cfopEntradaEstadual": null,
  "cfopEntradaInterestadual": null,
  "cfopEntradaExterior": null,
  "sobrescreverCfopProduto": false,
  "movimentarEstoque": true,
  "finalidade": 1,
  "tipoPlanoConta": "D",
  "gerarFinanceiro": false
})
});
const data = await response.json();

Python

import requests

data = requests.post(
    'https://api.app.hooked.com.br/api/naturezas-operacao',
    headers={'Authorization': 'Bearer {token}'},
    json={'descricao': 'Devolução de Compra', 'tipo': 'S', 'cfopSaidaEstadual': 5201, 'cfopSaidaInterestadual': 6201, 'cfopSaidaExterior': None, 'cfopEntradaEstadual': None, 'cfopEntradaInterestadual': None, 'cfopEntradaExterior': None, 'sobrescreverCfopProduto': False, 'movimentarEstoque': True, 'finalidade': 1, 'tipoPlanoConta': 'D', 'gerarFinanceiro': False}
).json()

import (
    "bytes"
    "net/http"
)

payload := []byte(`{"descricao":"Devolução de Compra","tipo":"S","cfopSaidaEstadual":5201,"cfopSaidaInterestadual":6201,"cfopSaidaExterior":null,"cfopEntradaEstadual":null,"cfopEntradaInterestadual":null,"cfopEntradaExterior":null,"sobrescreverCfopProduto":false,"movimentarEstoque":true,"finalidade":1,"tipoPlanoConta":"D","gerarFinanceiro":false}`)
req, _ := http.NewRequest("POST", "https://api.app.hooked.com.br/api/naturezas-operacao", bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer {token}")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

PHP

$ch = curl_init('https://api.app.hooked.com.br/api/naturezas-operacao');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'descricao' => 'Devolução de Compra',
        'tipo' => 'S',
        'cfopSaidaEstadual' => 5201,
        'cfopSaidaInterestadual' => 6201,
        'cfopSaidaExterior' => null,
        'cfopEntradaEstadual' => null,
        'cfopEntradaInterestadual' => null,
        'cfopEntradaExterior' => null,
        'sobrescreverCfopProduto' => false,
        'movimentarEstoque' => true,
        'finalidade' => 1,
        'tipoPlanoConta' => 'D',
        'gerarFinanceiro' => false
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — POST /api/naturezas-operacao",
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.app.hooked.com.br/api/naturezas-operacao",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer SEU_TOKEN_AQUI"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "specifyBody": "json",
        "jsonBody": "{\"descricao\":\"Devolução de Compra\",\"tipo\":\"S\",\"cfopSaidaEstadual\":5201,\"cfopSaidaInterestadual\":6201,\"cfopSaidaExterior\":null,\"cfopEntradaEstadual\":null,\"cfopEntradaInterestadual\":null,\"cfopEntradaExterior\":null,\"sobrescreverCfopProduto\":false,\"movimentarEstoque\":true,\"finalidade\":1,\"tipoPlanoConta\":\"D\",\"gerarFinanceiro\":false}",
        "options": {}
      },
      "id": "node-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        250,
        300
      ]
    }
  ],
  "connections": {},
  "pinData": {}
}

GET /api/naturezas-operacao/{id}

Descrição: Retorna os dados de uma natureza de operação pelo ID.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`id`	integer (int64)	path	✓	ID da natureza de operação

Resposta de Sucesso `200`

Retorna o objeto completo conforme formato da listagem.

Códigos de Erro

Código	Descrição
`401`	Token ausente ou inválido
`404`	Natureza de operação não encontrada
`500`	Erro interno do servidor

Exemplos de Código

cURL

curl -X GET "https://api.app.hooked.com.br/api/naturezas-operacao/{id}" \
  -H "Authorization: Bearer {token}"

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/naturezas-operacao/{id}', {
  headers: { 'Authorization': 'Bearer {token}' }
});
const data = await response.json();

Python

import requests

data = requests.get(
    'https://api.app.hooked.com.br/api/naturezas-operacao/{id}',
    headers={'Authorization': 'Bearer {token}'}
).json()

import (
    "io"
    "net/http"
)

req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/naturezas-operacao/{id}", nil)
req.Header.Set("Authorization", "Bearer {token}")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)

PHP

$ch = curl_init('https://api.app.hooked.com.br/api/naturezas-operacao/{id}');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}'],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — GET /api/naturezas-operacao/{id}",
  "nodes": [
    {
      "parameters": {
        "method": "GET",
        "url": "https://api.app.hooked.com.br/api/naturezas-operacao/{id}",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer SEU_TOKEN_AQUI"
            }
          ]
        },
        "options": {}
      },
      "id": "node-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        250,
        300
      ]
    }
  ],
  "connections": {},
  "pinData": {}
}

PUT /api/naturezas-operacao/{id}

Descrição: Atualiza os dados de uma natureza de operação existente.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`id`	integer (int64)	path	✓	ID da natureza de operação a atualizar

Corpo da Requisição

Mesmo formato do POST, com o campo id preenchido.

Resposta de Sucesso `200`

Retorna a natureza de operação atualizada.

Códigos de Erro

Código	Descrição
`400`	Dados inválidos
`401`	Token ausente ou inválido
`404`	Natureza de operação não encontrada
`500`	Erro interno do servidor

Exemplos de Código

cURL

curl -X PUT "https://api.app.hooked.com.br/api/naturezas-operacao/{id}" \
  -H "Authorization: Bearer {token}"

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/naturezas-operacao/{id}', {
  method: 'PUT',
  headers: { 'Authorization': 'Bearer {token}' }
});
const data = await response.json();

Python

import requests

data = requests.put(
    'https://api.app.hooked.com.br/api/naturezas-operacao/{id}',
    headers={'Authorization': 'Bearer {token}'}
).json()

import (
    "io"
    "net/http"
)

req, _ := http.NewRequest("PUT", "https://api.app.hooked.com.br/api/naturezas-operacao/{id}", nil)
req.Header.Set("Authorization", "Bearer {token}")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)

PHP

$ch = curl_init('https://api.app.hooked.com.br/api/naturezas-operacao/{id}');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}'],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — PUT /api/naturezas-operacao/{id}",
  "nodes": [
    {
      "parameters": {
        "method": "PUT",
        "url": "https://api.app.hooked.com.br/api/naturezas-operacao/{id}",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer SEU_TOKEN_AQUI"
            }
          ]
        },
        "options": {}
      },
      "id": "node-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        250,
        300
      ]
    }
  ],
  "connections": {},
  "pinData": {}
}

DELETE /api/naturezas-operacao/{id}

Descrição: Remove uma natureza de operação pelo ID.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`id`	integer (int64)	path	✓	ID da natureza de operação a remover

Resposta de Sucesso `200`

Retorna a natureza de operação removida.

Códigos de Erro

Código	Descrição
`401`	Token ausente ou inválido
`404`	Natureza de operação não encontrada
`500`	Erro interno do servidor

Exemplos de Código

cURL

curl -X DELETE "https://api.app.hooked.com.br/api/naturezas-operacao/{id}" \
  -H "Authorization: Bearer {token}"

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/naturezas-operacao/{id}', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer {token}' }
});
const data = await response.json();

Python

import requests

data = requests.delete(
    'https://api.app.hooked.com.br/api/naturezas-operacao/{id}',
    headers={'Authorization': 'Bearer {token}'}
).json()

import (
    "io"
    "net/http"
)

req, _ := http.NewRequest("DELETE", "https://api.app.hooked.com.br/api/naturezas-operacao/{id}", nil)
req.Header.Set("Authorization", "Bearer {token}")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)

PHP

$ch = curl_init('https://api.app.hooked.com.br/api/naturezas-operacao/{id}');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}'],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — DELETE /api/naturezas-operacao/{id}",
  "nodes": [
    {
      "parameters": {
        "method": "DELETE",
        "url": "https://api.app.hooked.com.br/api/naturezas-operacao/{id}",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer SEU_TOKEN_AQUI"
            }
          ]
        },
        "options": {}
      },
      "id": "node-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        250,
        300
      ]
    }
  ],
  "connections": {},
  "pinData": {}
}

Visão Geral

Base URL

Endpoints

Parâmetros

Resposta de Sucesso 200

Campos da Resposta — data[]

Códigos de Erro

Exemplos de Código

Corpo da Requisição

Parâmetros Base

Resposta de Sucesso 200

Códigos de Erro

Exemplos de Código

Parâmetros

Resposta de Sucesso 200

Códigos de Erro

Exemplos de Código

Parâmetros

Corpo da Requisição

Resposta de Sucesso 200

Códigos de Erro

Exemplos de Código

Parâmetros

Resposta de Sucesso 200

Códigos de Erro

Exemplos de Código

Resposta de Sucesso `200`

Campos da Resposta — `data[]`

Resposta de Sucesso `200`

Resposta de Sucesso `200`

Resposta de Sucesso `200`

Resposta de Sucesso `200`