Documentação da API Kombex — desenvolvedores

Visão geral

Protocolo	HTTP/1.1 ou superior
Formato	JSON (`Content-Type: application/json`)
Prefixo	Todas as rotas públicas ficam sob `/api/v1/`
URL base (desenvolvimento)	`https://api-desenv.kombex.log.br/public`
Endpoint completo	`{base}/api/v1/{recurso}`

Requisições OPTIONS (preflight CORS) respondem 204 sem corpo.

Formato padrão de resposta

Todas as respostas JSON seguem o envelope abaixo.

{
  "success": true,
  "data": { },
  "error": null
}

Campo	Tipo	Significado
`success`	boolean	Indica sucesso da operação
`data`	object, array ou null	Payload em sucesso; em alguns erros (ex.: 422) pode conter `detalhes`
`error`	string ou null	Mensagem legível em falha

Códigos HTTP frequentes: 200, 201, 204, 400, 401, 403, 404, 405, 409, 422, 429, 500, 503.

CORS e HTTPS

A API envia headers CORS incluindo métodos GET, POST, PUT, DELETE, OPTIONS e headers permitidos como Content-Type, Authorization, X-Kombex-Authorization, X-Access-Token e X-Kombex-Internal-Secret (quando aplicável).

Se o servidor estiver configurado para exigir HTTPS, requisições sem TLS (ou sem X-Forwarded-Proto: https atrás de proxy confiável) podem ser recusadas.

Autenticação

1. Credenciais de aplicativo

Você recebe api_key e api_secret (o segredo em texto plano; no servidor armazena-se apenas o hash).
POST /api/v1/auth/token com JSON api_key + api_secret.
A resposta traz access_token (JWT, curta duração) e refresh_token (JWT, longa duração).
Nas rotas protegidas, envie o access token em um dos headers abaixo.

TTL típicos: access ~1 hora; refresh ~7 dias (valores podem ser ajustados no servidor).

Algoritmo JWT: HS256. Claims úteis no payload incluem sub (id do registro), cid (identificador lógico do cliente), amb (desenv ou production) e typ (access ou refresh).

2. Headers do access token (ordem de leitura no servidor)

Authorization: Bearer <token>
X-Kombex-Authorization: Bearer <token> — recomendado em cPanel / CGI / FastCGI quando Authorization não chega ao PHP.
X-Access-Token: <token> — somente o JWT, sem a palavra Bearer.

3. Renovação do access token

POST /api/v1/auth/refresh com corpo:

{ "refresh_token": "<JWT refresh>" }

Resposta: novo access_token, token_type, expires_in, ambiente.

Ambiente. O cadastro da credencial no servidor deve estar alinhado ao ambiente do endpoint (desenvolvimento vs produção). Caso contrário, POST /auth/token pode retornar 403.

Rate limiting

Contexto	Limite (padrão)
`POST /auth/token`	Por IP + `api_key` — típico 20 req/min
Demais rotas com JWT	Por cliente API — típico 100 req/min

Resposta típica: 429, success: false, mensagem em error.

Referência de endpoints

{codigo} é o código público da solicitação (ex.: KMBX20260331120000ABC123).

Método	Rota	Auth	Descrição
POST	`/api/v1/auth/token`	—	Emite access + refresh JWT
POST	`/api/v1/auth/refresh`	—	Renova access JWT
POST	`/api/v1/solicitacoes`	JWT	Cria solicitação (orçamento/frete)
GET	`/api/v1/solicitacoes`	JWT	Lista solicitações do cliente
GET	`/api/v1/solicitacoes/{codigo}`	JWT	Detalhe por código público
PUT	`/api/v1/solicitacoes/{codigo}/status`	`X-Kombex-Internal-Secret`	Atualiza status — uso restrito (ver abaixo)
DELETE	`/api/v1/solicitacoes/{codigo}`	JWT	Cancela solicitação
POST	`/api/v1/webhooks`	JWT	Registra URL de webhook
GET	`/api/v1/webhooks`	JWT	Lista webhooks ativos

POST `/api/v1/auth/token`

Corpo (JSON)

Campo	Obrigatório	Descrição
`api_key`	sim	Chave pública
`api_secret`	sim	Segredo em texto plano (não é o hash)

Resposta 200 (data): access_token, refresh_token, token_type (Bearer), expires_in (segundos), ambiente.

Exemplo — corpo da requisição

{
  "api_key": "kbx_demo_api_key_001",
  "api_secret": "seu_segredo_em_texto_plano"
}

Exemplo — resposta 200 OK

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiY2lkIjoiREVNTzAwMSIsImFtYiI6ImRlc2V2IiwidHlwIjoiYWNjZXNzIiwiaWF0IjoxNzE0MDAwMDAwLCJleHAiOjE3MTQwMDM2MDB9.exemplo_assinatura",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwidHlwIjoicmVmcmVzaCIsImV4cCI6MTcxNDYwNDgwMH0.exemplo_refresh",
    "token_type": "Bearer",
    "expires_in": 3600,
    "ambiente": "desenv"
  },
  "error": null
}

Os JWT acima estão truncados/ilustrativos; na prática são strings longas em Base64.

Erros comuns: 400 (campos), 401 (credenciais), 403 (ambiente), 429 (rate limit).

POST `/api/v1/auth/refresh`

Corpo: refresh_token (JWT tipo refresh).

Resposta 200: access_token, token_type, expires_in, ambiente.

Exemplo — corpo da requisição

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwidHlwIjoicmVmcmVzaCIsImV4cCI6MTcxNDYwNDgwMH0.exemplo_refresh"
}

Exemplo — resposta 200 OK

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiY2lkIjoiREVNTzAwMSIsImFtYiI6ImRlc2V2IiwidHlwIjoiYWNjZXNzIiwiZXhwIjoxNzE0MDAzNjAwfQ.novo_access",
    "token_type": "Bearer",
    "expires_in": 3600,
    "ambiente": "desenv"
  },
  "error": null
}

POST `/api/v1/solicitacoes`

Header: JWT (recomendado X-Kombex-Authorization: Bearer …).

Corpo (principais campos):

termo_aceite — obrigatório aceito (true, 1, "1", "Sim", "sim").
Origem e destino: origem_nome, origem_documento, origem_contato, origem_telefone, origem_cep, origem_rua, origem_numero, origem_bairro, origem_cidade, origem_estado e os equivalentes destino_*.
Opcionais: origem_complemento, destino_complemento, pagamento_frete, observacao.
itens — array não vazio; cada item com peso, valor_nf, quantidade ou qtde (≥ 1), e:
- dimensoes: array de { "altura", "largura", "comprimento" } (cm), ou
- metro_cubico > 0 se não houver dimensões válidas.

Resposta 201 (data): id, codigo, status (0 solicitado), valor_frete, metro_cubico_total, empresas_rota, resumo_rota.

Exemplo — corpo da requisição

Campos de origem/destino usam prefixos origem_* e destino_* no JSON (não objetos aninhados).

{
  "termo_aceite": true,
  "origem_nome": "Empresa A",
  "origem_documento": "12.345.678/0001-90",
  "origem_contato": "João",
  "origem_telefone": "44999990000",
  "origem_cep": "87000000",
  "origem_rua": "Rua Um",
  "origem_numero": "100",
  "origem_bairro": "Centro",
  "origem_cidade": "MARINGA",
  "origem_estado": "PR",
  "origem_complemento": "",
  "destino_nome": "Empresa B",
  "destino_documento": "98.765.432/0001-10",
  "destino_contato": "Maria",
  "destino_telefone": "44988887777",
  "destino_cep": "86000000",
  "destino_rua": "Rua Dois",
  "destino_numero": "200",
  "destino_bairro": "Zona 7",
  "destino_cidade": "LONDRINA",
  "destino_estado": "PR",
  "destino_complemento": "",
  "pagamento_frete": "origem",
  "observacao": "",
  "itens": [
    {
      "descricao": "SNF",
      "quantidade": 1,
      "peso": 10,
      "valor_nf": 500,
      "nf_doc": "NF-001",
      "metro_cubico": 0,
      "dimensoes": [
        { "altura": 35, "largura": 45, "comprimento": 55 },
        { "altura": 65, "largura": 70, "comprimento": 75 }
      ]
    }
  ]
}

Exemplo — resposta 201 Created

{
  "success": true,
  "data": {
    "id": 3049,
    "codigo": "KMBX20260402123934DEC98C",
    "status": 0,
    "valor_frete": 118.09,
    "metro_cubico_total": 0.428,
    "empresas_rota": [
      {
        "empresa_id": 16,
        "empresa_name": "EMPRESA XPTO - LONDRINA X MARINGÁ"
      }
    ],
    "resumo_rota": {
      "status": "sucesso",
      "resumo": "A EMPRESA XPTO - LONDRINA X MARINGÁ fará a coleta em MARINGA e entrega direta em LONDRINA",
      "rota": [
        {
          "empresa_id": 16,
          "empresa_name": "EMPRESA XPTO - LONDRINA X MARINGÁ",
          "acao": "Coleta/Entrega",
          "cidades": ["MARINGA", "LONDRINA"]
        }
      ]
    }
  },
  "error": null
}

Exemplo — erro 422 (frete/rota)

{
  "success": false,
  "data": {
    "detalhes": "Mensagem explicando a regra de frete ou rota que não pôde ser atendida."
  },
  "error": "Não foi possível calcular o frete."
}

Erros: 400, 401, 422 (data.detalhes com motivo de frete/rota), 429, 500.

GET `/api/v1/solicitacoes`

Query (opcional):

Parâmetro	Descrição
`status`	Se informado, apenas 0 ou 1 retornam linhas; outros → lista vazia
`data_inicio` / `data_fim`	`YYYY-MM-DD`, dentro da janela permitida
`page`	Página (≥ 1)
`per_page`	Itens por página (máximo definido no servidor)

A listagem considera uma janela temporal retroativa limitada (ex.: últimos 30 dias até o fim do dia atual, conforme configuração). Sem status na query, entram em geral registros com status 0 ou 1.

Resposta 200: solicitacoes, periodo_consulta (data_inicio, data_fim, max_dias_retroativos), pagination (total, page, per_page, total_pages).

Exemplo — resposta 200 OK (GET /api/v1/solicitacoes?status=0&page=1&per_page=20)

{
  "success": true,
  "data": {
    "solicitacoes": [
      {
        "id": 3049,
        "codigo": "KMBX20260402123934DEC98C",
        "cliente_id_api": "DEMO001",
        "id_usuario_franqueado": 16,
        "origem": {
          "nome": "Empresa A",
          "documento": "12.345.678/0001-90",
          "contato": "João",
          "telefone": "44999990000",
          "cep": "87000000",
          "rua": "Rua Um",
          "numero": "100",
          "complemento": "",
          "bairro": "Centro",
          "cidade": "MARINGA",
          "estado": "PR"
        },
        "destino": {
          "nome": "Empresa B",
          "documento": "98.765.432/0001-10",
          "contato": "Maria",
          "telefone": "44988887777",
          "cep": "86000000",
          "rua": "Rua Dois",
          "numero": "200",
          "complemento": "",
          "bairro": "Zona 7",
          "cidade": "LONDRINA",
          "estado": "PR"
        },
        "itens": [
          {
            "descricao": "SNF",
            "quantidade": 1,
            "peso": 10,
            "valor_nf": 500,
            "nf_doc": "NF-001",
            "metro_cubico": 0,
            "dimensoes": [
              { "altura": 35, "largura": 45, "comprimento": 55 },
              { "altura": 65, "largura": 70, "comprimento": 75 }
            ]
          }
        ],
        "resumo_rota": {
          "status": "sucesso",
          "rota": [
            {
              "empresa_id": 16,
              "empresa_name": "EMPRESA XPTO - LONDRINA X MARINGÁ",
              "acao": "Coleta/Entrega",
              "cidades": ["MARINGA", "LONDRINA"]
            }
          ],
          "resumo": "A EMPRESA XPTO - LONDRINA X MARINGÁ fará a coleta em MARINGA e entrega direta em LONDRINA"
        },
        "data_criacao": "2026-04-02 09:39:34",
        "data_atualizacao_status": null,
        "status": 0,
        "metro_cubico_total": "0.428",
        "valor_frete": "118.09",
        "pagamento_frete": "origem",
        "observacao": "",
        "prazo_entrega": "12 horas",
        "termo_aceite": "Sim"
      }
    ],
    "periodo_consulta": {
      "data_inicio": "2026-03-04",
      "data_fim": "2026-04-03",
      "max_dias_retroativos": 30
    },
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 20,
      "total_pages": 1
    }
  },
  "error": null
}

GET `/api/v1/solicitacoes/{codigo}`

Retorna apenas se a solicitação pertencer ao cliente_id do token.

data inclui: identificação, status, datas, valores, origem / destino aninhados, itens, resumo_rota, etc.

Exemplo — resposta 200 OK (data = um único objeto; mesmo formato de cada item de solicitacoes na listagem)

{
  "success": true,
  "data": {
    "id": 3049,
    "codigo": "KMBX20260402123934DEC98C",
    "cliente_id_api": "DEMO001",
    "id_usuario_franqueado": 16,
    "origem": {
      "nome": "Empresa A",
      "documento": "12.345.678/0001-90",
      "contato": "João",
      "telefone": "44999990000",
      "cep": "87000000",
      "rua": "Rua Um",
      "numero": "100",
      "complemento": "",
      "bairro": "Centro",
      "cidade": "MARINGA",
      "estado": "PR"
    },
    "destino": {
      "nome": "Empresa B",
      "documento": "98.765.432/0001-10",
      "contato": "Maria",
      "telefone": "44988887777",
      "cep": "86000000",
      "rua": "Rua Dois",
      "numero": "200",
      "complemento": "",
      "bairro": "Zona 7",
      "cidade": "LONDRINA",
      "estado": "PR"
    },
    "itens": [
      {
        "descricao": "SNF",
        "quantidade": 1,
        "peso": 10,
        "valor_nf": 500,
        "nf_doc": "NF-001",
        "metro_cubico": 0,
        "dimensoes": [
          { "altura": 35, "largura": 45, "comprimento": 55 },
          { "altura": 65, "largura": 70, "comprimento": 75 }
        ]
      }
    ],
    "resumo_rota": {
      "status": "sucesso",
      "rota": [
        {
          "empresa_id": 16,
          "empresa_name": "EMPRESA XPTO - LONDRINA X MARINGÁ",
          "acao": "Coleta/Entrega",
          "cidades": ["MARINGA", "LONDRINA"]
        }
      ],
      "resumo": "A EMPRESA XPTO - LONDRINA X MARINGÁ fará a coleta em MARINGA e entrega direta em LONDRINA"
    },
    "data_criacao": "2026-04-02 09:39:34",
    "data_atualizacao_status": null,
    "status": 0,
    "metro_cubico_total": "0.428",
    "valor_frete": "118.09",
    "pagamento_frete": "origem",
    "observacao": "",
    "prazo_entrega": "12 horas",
    "termo_aceite": "Sim"
  },
  "error": null
}

404 se não existir ou não for do cliente.

PUT `/api/v1/solicitacoes/{codigo}/status`

Uso restrito. Este endpoint não utiliza JWT do cliente. Exige o header X-Kombex-Internal-Secret com valor fornecido pela Kombex para integrações internas ou parceiros autorizados. Aplicações de cliente devem acompanhar mudanças via consultas ou webhooks.

Corpo: { "status": 2 } (inteiro conforme tabela de status).

Regras: não atualiza se o status atual for terminal — 409. Valores inválidos — 400. Endpoint indisponível se segredo interno não estiver configurado — 503.

Resposta 200: objeto completo da solicitação após atualização (mesmo formato do GET). Pode disparar webhooks de evento status.

Exemplo — corpo da requisição

{
  "status": 2
}

Exemplo — resposta 200 OK (mesmo formato do GET por código; aqui status passou para 2 — em coleta)

{
  "success": true,
  "data": {
    "id": 3049,
    "codigo": "KMBX20260402123934DEC98C",
    "cliente_id_api": "DEMO001",
    "id_usuario_franqueado": 16,
    "origem": {
      "nome": "Empresa A",
      "documento": "12.345.678/0001-90",
      "contato": "João",
      "telefone": "44999990000",
      "cep": "87000000",
      "rua": "Rua Um",
      "numero": "100",
      "complemento": "",
      "bairro": "Centro",
      "cidade": "MARINGA",
      "estado": "PR"
    },
    "destino": {
      "nome": "Empresa B",
      "documento": "98.765.432/0001-10",
      "contato": "Maria",
      "telefone": "44988887777",
      "cep": "86000000",
      "rua": "Rua Dois",
      "numero": "200",
      "complemento": "",
      "bairro": "Zona 7",
      "cidade": "LONDRINA",
      "estado": "PR"
    },
    "itens": [
      {
        "descricao": "SNF",
        "quantidade": 1,
        "peso": 10,
        "valor_nf": 500,
        "nf_doc": "NF-001",
        "metro_cubico": 0,
        "dimensoes": [
          { "altura": 35, "largura": 45, "comprimento": 55 },
          { "altura": 65, "largura": 70, "comprimento": 75 }
        ]
      }
    ],
    "resumo_rota": {
      "status": "sucesso",
      "rota": [
        {
          "empresa_id": 16,
          "empresa_name": "EMPRESA XPTO - LONDRINA X MARINGÁ",
          "acao": "Coleta/Entrega",
          "cidades": ["MARINGA", "LONDRINA"]
        }
      ],
      "resumo": "A EMPRESA XPTO - LONDRINA X MARINGÁ fará a coleta em MARINGA e entrega direta em LONDRINA"
    },
    "data_criacao": "2026-04-02 09:39:34",
    "data_atualizacao_status": "2026-04-02 14:22:10",
    "status": 2,
    "metro_cubico_total": "0.428",
    "valor_frete": "118.09",
    "pagamento_frete": "origem",
    "observacao": "",
    "prazo_entrega": "12 horas",
    "termo_aceite": "Sim"
  },
  "error": null
}

DELETE `/api/v1/solicitacoes/{codigo}`

Cancela (status 9) se ainda não estiver em estado terminal; caso contrário 409.

Resposta 200 (data): mensagem, codigo, id, status, data_atualizacao_status.

Exemplo — resposta 200 OK (sem corpo na requisição além do JWT no header)

{
  "success": true,
  "data": {
    "mensagem": "Solicitação cancelada com sucesso.",
    "codigo": "KMBX20260402123934DEC98C",
    "id": 3049,
    "status": 9,
    "data_atualizacao_status": "2026-04-02 16:05:00"
  },
  "error": null
}

POST `/api/v1/webhooks` · GET `/api/v1/webhooks`

POST — corpo: url (obrigatório), eventos (opcional; padrão status; lista separada por vírgula ou *), secret (opcional, para assinatura HMAC).

POST — resposta 201: id, url, eventos.

GET — resposta 200: webhooks array com itens ativos (id, url, eventos, ativo, created_at).

POST — exemplo de corpo

{
  "url": "https://seu-sistema.com/webhook/kombex",
  "eventos": "status",
  "secret": "opcional_para_hmac_sha256"
}

POST — exemplo de resposta 201 Created

{
  "success": true,
  "data": {
    "id": 12,
    "url": "https://seu-sistema.com/webhook/kombex",
    "eventos": "status"
  },
  "error": null
}

GET — exemplo de resposta 200 OK

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": 12,
        "url": "https://seu-sistema.com/webhook/kombex",
        "eventos": "status",
        "ativo": "Sim",
        "created_at": "2026-04-01 10:00:00"
      }
    ]
  },
  "error": null
}

Webhooks (callback)

Quando o status da solicitação muda, a API pode enviar POST para URLs cadastradas.

Exemplo — corpo enviado pela Kombex ao seu endpoint (POST)

{
  "event": "solicitacao.status",
  "timestamp": "2026-04-02T14:22:10+00:00",
  "payload": {
    "codigo": "KMBX20260402123934DEC98C",
    "status_anterior": 0,
    "status_novo": 2,
    "solicitacao": {
      "id": 3049,
      "codigo": "KMBX20260402123934DEC98C",
      "status": 2,
      "valor_frete": "118.09",
      "origem": { "cidade": "MARINGA", "estado": "PR" },
      "destino": { "cidade": "LONDRINA", "estado": "PR" }
    }
  }
}

O objeto solicitacao no webhook pode trazer o mesmo nível de detalhe do GET por código, conforme a versão da API.

Se um secret foi configurado no cadastro do webhook:

X-Kombex-Signature: sha256=<HMAC-SHA256 do corpo JSON com o secret>

Códigos de status da solicitação

Valor	Significado
`0`	Solicitado
`1`	Em processamento
`2`	Em coleta
`3`	Em trânsito
`4`	Entregue (terminal)
`9`	Cancelado (terminal)

Exemplos por linguagem

Substitua BASE_URL, API_KEY, API_SECRET e tokens pelos valores reais. Em produção, guarde segredos em variáveis de ambiente.

Obter token

curl -s -X POST "${BASE_URL}/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"api_key":"'"$API_KEY"'","api_secret":"'"$API_SECRET"'"}'

Criar solicitação (com token)

curl -s -X POST "${BASE_URL}/api/v1/solicitacoes" \
  -H "Content-Type: application/json" \
  -H "X-Kombex-Authorization: Bearer $ACCESS_TOKEN" \
  -d @payload-solicitacao.json

JavaScript (fetch) — token + POST solicitação

const BASE_URL = 'https://seu-dominio';

async function obterToken(apiKey, apiSecret) {
  const res = await fetch(`${BASE_URL}/api/v1/auth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ api_key: apiKey, api_secret: apiSecret }),
  });
  const json = await res.json();
  if (!json.success) throw new Error(json.error || 'Falha no token');
  return json.data;
}

async function criarSolicitacao(accessToken, payload) {
  const res = await fetch(`${BASE_URL}/api/v1/solicitacoes`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Kombex-Authorization': `Bearer ${accessToken}`,
    },
    body: JSON.stringify(payload),
  });
  return res.json();
}

// React: chame obterToken / criarSolicitacao em event handlers ou em server actions
// (nunca exponha api_secret no bundle público — use backend ou variáveis de build seguras).

PHP (cURL)

<?php
function kombex_post_json(string $url, array $body, array $extraHeaders = []): array {
    $ch = curl_init($url);
    $headers = array_merge(
        ['Content-Type: application/json'],
        $extraHeaders
    );
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_POSTFIELDS => json_encode($body),
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $raw = curl_exec($ch);
    curl_close($ch);
    return json_decode($raw, true) ?? [];
}

$base = 'https://seu-dominio';
$auth = kombex_post_json($base . '/api/v1/auth/token', [
    'api_key' => getenv('KOMBEX_API_KEY'),
    'api_secret' => getenv('KOMBEX_API_SECRET'),
]);
$access = $auth['data']['access_token'] ?? null;

$solic = kombex_post_json($base . '/api/v1/solicitacoes', [
    'termo_aceite' => true,
    'origem_nome' => 'Empresa A',
    // ... demais campos ...
    'itens' => [['quantidade' => 1, 'peso' => 10, 'valor_nf' => 500, 'dimensoes' => [
        ['altura' => 35, 'largura' => 45, 'comprimento' => 55],
    ]]],
], ['X-Kombex-Authorization: Bearer ' . $access]);

Python (requests)

import os
import requests

BASE = os.environ["KOMBEX_BASE_URL"].rstrip("/")

def obter_token():
    r = requests.post(
        f"{BASE}/api/v1/auth/token",
        json={
            "api_key": os.environ["KOMBEX_API_KEY"],
            "api_secret": os.environ["KOMBEX_API_SECRET"],
        },
        timeout=30,
    )
    r.raise_for_status()
    body = r.json()
    if not body.get("success"):
        raise RuntimeError(body.get("error"))
    return body["data"]["access_token"]

def criar_solicitacao(access_token, payload):
    r = requests.post(
        f"{BASE}/api/v1/solicitacoes",
        json=payload,
        headers={"X-Kombex-Authorization": f"Bearer {access_token}"},
        timeout=60,
    )
    return r.json()

Node.js (fetch nativo)

const BASE_URL = process.env.KOMBEX_BASE_URL;

async function obterToken() {
  const res = await fetch(`${BASE_URL}/api/v1/auth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      api_key: process.env.KOMBEX_API_KEY,
      api_secret: process.env.KOMBEX_API_SECRET,
    }),
  });
  const json = await res.json();
  if (!json.success) throw new Error(json.error);
  return json.data.access_token;
}

async function listarSolicitacoes(accessToken, query = '') {
  const res = await fetch(`${BASE_URL}/api/v1/solicitacoes?${query}`, {
    headers: { 'X-Kombex-Authorization': `Bearer ${accessToken}` },
  });
  return res.json();
}

Erros e diagnóstico

Sintoma	O que verificar
404 com mensagem sobre prefixo `/api/v1/`	URL sem o prefixo correto no path
401 token ausente	Enviar JWT em `Authorization`, `X-Kombex-Authorization` ou `X-Access-Token`
401 após deploy em cPanel	Usar `X-Kombex-Authorization: Bearer …`
403 em `/auth/token`	Ambiente da credencial vs ambiente do endpoint
422 ao criar solicitação	Validação de endereços/itens ou rota/frete; ver `data.detalhes`

Coleção Postman

O repositório da API pode incluir o arquivo Kombex-API-v1.postman_collection.json com variáveis base_url, api_key, api_secret, access_token, refresh_token e codigo_solicitacao. Importe no Postman para testar o fluxo completo.

Dica: após POST /auth/token, copie data.access_token e data.refresh_token para as variáveis da coleção.

Precisa de credenciais ou suporte?

Faça o cadastro da empresa para solicitar acesso ou entre em contato para obter api_key e api_secret no ambiente correto.

Cadastro para uso da API Falar com a Kombex Visão geral da API

Informações de Contato

Integre orçamentos e solicitações de frete

Visão geral

Formato padrão de resposta

CORS e HTTPS

Autenticação

1. Credenciais de aplicativo

2. Headers do access token (ordem de leitura no servidor)

3. Renovação do access token

Rate limiting

Referência de endpoints

POST `/api/v1/auth/token`

POST `/api/v1/auth/refresh`

POST `/api/v1/solicitacoes`

GET `/api/v1/solicitacoes`

GET `/api/v1/solicitacoes/{codigo}`

PUT `/api/v1/solicitacoes/{codigo}/status`

DELETE `/api/v1/solicitacoes/{codigo}`

POST `/api/v1/webhooks` · GET `/api/v1/webhooks`

Webhooks (callback)

Códigos de status da solicitação

Exemplos por linguagem

Obter token

Criar solicitação (com token)

JavaScript (fetch) — token + POST solicitação

PHP (cURL)

Python (requests)

Node.js (fetch nativo)

Erros e diagnóstico

Coleção Postman

Precisa de credenciais ou suporte?

Vamos trabalhar juntos!

Privacidade e Cookies

Informações de Contato