IBPTs · API Hooked

Visão Geral

O módulo IBPTs gerencia a tabela de alíquotas do IBPT (Instituto Brasileiro de Planejamento e Tributação), utilizada para calcular a carga tributária aproximada exibida nas notas fiscais conforme exigência da Lei 12.741/2012. Permite cadastro manual, consulta e importação em massa da tabela oficial.

Base URL

/api/ibpts

Todos os endpoints requerem autenticação via Bearer Token:
Authorization: Bearer {token}

Endpoints

GET /api/ibpts

Descrição: Retorna uma lista paginada de alíquotas IBPT cadastradas, com filtro por código NCM e descrição.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`codigo`	string	query	—	Filtra pelo código NCM
`descricao`	string	query	—	Filtra pela descrição do produto
`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": 50,
    "pageSize": 20,
    "totalCount": 1000,
    "hasPrevious": false,
    "hasNext": true
  },
  "data": [
    {
      "id": 1,
      "codigo": "01012100",
      "ex": null,
      "tipo": "0",
      "descricao": "Animais vivos",
      "nacionalFederal": 0.0,
      "importadosFederal": 0.0,
      "estadual": 0.0,
      "municipal": 0.0,
      "vigenciaInicio": "01/01/2024",
      "vigenciaFim": "31/12/2024",
      "chave": "abc123",
      "versao": "24.1.A",
      "fonte": "IBPT"
    }
  ],
  "summary": null
}

Campos da Resposta — `data[]`

Campo	Tipo	Descrição
`id`	integer (int64)	Identificador do registro IBPT
`codigo`	string	Código NCM ou NBS
`ex`	string	Exceção da tabela NCM
`tipo`	string	`0` = NCM, `1` = NBS, `2` = LC116
`descricao`	string	Descrição do produto/serviço
`nacionalFederal`	number	Alíquota federal para produtos nacionais (%)
`importadosFederal`	number	Alíquota federal para produtos importados (%)
`estadual`	number	Alíquota estadual (%)
`municipal`	number	Alíquota municipal (%)
`vigenciaInicio`	string	Início da vigência da alíquota
`vigenciaFim`	string	Fim da vigência da alíquota
`versao`	string	Versão da tabela IBPT
`fonte`	string	Fonte dos dados

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/ibpts" \
  -H "Authorization: Bearer {token}"

JavaScript

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

Python

import requests

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

import (
    "io"
    "net/http"
)

req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/ibpts", 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/ibpts');
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/ibpts",
  "nodes": [
    {
      "parameters": {
        "method": "GET",
        "url": "https://api.app.hooked.com.br/api/ibpts",
        "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/ibpts

Descrição: Cadastra manualmente uma alíquota IBPT.

Corpo da Requisição

{
  "codigo": "84713012",
  "ex": null,
  "tipo": "0",
  "descricao": "Computadores portáteis",
  "nacionalFederal": 9.25,
  "importadosFederal": 23.70,
  "estadual": 12.0,
  "municipal": 0.0,
  "vigenciaInicio": "01/01/2024",
  "vigenciaFim": "31/12/2024",
  "chave": "abc456",
  "versao": "24.1.A",
  "fonte": "IBPT"
}

Resposta de Sucesso `200`

Retorna o registro IBPT criado.

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/ibpts" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"codigo":"84713012","ex":null,"tipo":"0","descricao":"Computadores portáteis","nacionalFederal":9.25,"importadosFederal":23.7,"estadual":12.0,"municipal":0.0,"vigenciaInicio":"01/01/2024","vigenciaFim":"31/12/2024","chave":"abc456","versao":"24.1.A","fonte":"IBPT"}'

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/ibpts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "codigo": "84713012",
  "ex": null,
  "tipo": "0",
  "descricao": "Computadores portáteis",
  "nacionalFederal": 9.25,
  "importadosFederal": 23.7,
  "estadual": 12.0,
  "municipal": 0.0,
  "vigenciaInicio": "01/01/2024",
  "vigenciaFim": "31/12/2024",
  "chave": "abc456",
  "versao": "24.1.A",
  "fonte": "IBPT"
})
});
const data = await response.json();

Python

import requests

data = requests.post(
    'https://api.app.hooked.com.br/api/ibpts',
    headers={'Authorization': 'Bearer {token}'},
    json={'codigo': '84713012', 'ex': None, 'tipo': '0', 'descricao': 'Computadores portáteis', 'nacionalFederal': 9.25, 'importadosFederal': 23.7, 'estadual': 12.0, 'municipal': 0.0, 'vigenciaInicio': '01/01/2024', 'vigenciaFim': '31/12/2024', 'chave': 'abc456', 'versao': '24.1.A', 'fonte': 'IBPT'}
).json()

import (
    "bytes"
    "net/http"
)

payload := []byte(`{"codigo":"84713012","ex":null,"tipo":"0","descricao":"Computadores portáteis","nacionalFederal":9.25,"importadosFederal":23.7,"estadual":12.0,"municipal":0.0,"vigenciaInicio":"01/01/2024","vigenciaFim":"31/12/2024","chave":"abc456","versao":"24.1.A","fonte":"IBPT"}`)
req, _ := http.NewRequest("POST", "https://api.app.hooked.com.br/api/ibpts", 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/ibpts');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'codigo' => '84713012',
        'ex' => null,
        'tipo' => '0',
        'descricao' => 'Computadores portáteis',
        'nacionalFederal' => 9.25,
        'importadosFederal' => 23.7,
        'estadual' => 12.0,
        'municipal' => 0.0,
        'vigenciaInicio' => '01/01/2024',
        'vigenciaFim' => '31/12/2024',
        'chave' => 'abc456',
        'versao' => '24.1.A',
        'fonte' => 'IBPT'
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — POST /api/ibpts",
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.app.hooked.com.br/api/ibpts",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer SEU_TOKEN_AQUI"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "specifyBody": "json",
        "jsonBody": "{\"codigo\":\"84713012\",\"ex\":null,\"tipo\":\"0\",\"descricao\":\"Computadores portáteis\",\"nacionalFederal\":9.25,\"importadosFederal\":23.7,\"estadual\":12.0,\"municipal\":0.0,\"vigenciaInicio\":\"01/01/2024\",\"vigenciaFim\":\"31/12/2024\",\"chave\":\"abc456\",\"versao\":\"24.1.A\",\"fonte\":\"IBPT\"}",
        "options": {}
      },
      "id": "node-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        250,
        300
      ]
    }
  ],
  "connections": {},
  "pinData": {}
}

GET /api/ibpts/{id}

Descrição: Retorna os dados de uma alíquota IBPT pelo ID.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`id`	integer (int64)	path	✓	ID do registro IBPT

Resposta de Sucesso `200`

Retorna o objeto no mesmo formato da listagem.

Códigos de Erro

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

Exemplos de Código

cURL

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

JavaScript

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

Python

import requests

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

import (
    "io"
    "net/http"
)

req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/ibpts/{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/ibpts/{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/ibpts/{id}",
  "nodes": [
    {
      "parameters": {
        "method": "GET",
        "url": "https://api.app.hooked.com.br/api/ibpts/{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/ibpts/{id}

Descrição: Atualiza os dados de uma alíquota IBPT existente.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`id`	integer (int64)	path	✓	ID do registro a atualizar

Corpo da Requisição

Mesmo formato do POST, com o campo id preenchido.

Resposta de Sucesso `200`

Retorna o registro atualizado.

Códigos de Erro

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

Exemplos de Código

cURL

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

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/ibpts/{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/ibpts/{id}',
    headers={'Authorization': 'Bearer {token}'}
).json()

import (
    "io"
    "net/http"
)

req, _ := http.NewRequest("PUT", "https://api.app.hooked.com.br/api/ibpts/{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/ibpts/{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/ibpts/{id}",
  "nodes": [
    {
      "parameters": {
        "method": "PUT",
        "url": "https://api.app.hooked.com.br/api/ibpts/{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/ibpts/{id}

Descrição: Remove uma alíquota IBPT pelo ID.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`id`	integer (int64)	path	✓	ID do registro a remover

Resposta de Sucesso `200`

Retorna o registro removido.

Códigos de Erro

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

Exemplos de Código

cURL

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

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/ibpts/{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/ibpts/{id}',
    headers={'Authorization': 'Bearer {token}'}
).json()

import (
    "io"
    "net/http"
)

req, _ := http.NewRequest("DELETE", "https://api.app.hooked.com.br/api/ibpts/{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/ibpts/{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/ibpts/{id}",
  "nodes": [
    {
      "parameters": {
        "method": "DELETE",
        "url": "https://api.app.hooked.com.br/api/ibpts/{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": {}
}

POST /api/ibpts/importar

Descrição: Importa em massa a tabela IBPT oficial, substituindo os registros existentes. Utilizado para atualização periódica das alíquotas conforme novas versões publicadas pelo IBPT.

Corpo da Requisição

Envio do arquivo CSV/TXT da tabela IBPT no formato oficial via multipart/form-data.

Resposta de Sucesso `200`

true

Retorna true se a importação foi concluída com sucesso.

Códigos de Erro

Código	Descrição
`400`	Arquivo inválido ou formato incorreto
`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/ibpts/importar" \
  -H "Authorization: Bearer {token}" \
  -F "[email protected]"

JavaScript

const form = new FormData();
form.append('files', arquivo, 'arquivo.pdf');

const response = await fetch('https://api.app.hooked.com.br/api/ibpts/importar', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer {token}' },
  body: form
});
const data = await response.json();

Python

import requests

with open('arquivo.pdf', 'rb') as f:
    data = requests.post(
        'https://api.app.hooked.com.br/api/ibpts/importar',
    headers={'Authorization': 'Bearer {token}'},
        files=[('files', f)]
    ).json()

import (
    "bytes"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
arquivo, _ := os.Open("arquivo.pdf")
part, _ := writer.CreateFormFile("files", "arquivo.pdf")
io.Copy(part, arquivo)
writer.Close()

req, _ := http.NewRequest("POST", "https://api.app.hooked.com.br/api/ibpts/importar", body)
req.Header.Set("Authorization", "Bearer {token}")
req.Header.Set("Content-Type", writer.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

PHP

$ch = curl_init('https://api.app.hooked.com.br/api/ibpts/importar');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}'],
    CURLOPT_POSTFIELDS     => ['files' => new CURLFile('arquivo.pdf')],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — POST /api/ibpts/importar",
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.app.hooked.com.br/api/ibpts/importar",
        "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

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

Corpo da Requisição

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`

Resposta de Sucesso `200`