API Reference

Trenix Logística

API REST da Trenix Logística para integração com gateways de pagamento. Gere códigos de rastreio automaticamente para seus clientes.

#Autenticação

Todas as requisições precisam incluir o header de autenticação com sua API key.

Authorization: Bearer {API_KEY}

Onde obter sua API key? Acesse o painel do vendedor em /seller/api para gerar e gerenciar suas chaves.

#Base URL

Todas as requisições devem ser enviadas para a seguinte URL base:

https://your-domain.com/api/v1

#Criar Rastreio

POST/api/v1/trackingsR$ 1,00 por rastreio

Cria um novo código de rastreio. Cada criação custa R$ 1,00 e será debitado do seu saldo.

Request Body

{
  "order_number": "PED-001",
  "profile": "default",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "phone": "11999999999",
    "cpf": "123.456.789-00"
  },
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Apto 4B",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01001-000"
  }
}

Response 201

{
  "tracking_code": "BR123456789CD",
  "public_link": "https://your-domain.com/rastreie-sua-encomenda/BR123456789CD",
  "status": "processing",
  "delivery_estimate": "2026-03-28",
  "cost": 1.00,
  "seller_balance": 49.00
}

#Listar Rastreios

GET/api/v1/trackings

Retorna uma lista paginada de todos os seus rastreios.

Query Parameters

Param	Tipo	Descrição
page	integer	Página atual (padrão: 1)
per_page	integer	Itens por página (máx: 100)
search	string	Busca por código ou pedido
status	string	Filtrar por status
date_from	string	Data início (YYYY-MM-DD)
date_to	string	Data fim (YYYY-MM-DD)

Response 200

{
  "data": [
    {
      "tracking_code": "BR123456789CD",
      "order_number": "PED-001",
      "status": "in_transit",
      "created_at": "2026-03-20T14:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 58,
    "total_pages": 3
  }
}

#Detalhe do Rastreio

GET/api/v1/trackings/{code}

Retorna os detalhes completos de um rastreio, incluindo todos os eventos.

Response 200

{
  "tracking_code": "BR123456789CD",
  "order_number": "PED-001",
  "status": "in_transit",
  "delivery_estimate": "2026-03-28",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "events": [
    {
      "status": "in_transit",
      "description": "Objeto em trânsito para a cidade de destino",
      "location": "São Paulo - SP",
      "created_at": "2026-03-21T08:15:00Z"
    },
    {
      "status": "shipped",
      "description": "Objeto postado na agência",
      "location": "Curitiba - PR",
      "created_at": "2026-03-20T16:00:00Z"
    }
  ]
}

#Saldo do Vendedor

GET/api/v1/balance

Retorna o saldo atual da sua conta de vendedor.

Response 200

{
  "balance": 49.00,
  "currency": "BRL"
}

#Webhook Pagap

Endpoint para receber webhooks da Pagap. Quando um pagamento é aprovado, a Pagap envia os dados do cliente e o sistema gera automaticamente o código de rastreio, debita R$ 1,00 do saldo e envia email ao cliente.

POST/api/v1/webhooks/pagap

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Payload (enviado pela Pagap)

{
  "event": "paid",
  "data": {
    "transaction_id": "txn_8bfe81f7-a4a2",
    "status": "paid",
    "amount": 100.00,
    "customer_name": "João Silva",
    "created_at": "2026-03-22T20:44:51Z",
    "paid_at": "2026-03-22T20:50:12Z",
    "customer_email": "joao@email.com",
    "customer_phone": "(11) 99999-9999",
    "customer_document": "12345678900",
    "customer_postal_code": "01310-100",
    "customer_address": "Av. Paulista",
    "customer_address_number": "1000",
    "customer_neighborhood": "Bela Vista",
    "customer_city": "São Paulo",
    "customer_state": "SP"
  }
}

Response 201

{
  "message": "Rastreio criado com sucesso!",
  "processed": true,
  "tracking": {
    "tracking_code": "PQR63095545178516BR",
    "public_link": "https://trenixlogistica.online/rastreie-sua-encomenda/PQR63095545178516BR",
    "status": "processing",
    "delivery_estimate": "2026-03-28T14:30:00Z",
    "cost": 1.00,
    "seller_balance": 49.00
  }
}

Configuração na Pagap

1. Acesse as configurações de webhook na Pagap

2. URL do webhook: https://trenixlogistica.online/api/v1/webhooks/pagap

3. Header de autenticação: Authorization: Bearer SUA_API_KEY

4. Evento: paid

Notas

Apenas eventos paid são processados. Outros eventos retornam 200 sem ação.
Se a mesma transaction_id for enviada novamente, retorna o rastreio existente (idempotente).
O saldo do seller deve ser suficiente. Se insuficiente, retorna 402.
O email ao cliente é enviado automaticamente após a criação do rastreio.

#Exemplos de Código

Exemplos completos de como criar um rastreio em diferentes linguagens.

curl -X POST https://your-domain.com/api/v1/trackings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "order_number": "PED-001",
    "profile": "default",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "11999999999",
      "cpf": "123.456.789-00"
    },
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "complement": "Apto 4B",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipcode": "01001-000"
    }
  }'

#Códigos de Erro

Quando uma requisição falha, a API retorna um objeto de erro no seguinte formato:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo 'customer.email' é obrigatório.",
    "details": {
      "field": "customer.email",
      "rule": "required"
    }
  }
}

Códigos

Código	HTTP	Descrição
INVALID_API_KEY	401	API key inválida
SELLER_BLOCKED	403	Seller bloqueado
INSUFFICIENT_BALANCE	402	Saldo insuficiente
VALIDATION_ERROR	422	Dados inválidos
RATE_LIMIT_EXCEEDED	429	Limite de requisições

#Status de Rastreio

Os possíveis status de um rastreio ao longo do ciclo de entrega.

Status	Label
processing	Pedido Confirmado
separating	Em Separação
shipped	Enviado à Transportadora
in_transit	Em Trânsito
out_for_delivery	Saiu para Entrega
delivered	Entregue
returned	Devolvido

Trenix Logística — API Documentation