SPEDs Fiscais

Visão Geral

O módulo SPEDs Fiscais gerencia a geração e controle dos arquivos do SPED Fiscal (Sistema Público de Escrituração Digital), obrigação fiscal eletrônica que substitui a escrituração dos livros fiscais em papel. Permite criar, gerar e baixar o arquivo EFD (Escrituração Fiscal Digital).

Endpoints

GET /api/speds-fiscais

Descrição: Lista todos os SPEDs Fiscais gerados com suporte a paginação e filtros. Autenticação: Obrigatória

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
pagina	integer	Não	Número da página (padrão: 1)
quantidade	integer	Não	Itens por página (padrão: 20)
empresaId	string	Não	Filtrar por empresa
competenciaInicio	string (date)	Não	Competência inicial (AAAA-MM)
competenciaFim	string (date)	Não	Competência final (AAAA-MM)
status	string	Não	Status: pendente, gerado, transmitido

Resposta de Sucesso

{
  "dados": [
    {
      "id": "uuid",
      "empresaId": "uuid",
      "empresaNome": "Empresa XYZ Ltda",
      "competencia": "2024-01",
      "status": "gerado",
      "dataGeracao": "2024-02-05T08:00:00Z",
      "nomeArquivo": "SPED_202401.txt"
    }
  ],
  "total": 12,
  "pagina": 1,
  "quantidade": 20
}

Códigos de Erro Comuns

Código	Descrição
401	Não autorizado
500	Erro interno do servidor

Exemplos de Código

cURL

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

JavaScript

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

Python

import requests

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

Go

import (
    "io"
    "net/http"
)

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

Descrição: Cria um novo registro de SPED Fiscal para uma competência específica. Autenticação: Obrigatória

Corpo da Requisição

{
  "empresaId": 1,
  "mes": 1,
  "ano": 2024,
  "finalidade": 0,
  "situacao": 0,
  "perfil": "A",
  "tipoAtividade": 0,
  "blocoK": false,
  "gerarC170Saida": false,
  "difalAjustes": false,
  "gerarH": false
}

Campo	Tipo	Obrigatório	Regras	Descrição
empresaId	integer (int64)	✓	—	ID da empresa
mes	integer (int32)	✓	1–12	Mês de competência
ano	integer (int32)	✓	ano com 4 dígitos	Ano de competência
finalidade	integer (int32)	✓	—	Finalidade do arquivo (0 = original, 1 = substituto, etc.)
situacao	integer (int32)	✓	—	Situação do registro
id	integer (int64)	—	—	ID gerado pelo servidor (no POST geralmente 0)
blocoK	boolean	—	—	Indica se gera o Bloco K
gerarC170Saida	boolean	—	—	Gera registros C170 de saída
difalAjustes	boolean	—	—	Aplica ajustes de DIFAL
gerarH	boolean	—	—	Gera Bloco H (inventário)
codigoAjusteDifal	string	—	—	Código de ajuste DIFAL
perfil	string	—	A, B ou C	Perfil de apresentação do SPED
tipoAtividade	integer (int32)	—	—	Tipo de atividade do contribuinte
registro002	string	—	—	Conteúdo do registro 0002
fileName	string	—	—	Nome do arquivo gerado
content	string	—	—	Conteúdo do arquivo gerado
mensagem	string	—	—	Mensagem de retorno
data	string (date-time)	—	ISO 8601	Data de geração/processamento

Resposta de Sucesso

{
  "id": 0,
  "empresaId": 1,
  "mes": 1,
  "ano": 2024,
  "finalidade": 0,
  "situacao": 0
}

Códigos de Erro Comuns

Código	Descrição
400	Dados inválidos
401	Não autorizado
409	SPED já existe para essa competência e empresa

Exemplos de Código

cURL

curl -X POST "https://api.app.hooked.com.br/api/speds-fiscais" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"empresaId":1,"mes":1,"ano":2024,"finalidade":0,"situacao":0,"perfil":"A"}'

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/speds-fiscais', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "empresaId": 1,
  "mes": 1,
  "ano": 2024,
  "finalidade": 0,
  "situacao": 0,
  "perfil": "A"
})
});
const data = await response.json();

Python

import requests

data = requests.post(
    'https://api.app.hooked.com.br/api/speds-fiscais',
    headers={'Authorization': 'Bearer {token}'},
    json={'empresaId': 1, 'mes': 1, 'ano': 2024, 'finalidade': 0, 'situacao': 0, 'perfil': 'A'}
).json()

Go

import (
    "bytes"
    "net/http"
)

payload := []byte(`{"empresaId":1,"mes":1,"ano":2024,"finalidade":0,"situacao":0,"perfil":"A"}`)
req, _ := http.NewRequest("POST", "https://api.app.hooked.com.br/api/speds-fiscais", 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/speds-fiscais');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'empresaId' => 1,
        'mes' => 1,
        'ano' => 2024,
        'finalidade' => 0,
        'situacao' => 0,
        'perfil' => 'A'
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — POST /api/speds-fiscais",
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.app.hooked.com.br/api/speds-fiscais",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer SEU_TOKEN_AQUI"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "specifyBody": "json",
        "jsonBody": "{\"empresaId\":1,\"mes\":1,\"ano\":2024,\"finalidade\":0,\"situacao\":0,\"perfil\":\"A\"}",
        "options": {}
      },
      "id": "node-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        250,
        300
      ]
    }
  ],
  "connections": {},
  "pinData": {}
}

---

GET /api/speds-fiscais/{id}

Descrição: Retorna os detalhes de um SPED Fiscal pelo seu identificador único. Autenticação: Obrigatória

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
id	string (uuid)	Sim	Identificador único do SPED Fiscal

Resposta de Sucesso

{
  "id": "uuid",
  "empresaId": "uuid",
  "empresaNome": "Empresa XYZ Ltda",
  "competencia": "2024-01",
  "perfil": "A",
  "finalidade": "0",
  "status": "gerado",
  "dataGeracao": "2024-02-05T08:00:00Z",
  "nomeArquivo": "SPED_202401.txt",
  "observacoes": "Escrituração referente a janeiro de 2024"
}

Códigos de Erro Comuns

Código	Descrição
401	Não autorizado
404	SPED Fiscal não encontrado

Exemplos de Código

cURL

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

JavaScript

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

Python

import requests

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

Go

import (
    "io"
    "net/http"
)

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

Descrição: Atualiza os dados de um SPED Fiscal existente. Autenticação: Obrigatória

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
id	string (uuid)	Sim	Identificador único do SPED Fiscal

Corpo da Requisição (Request Body)

{
  "observacoes": "Retificação - ajuste de alíquota"
}

Resposta de Sucesso

{
  "id": "uuid",
  "competencia": "2024-01",
  "observacoes": "Retificação - ajuste de alíquota"
}

Códigos de Erro Comuns

Código	Descrição
400	Dados inválidos
401	Não autorizado
404	SPED Fiscal não encontrado

Exemplos de Código

cURL

curl -X PUT "https://api.app.hooked.com.br/api/speds-fiscais/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"observacoes":"Retificação - ajuste de alíquota"}'

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/speds-fiscais/{id}', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "observacoes": "Retificação - ajuste de alíquota"
})
});
const data = await response.json();

Python

import requests

data = requests.put(
    'https://api.app.hooked.com.br/api/speds-fiscais/{id}',
    headers={'Authorization': 'Bearer {token}'},
    json={'observacoes': 'Retificação - ajuste de alíquota'}
).json()

Go

import (
    "bytes"
    "net/http"
)

payload := []byte(`{"observacoes":"Retificação - ajuste de alíquota"}`)
req, _ := http.NewRequest("PUT", "https://api.app.hooked.com.br/api/speds-fiscais/{id}", 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/speds-fiscais/{id}');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'observacoes' => 'Retificação - ajuste de alíquota'
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — PUT /api/speds-fiscais/{id}",
  "nodes": [
    {
      "parameters": {
        "method": "PUT",
        "url": "https://api.app.hooked.com.br/api/speds-fiscais/{id}",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer SEU_TOKEN_AQUI"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "specifyBody": "json",
        "jsonBody": "{\"observacoes\":\"Retificação - ajuste de alíquota\"}",
        "options": {}
      },
      "id": "node-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        250,
        300
      ]
    }
  ],
  "connections": {},
  "pinData": {}
}

---

DELETE /api/speds-fiscais/{id}

Descrição: Remove um SPED Fiscal do sistema pelo seu identificador. Autenticação: Obrigatória

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
id	string (uuid)	Sim	Identificador único do SPED Fiscal

Resposta de Sucesso

{
  "mensagem": "SPED Fiscal removido com sucesso"
}

Códigos de Erro Comuns

Código	Descrição
401	Não autorizado
404	SPED Fiscal não encontrado
409	SPED já transmitido não pode ser removido

Exemplos de Código

cURL

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

JavaScript

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

Go

import (
    "io"
    "net/http"
)

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

Descrição: Processa e gera o arquivo EFD do SPED Fiscal com base nos dados de escrituração do período. Autenticação: Obrigatória

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
id	string (uuid)	Sim	Identificador único do SPED Fiscal

Resposta de Sucesso

{
  "id": "uuid",
  "status": "gerado",
  "nomeArquivo": "SPED_202401.txt",
  "dataGeracao": "2024-02-05T08:00:00Z"
}

Códigos de Erro Comuns

Código	Descrição
401	Não autorizado
404	SPED Fiscal não encontrado
422	Dados insuficientes para geração

Exemplos de Código

cURL

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

JavaScript

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

Python

import requests

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

Go

import (
    "io"
    "net/http"
)

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

---

GET /api/speds-fiscais/{id}/recuperar-arquivo

Descrição: Faz o download do arquivo EFD gerado para o SPED Fiscal. Autenticação: Obrigatória

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
id	string (uuid)	Sim	Identificador único do SPED Fiscal

Resposta de Sucesso

Retorna o arquivo EFD em formato texto plano para download, com Content-Type text/plain.

Códigos de Erro Comuns

Código	Descrição
401	Não autorizado
404	Arquivo não encontrado ou SPED ainda não gerado

Exemplos de Código

cURL

curl -X GET "https://api.app.hooked.com.br/api/speds-fiscais/{id}/recuperar-arquivo" \
  -H "Authorization: Bearer {token}" \
  -o arquivo

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/speds-fiscais/{id}/recuperar-arquivo', {
  headers: { 'Authorization': 'Bearer {token}' }
});
const blob = await response.blob();
// Node.js: use response.buffer() e salve com fs.writeFile

Python

import requests

response = requests.get(
    'https://api.app.hooked.com.br/api/speds-fiscais/{id}/recuperar-arquivo',
    headers={'Authorization': 'Bearer {token}'},
)
with open('arquivo', 'wb') as f:
    f.write(response.content)

Go

import (
    "io"
    "net/http"
)

req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/speds-fiscais/{id}/recuperar-arquivo", nil)
req.Header.Set("Authorization", "Bearer {token}")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
arquivo, _ := os.Create("arquivo")
defer arquivo.Close()
io.Copy(arquivo, resp.Body)

PHP

$ch = curl_init('https://api.app.hooked.com.br/api/speds-fiscais/{id}/recuperar-arquivo');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}'],
    CURLOPT_RETURNTRANSFER => true,
]);
$arquivo = curl_exec($ch);
curl_close($ch);
file_put_contents('arquivo', $arquivo);

n8n

{
  "name": "Hooked API — GET /api/speds-fiscais/{id}/recuperar-arquivo",
  "nodes": [
    {
      "parameters": {
        "method": "GET",
        "url": "https://api.app.hooked.com.br/api/speds-fiscais/{id}/recuperar-arquivo",
        "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": {}
}