Pessoas
Visão Geral
O módulo Pessoas gerencia o cadastro de pessoas físicas e jurídicas no sistema, incluindo clientes, fornecedores, transportadoras e outros contatos. Permite criar, consultar, atualizar e remover registros, além de gerar relatórios e consultar por CNPJ/CPF.
Endpoints
Descrição: Lista todas as pessoas cadastradas 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) |
| nome | string | Não | Filtrar por nome ou razão social |
| cnpjCpf | string | Não | Filtrar por CNPJ ou CPF |
| tipo | string | Não | Tipo: cliente, fornecedor, transportadora |
| ativo | boolean | Não | Filtrar por status ativo/inativo |
Resposta de Sucesso
{
"dados": [
{
"id": "uuid",
"nome": "João da Silva",
"nomeFantasia": "JS Comércio",
"cnpjCpf": "123.456.789-00",
"tipo": "cliente",
"email": "[email protected]",
"telefone": "(11) 99999-9999",
"ativo": true
}
],
"total": 100,
"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/pessoas?pagina=1&quantidade=20&tipo=cliente" \
-H "Authorization: Bearer {token}"
JavaScript
const response = await fetch('https://api.app.hooked.com.br/api/pessoas?pagina=1&quantidade=20&tipo=cliente', {
headers: { 'Authorization': 'Bearer {token}' }
});
const data = await response.json();
Python
import requests
data = requests.get(
'https://api.app.hooked.com.br/api/pessoas',
headers={'Authorization': 'Bearer {token}'},
params={'pagina': 1, 'quantidade': 20, 'tipo': 'cliente'}
).json()
Go
import (
"io"
"net/http"
)
req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/pessoas?pagina=1&quantidade=20&tipo=cliente", 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/pessoas?pagina=1&quantidade=20&tipo=cliente');
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/pessoas",
"nodes": [
{
"parameters": {
"method": "GET",
"url": "https://api.app.hooked.com.br/api/pessoas",
"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": {}
}
Descrição: Cria uma nova pessoa (física ou jurídica) no sistema. Autenticação: Obrigatória
Corpo da Requisição (Request Body)
{
"nome": "Maria Oliveira",
"nomeFantasia": "MO Serviços",
"cnpjCpf": "987.654.321-00",
"tipo": "cliente",
"email": "[email protected]",
"telefone": "(11) 88888-8888",
"celular": "(11) 77777-7777",
"enderecoLogradouro": "Rua das Flores",
"enderecoNumero": "100",
"enderecoComplemento": "Apto 1",
"enderecoBairro": "Centro",
"enderecoCep": "01310-100",
"enderecoCidadeId": "uuid-cidade",
"ativo": true,
"observacoes": "Cliente VIP"
}
Resposta de Sucesso
{
"id": "uuid",
"nome": "Maria Oliveira",
"cnpjCpf": "987.654.321-00",
"tipo": "cliente",
"ativo": true
}
Códigos de Erro Comuns
| Código | Descrição |
|---|---|
| 400 | Dados inválidos |
| 401 | Não autorizado |
| 409 | CNPJ/CPF já cadastrado |
Exemplos de Código
cURL
curl -X POST "https://api.app.hooked.com.br/api/pessoas" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"nome":"Maria Oliveira","cnpjCpf":"987.654.321-00","tipo":"cliente","email":"[email protected]","ativo":true}'
JavaScript
const response = await fetch('https://api.app.hooked.com.br/api/pessoas', {
method: 'POST',
headers: {
'Authorization': 'Bearer {token}',
'Content-Type': 'application/json'
},
body: JSON.stringify({
nome: 'Maria Oliveira',
cnpjCpf: '987.654.321-00',
tipo: 'cliente',
email: '[email protected]',
ativo: true
})
});
const data = await response.json();
Python
import requests
data = requests.post(
'https://api.app.hooked.com.br/api/pessoas',
headers={'Authorization': 'Bearer {token}'},
json={'nome': 'Maria Oliveira', 'cnpjCpf': '987.654.321-00', 'tipo': 'cliente', 'email': '[email protected]', 'ativo': True}
).json()
Go
import (
"bytes"
"encoding/json"
"net/http"
)
payload, _ := json.Marshal(map[string]any{
"nome": "Maria Oliveira", "cnpjCpf": "987.654.321-00",
"tipo": "cliente", "email": "[email protected]", "ativo": true,
})
req, _ := http.NewRequest("POST", "https://api.app.hooked.com.br/api/pessoas", 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/pessoas');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer {token}', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['nome' => 'Maria Oliveira', 'cnpjCpf' => '987.654.321-00', 'tipo' => 'cliente', 'email' => '[email protected]', 'ativo' => true]),
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
n8n
{
"name": "Hooked API — POST /api/pessoas",
"nodes": [
{
"parameters": {
"method": "POST",
"url": "https://api.app.hooked.com.br/api/pessoas",
"sendHeaders": true,
"headerParameters": {
"parameters": [
{
"name": "Authorization",
"value": "Bearer SEU_TOKEN_AQUI"
}
]
},
"sendBody": true,
"contentType": "json",
"specifyBody": "json",
"jsonBody": "{\n \"nome\": \"Maria Oliveira\",\n \"cnpjCpf\": \"987.654.321-00\",\n \"tipo\": \"cliente\",\n \"email\": \"[email protected]\",\n \"ativo\": true\n}",
"options": {}
},
"id": "node-1",
"name": "HTTP Request",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.2,
"position": [
250,
300
]
}
],
"connections": {},
"pinData": {}
}
Descrição: Retorna os detalhes completos de uma pessoa 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 da pessoa |
Resposta de Sucesso
{
"id": "uuid",
"nome": "João da Silva",
"nomeFantasia": "JS Comércio",
"cnpjCpf": "123.456.789-00",
"tipo": "cliente",
"email": "[email protected]",
"telefone": "(11) 99999-9999",
"celular": "(11) 88888-8888",
"enderecoLogradouro": "Av. Paulista",
"enderecoNumero": "1000",
"enderecoBairro": "Bela Vista",
"enderecoCep": "01310-100",
"enderecoCidade": "São Paulo",
"enderecoEstado": "SP",
"ativo": true,
"observacoes": ""
}
Códigos de Erro Comuns
| Código | Descrição |
|---|---|
| 401 | Não autorizado |
| 404 | Pessoa não encontrada |
Exemplos de Código
cURL
curl -X GET "https://api.app.hooked.com.br/api/pessoas/{id}" \
-H "Authorization: Bearer {token}"
JavaScript
const response = await fetch('https://api.app.hooked.com.br/api/pessoas/{id}', {
headers: { 'Authorization': 'Bearer {token}' }
});
const data = await response.json();
Python
import requests
data = requests.get(
'https://api.app.hooked.com.br/api/pessoas/{id}',
headers={'Authorization': 'Bearer {token}'}
).json()
Go
import (
"io"
"net/http"
)
req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/pessoas/{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/pessoas/{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/pessoas/{{$json.id}}",
"nodes": [
{
"parameters": {
"method": "GET",
"url": "https://api.app.hooked.com.br/api/pessoas/{{$json.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": {}
}
Descrição: Atualiza os dados de uma pessoa existente. Autenticação: Obrigatória
Parâmetros de Path
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string (uuid) | Sim | Identificador único da pessoa |
Corpo da Requisição (Request Body)
{
"nome": "João da Silva Atualizado",
"email": "[email protected]",
"telefone": "(11) 99999-0000",
"ativo": true
}
Resposta de Sucesso
{
"id": "uuid",
"nome": "João da Silva Atualizado",
"email": "[email protected]",
"ativo": true
}
Códigos de Erro Comuns
| Código | Descrição |
|---|---|
| 400 | Dados inválidos |
| 401 | Não autorizado |
| 404 | Pessoa não encontrada |
Exemplos de Código
cURL
curl -X PUT "https://api.app.hooked.com.br/api/pessoas/{id}" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"nome":"João da Silva Atualizado","email":"[email protected]","ativo":true}'
JavaScript
const response = await fetch('https://api.app.hooked.com.br/api/pessoas/{id}', {
method: 'PUT',
headers: {
'Authorization': 'Bearer {token}',
'Content-Type': 'application/json'
},
body: JSON.stringify({ nome: 'João da Silva Atualizado', email: '[email protected]', ativo: true })
});
const data = await response.json();
Python
import requests
data = requests.put(
'https://api.app.hooked.com.br/api/pessoas/{id}',
headers={'Authorization': 'Bearer {token}'},
json={'nome': 'João da Silva Atualizado', 'email': '[email protected]', 'ativo': True}
).json()
Go
import (
"bytes"
"encoding/json"
"net/http"
)
payload, _ := json.Marshal(map[string]any{
"nome": "João da Silva Atualizado", "email": "[email protected]", "ativo": true,
})
req, _ := http.NewRequest("PUT", "https://api.app.hooked.com.br/api/pessoas/{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/pessoas/{id}');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => ['Authorization: Bearer {token}', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['nome' => 'João da Silva Atualizado', 'email' => '[email protected]', 'ativo' => true]),
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
n8n
{
"name": "Hooked API — PUT /api/pessoas/{{$json.id}}",
"nodes": [
{
"parameters": {
"method": "PUT",
"url": "https://api.app.hooked.com.br/api/pessoas/{{$json.id}}",
"sendHeaders": true,
"headerParameters": {
"parameters": [
{
"name": "Authorization",
"value": "Bearer SEU_TOKEN_AQUI"
}
]
},
"sendBody": true,
"contentType": "json",
"specifyBody": "json",
"jsonBody": "{\n \"nome\": \"João da Silva Atualizado\",\n \"email\": \"[email protected]\",\n \"ativo\": true\n}",
"options": {}
},
"id": "node-1",
"name": "HTTP Request",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.2,
"position": [
250,
300
]
}
],
"connections": {},
"pinData": {}
}
Descrição: Remove uma pessoa 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 da pessoa |
Resposta de Sucesso
{
"mensagem": "Pessoa removida com sucesso"
}
Códigos de Erro Comuns
| Código | Descrição |
|---|---|
| 401 | Não autorizado |
| 404 | Pessoa não encontrada |
| 409 | Pessoa vinculada a outros registros |
Exemplos de Código
cURL
curl -X DELETE "https://api.app.hooked.com.br/api/pessoas/{id}" \
-H "Authorization: Bearer {token}"
JavaScript
const response = await fetch('https://api.app.hooked.com.br/api/pessoas/{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/pessoas/{id}',
headers={'Authorization': 'Bearer {token}'}
).json()
Go
import "net/http"
req, _ := http.NewRequest("DELETE", "https://api.app.hooked.com.br/api/pessoas/{id}", nil)
req.Header.Set("Authorization", "Bearer {token}")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
PHP
$ch = curl_init('https://api.app.hooked.com.br/api/pessoas/{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/pessoas/{{$json.id}}",
"nodes": [
{
"parameters": {
"method": "DELETE",
"url": "https://api.app.hooked.com.br/api/pessoas/{{$json.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": {}
}
Descrição: Retorna a quantidade total de pessoas cadastradas, podendo aplicar filtros. Autenticação: Obrigatória
Parâmetros de Query
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tipo | string | Não | Tipo da pessoa para filtrar |
| ativo | boolean | Não | Filtrar por status |
Resposta de Sucesso
{
"quantidade": 500
}
Códigos de Erro Comuns
| Código | Descrição |
|---|---|
| 401 | Não autorizado |
Exemplos de Código
cURL
curl -X GET "https://api.app.hooked.com.br/api/pessoas/recuperar-quantidade?tipo=cliente" \
-H "Authorization: Bearer {token}"
JavaScript
const response = await fetch('https://api.app.hooked.com.br/api/pessoas/recuperar-quantidade?tipo=cliente', {
headers: { 'Authorization': 'Bearer {token}' }
});
const data = await response.json();
Python
import requests
data = requests.get(
'https://api.app.hooked.com.br/api/pessoas/recuperar-quantidade',
headers={'Authorization': 'Bearer {token}'},
params={'tipo': 'cliente'}
).json()
Go
import (
"io"
"net/http"
)
req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/pessoas/recuperar-quantidade?tipo=cliente", 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/pessoas/recuperar-quantidade?tipo=cliente');
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/pessoas/recuperar-quantidade",
"nodes": [
{
"parameters": {
"method": "GET",
"url": "https://api.app.hooked.com.br/api/pessoas/recuperar-quantidade",
"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": {}
}
Descrição: Gera um relatório de pessoas em formato para download (PDF ou Excel). Autenticação: Obrigatória
Parâmetros de Query
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tipo | string | Não | Tipo da pessoa para filtrar |
| formato | string | Não | Formato do relatório: pdf ou xlsx |
Resposta de Sucesso
Retorna o arquivo binário para download com o Content-Type adequado.
Códigos de Erro Comuns
| Código | Descrição |
|---|---|
| 401 | Não autorizado |
| 500 | Erro ao gerar relatório |
Exemplos de Código
cURL
curl -X GET "https://api.app.hooked.com.br/api/pessoas/gerar-relatorio?formato=pdf" \
-H "Authorization: Bearer {token}" \
-o relatorio-pessoas.pdf
JavaScript
const response = await fetch('https://api.app.hooked.com.br/api/pessoas/gerar-relatorio?formato=pdf', {
headers: { 'Authorization': 'Bearer {token}' }
});
const blob = await response.blob();
// No Node.js: use response.buffer() e salve com fs.writeFile
Python
import requests
response = requests.get(
'https://api.app.hooked.com.br/api/pessoas/gerar-relatorio',
headers={'Authorization': 'Bearer {token}'},
params={'formato': 'pdf'}
)
with open('relatorio-pessoas.pdf', 'wb') as f:
f.write(response.content)
Go
import (
"net/http"
"os"
)
req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/pessoas/gerar-relatorio?formato=pdf", nil)
req.Header.Set("Authorization", "Bearer {token}")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
arquivo, _ := os.Create("relatorio-pessoas.pdf")
defer arquivo.Close()
io.Copy(arquivo, resp.Body)
PHP
$ch = curl_init('https://api.app.hooked.com.br/api/pessoas/gerar-relatorio?formato=pdf');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer {token}'],
CURLOPT_RETURNTRANSFER => true,
]);
$arquivo = curl_exec($ch);
curl_close($ch);
file_put_contents('relatorio-pessoas.pdf', $arquivo);
n8n
{
"name": "Hooked API — GET /api/pessoas/gerar-relatorio?formato=pdf",
"nodes": [
{
"parameters": {
"method": "GET",
"url": "https://api.app.hooked.com.br/api/pessoas/gerar-relatorio?formato=pdf",
"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": {}
}
Descrição: Consulta uma pessoa pelo número de CNPJ, CPF ou Documento de Identidade (DI) para estrangeiros. Autenticação: Obrigatória
Parâmetros de Path
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cnpjCpfDi | string | Sim | CNPJ, CPF ou DI da pessoa |
Resposta de Sucesso
{
"id": "uuid",
"nome": "Empresa XYZ Ltda",
"cnpjCpf": "00.000.000/0001-00",
"tipo": "fornecedor",
"email": "[email protected]",
"ativo": true
}
Códigos de Erro Comuns
| Código | Descrição |
|---|---|
| 401 | Não autorizado |
| 404 | Pessoa não encontrada com esse documento |
Exemplos de Código
cURL
curl -X GET "https://api.app.hooked.com.br/api/pessoas/consultar/{cnpjCpfDi}" \
-H "Authorization: Bearer {token}"
JavaScript
const response = await fetch('https://api.app.hooked.com.br/api/pessoas/consultar/{cnpjCpfDi}', {
headers: { 'Authorization': 'Bearer {token}' }
});
const data = await response.json();
Python
import requests
data = requests.get(
'https://api.app.hooked.com.br/api/pessoas/consultar/{cnpjCpfDi}',
headers={'Authorization': 'Bearer {token}'}
).json()
Go
import (
"io"
"net/http"
)
req, _ := http.NewRequest("GET", "https://api.app.hooked.com.br/api/pessoas/consultar/{cnpjCpfDi}", 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/pessoas/consultar/{cnpjCpfDi}');
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/pessoas/consultar/{{$json.cnpjCpf}}",
"nodes": [
{
"parameters": {
"method": "GET",
"url": "https://api.app.hooked.com.br/api/pessoas/consultar/{{$json.cnpjCpf}}",
"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": {}
}
