API Truex

Integre seu sistema com a plataforma Truex e automatize sua gestão de vendas, estoque e notas fiscais.

🚀 Base URL

Todas as requisições devem ser feitas para:

https://api.truex.com.br/v1

📦 O que você pode fazer

A API Truex permite que você:

Consulte e gerencie produtos e estoque
Crie e acompanhe pedidos de venda
Gerencie sua base de clientes
Emita notas fiscais eletrônicas (NF-e, NFC-e)
Receba webhooks em tempo real
Integre com marketplaces e e-commerces

Autenticação

A API Truex utiliza tokens de acesso (Bearer Token) para autenticação.

Obtendo seu Token

Acesse o painel do Truex em Configurações → API para gerar seu token de acesso.

# Inclua o header Authorization em todas as requisições

curl https://api.truex.com.br/v1/produtos \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json"

⚠️ Importante

Mantenha seu token em segurança! Nunca exponha em código client-side ou repositórios públicos. Se comprometido, regenere imediatamente no painel.

Códigos de Erro

A API retorna códigos HTTP padrão para indicar sucesso ou falha.

200 OK - Requisição bem sucedida

201 Created - Recurso criado com sucesso

400 Bad Request - Parâmetros inválidos

401 Unauthorized - Token inválido ou ausente

404 Not Found - Recurso não encontrado

429 Too Many Requests - Rate limit excedido

500 Internal Error - Erro interno do servidor

Formato de Erro

                        Resposta de erro
                    

                        {
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "O campo 'email' é obrigatório",
    "field": "email"
  }
}
                    

Rate Limit

Para garantir estabilidade, aplicamos limites de requisições por minuto.

100

Requisições / minuto

5.000

Requisições / hora

50.000

Requisições / dia

Os headers de resposta incluem informações sobre seu uso:

                        X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
                    

Produtos

Gerencie seu catálogo de produtos.

GET /produtos Listar todos os produtos

Query Parameters

Parâmetro	Tipo	Descrição
`page` opcional	integer	Página atual (padrão: 1)
`per_page` opcional	integer	Itens por página (máx: 100)
`sku` opcional	string	Filtrar por SKU
`ativo` opcional	boolean	Filtrar por status

Resposta

                                {
  "data": [
    {
      "id": 12345,
      "sku": "PROD-001",
      "nome": "Notebook Gamer XYZ",
      "preco": 4599.90,
      "estoque": 25,
      "ncm": "8471.30.19",
      "ativo": true,
      "created_at": "2025-01-01T10:00:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20
  }
}
                            

GET /produtos/{id} Buscar produto por ID

POST /produtos Criar novo produto

Body (JSON)

Campo	Tipo	Descrição
`sku` obrigatório	string	Código único do produto
`nome` obrigatório	string	Nome do produto
`preco` obrigatório	number	Preço de venda
`ncm` opcional	string	Código NCM (fiscal)

PUT /produtos/{id} Atualizar produto

DELETE /produtos/{id} Remover produto

Pedidos

Gerencie pedidos de venda.

GET /pedidos Listar pedidos

Query Parameters

`status` opcional	string	pendente, aprovado, enviado, entregue, cancelado
`data_inicio` opcional	date	Data inicial (YYYY-MM-DD)
`data_fim` opcional	date	Data final (YYYY-MM-DD)
`marketplace` opcional	string	Filtrar por origem (mercadolivre, shopee, etc)

GET /pedidos/{id} Buscar pedido

POST /pedidos Criar pedido

PATCH /pedidos/{id}/status Atualizar status

POST /pedidos/{id}/rastreio Adicionar rastreio

Clientes

Gerencie sua base de clientes.

GET /clientes Listar clientes

GET /clientes/{id} Buscar cliente

POST /clientes Criar cliente

PUT /clientes/{id} Atualizar cliente

Estoque

Controle de estoque e movimentações.

GET /estoque Consultar estoque

PUT /estoque/{produto_id} Atualizar quantidade

Body (JSON)

                                {
  "quantidade": 50,
  "tipo": "entrada",  // entrada ou saida
  "motivo": "Compra fornecedor"
}
                            

GET /estoque/movimentacoes Histórico de movimentações

Notas Fiscais

Emissão e consulta de documentos fiscais.

GET /notas-fiscais Listar notas

POST /notas-fiscais Emitir NF-e

Body (JSON)

                                {
  "pedido_id": 12345,
  "tipo": "nfe",  // nfe, nfce, nfse
  "natureza_operacao": "Venda de mercadoria",
  "enviar_email": true
}
                            

GET /notas-fiscais/{id}/pdf Download PDF (DANFE)

GET /notas-fiscais/{id}/xml Download XML

POST /notas-fiscais/{id}/cancelar Cancelar nota

POST /notas-fiscais/{id}/carta-correcao Carta de correção

Webhooks

Receba notificações em tempo real quando eventos acontecerem.

Configuração

Configure seus webhooks em Configurações → API → Webhooks no painel do Truex.

Eventos Disponíveis

pedido.criado Novo pedido recebido

pedido.atualizado Status do pedido alterado

pedido.cancelado Pedido foi cancelado

produto.criado Novo produto cadastrado

produto.atualizado Produto foi alterado

estoque.baixo Estoque abaixo do mínimo

nfe.emitida Nota fiscal autorizada

nfe.cancelada Nota fiscal cancelada

Payload do Webhook

                        {
  "evento": "pedido.criado",
  "timestamp": "2025-01-15T14:30:00Z",
  "data": {
    "id": 12345,
    "numero": "PED-2025-0001",
    "valor_total": 299.90,
    "cliente": {
      "nome": "João Silva",
      "email": "joao@email.com"
    }
  }
}
                    

🔐 Verificação de Assinatura

Todos os webhooks incluem o header X-Truex-Signature com uma assinatura HMAC-SHA256. Verifique esta assinatura para garantir a autenticidade.

Sandbox

Ambiente de testes para desenvolvimento.

🧪 URL do Sandbox

https://sandbox.api.truex.com.br/v1

O ambiente sandbox permite testar todas as funcionalidades sem afetar dados reais. As notas fiscais emitidas no sandbox são enviadas em modo de homologação.

Diferenças do Sandbox

Notas fiscais são emitidas em ambiente de homologação
Dados são resetados semanalmente
Rate limits mais permissivos (500 req/min)
Webhooks possuem prefixo sandbox.

SDKs e Bibliotecas

Bibliotecas oficiais para facilitar a integração.

Node.js

npm install @truex/sdk

Python

pip install truex-python

PHP

composer require truex/sdk

Exemplo de Uso (Node.js)

                        const Truex = require('@truex/sdk');

const client = new Truex({
  apiKey: 'sua_api_key',
  sandbox: true  // use false para produção
});

// Listar produtos
const produtos = await client.produtos.list({
  page: 1,
  per_page: 20
});

// Criar pedido
const pedido = await client.pedidos.create({
  cliente_id: 123,
  itens: [
    { produto_id: 456, quantidade: 2 }
  ]
});

// Emitir NF-e
const nfe = await client.notasFiscais.emitir({
  pedido_id: pedido.id
});
                    