Comissões · API Hooked

Visão Geral

O módulo Comissões gerencia o controle de comissões de vendedores geradas a partir de pedidos. Permite consultar comissões com filtros por empresa, vendedor, período e tipo, além de gerar relatórios em formato Excel.

Base URL

/api/comissoes

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

Endpoints

GET /api/comissoes

Descrição: Retorna uma lista paginada de comissões. Suporta filtros por empresa, vendedor, tipo e período.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`empresaId`	integer (int64)	query	—	Filtra por empresa
`vendedorId`	integer (int64)	query	—	Filtra por vendedor
`tipo`	string	query	—	Tipo de comissão
`dataInicial`	string (date-time)	query	—	Data inicial do período (`YYYY-MM-DDTHH:mm:ss`)
`dataFinal`	string (date-time)	query	—	Data final do período (`YYYY-MM-DDTHH:mm:ss`)
`property`	string	query	—	Campo pelo qual ordenar
`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": 5,
    "pageSize": 20,
    "totalCount": 98,
    "hasPrevious": false,
    "hasNext": true
  },
  "data": [
    {
      "id": 1,
      "codigo": "COM-001",
      "pessoaId": 10,
      "pessoaCodigo": 1001,
      "pessoaNome": "Empresa ABC Ltda",
      "pessoaCnpjCpfDi": "12.345.678/0001-99",
      "dataEmissao": "2024-01-15T00:00:00",
      "dataVencimento": "2024-02-15T00:00:00",
      "vendedorId": 5,
      "vendedorNome": "Carlos Vendas",
      "valor": 5000.00,
      "dataPaga": null,
      "totalPago": null,
      "valorComissao": 250.00,
      "comissaoGerada": true,
      "status": "Pendente",
      "pedidoId": 100,
      "numeroPedido": 1000,
      "empresaId": 1,
      "licencaId": 1
    }
  ],
  "summary": null
}

Campos da Resposta — `data[]`

Campo	Tipo	Descrição
`id`	integer (int64)	Identificador único da comissão
`codigo`	string	Código da comissão
`pessoaId`	integer (int64)	ID da pessoa (cliente)
`pessoaNome`	string	Nome da pessoa (cliente)
`pessoaCnpjCpfDi`	string	CNPJ/CPF da pessoa
`dataEmissao`	string (date-time)	Data de emissão do pedido
`dataVencimento`	string (date-time)	Data de vencimento da comissão
`vendedorId`	integer (int64)	ID do vendedor
`vendedorNome`	string	Nome do vendedor
`valor`	number (double)	Valor total do pedido
`valorComissao`	number (double)	Valor da comissão calculada
`dataPaga`	string (date-time)	Data em que a comissão foi paga
`totalPago`	number (double)	Total já pago da comissão
`comissaoGerada`	boolean	Indica se a comissão foi gerada
`status`	string	Status atual da comissão
`pedidoId`	integer (int64)	ID do pedido de origem
`numeroPedido`	integer (int64)	Número do pedido
`empresaId`	integer (int64)	ID da empresa

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

JavaScript

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

Python

import requests

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

import (
    "io"
    "net/http"
)

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

Descrição: Gera um relatório de comissões com os mesmos filtros da listagem. Quando excel=true, retorna o arquivo em formato Excel.

Parâmetros

Nome	Tipo	Local	Obrigatório	Descrição
`empresaId`	integer (int64)	query	—	Filtra por empresa
`vendedorId`	integer (int64)	query	—	Filtra por vendedor
`tipo`	string	query	—	Tipo de comissão
`dataInicial`	string (date-time)	query	—	Data inicial do período
`dataFinal`	string (date-time)	query	—	Data final do período
`excel`	boolean	query	—	Se `true`, retorna arquivo `.xlsx` para download
`property`	string	query	—	Campo pelo qual ordenar
`orderBy`	string	query	—	Direção: `asc` ou `desc`
`pageNumber`	integer	query	—	Número da página
`pageSize`	integer	query	—	Registros por página

Resposta de Sucesso `200`

Quando excel=false (padrão): retorna os dados no mesmo formato da listagem.

Quando excel=true: retorna o arquivo .xlsx para download no Content-Disposition.

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/comissoes/gerar-relatorio" \
  -H "Authorization: Bearer {token}" \
  -o arquivo

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/comissoes/gerar-relatorio', {
  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/comissoes/gerar-relatorio',
    headers={'Authorization': 'Bearer {token}'},
)
with open('arquivo', 'wb') as f:
    f.write(response.content)

import (
    "io"
    "net/http"
)

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

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`