Integrar via API

O que é a integração via API

A API Whitelabel permite que você conecte seu próprio sistema (ERP, plataforma própria, marketplace customizado ou qualquer software server-side) ao Envio Ecom sem depender das integrações prontas (Shopify, Bling, Nuvemshop etc.).

Com ela você pode cotar frete, criar envios, gerar etiquetas em PDF, listar e rastrear pacotes, tudo via endpoints REST com payloads em JSON.

Quando usar

• Você tem um e-commerce próprio (não usa Shopify, Nuvemshop, Yampi, Loja Integrada etc.).
• Você quer integrar um ERP, OMS ou ferramenta interna.
• Você precisa de mais flexibilidade que as integrações prontas oferecem.

Passo 1 — Ativar a integração e gerar o token

1. Faça login na sua conta.
2. Acesse Integrações no menu lateral (URL: /integration/<seu_id>).
3. Clique no card "Integrar via API" (ícone api).
4. Clique no botão "Gerar Token e Ativar Integração".
5. O sistema exibirá:
   • Base URL: a URL base de todas as chamadas.
   • X-Partner-Token: seu token de autenticação exclusivo (copie e guarde em local seguro).

Passo 2 — Autenticação

Toda requisição autenticada deve enviar o header:

X-Partner-Token: SEU_TOKEN_AQUI
Content-Type: application/json

Passo 3 — Fluxo principal (5 passos)

1) Cotação de frete

POST /api/v1/whitelabel/shipping/quote

Envie o CEP de destino e a lista de produtos (peso, dimensões, valor). Retorna as transportadoras disponíveis com preço e prazo.

{
  "postal_code_destination": "01456010",
  "aviso_recebimento": false,
  "include_dropoff_points": true,
  "carriers": ["Ponto Loggi envioEcom", "J&T Express envioEcom"],
  "products": [
    {
      "weight": 0.5,
      "length": 16,
      "height": 5,
      "width": 12,
      "quantity": 1,
      "price": 100.00
    }
  ]
}

Filtro carriers (opcional): passe um array com as transportadoras desejadas para limitar o retorno. Omita para receber todas. Valores aceitos: Ponto Loggi envioEcom, J&T Express envioEcom, Jadlog envioEcom, Correios Sedex, Correios Pac, Correios Mini Envios, BUSLOG envioEcom, Correios Economico envioEcom.

Resposta: array quotes com carrier, price e delivery_time. Guarde o valor de carrier — ele é exigido no passo 2.

2) Criar envio

POST /api/v1/whitelabel/shipping/create

Crie o envio com os dados do destinatário e o serviço escolhido na cotação. O campo shipping_company deve ser exatamente o valor de carrier retornado na cotação.

{
  "shipments": [{
    "orderId": "PED-1234",
    "shipping_company": "Correios Sedex",
    "cep_origem": "74440480",
    "cep_destino": "01456010",
    "freight_cost": "19.85",
    "delivery_time": "3",
    "height": "20", "width": "20",
    "length": "20", "weight": "0.500",
    "cost": "100",
    "name": "João da Silva",
    "document_number": "123.456.789-00",
    "phone_number": "11999999999",
    "email": "joao@email.com",
    "logradouro": "Rua das Flores",
    "number": "123",
    "complemento": "Apto 5",
    "bairro": "Centro",
    "localidade": "São Paulo",
    "uf": "SP",
    "items": [
      {"name": "Camiseta", "quantity": 1, "unit_cost": 59.90},
      {"name": "Bermuda", "quantity": 1, "unit_cost": 40.10}
    ]
  }]
}

Resposta: shipping_id e barcode do envio criado. Guarde o shipping_id para gerar a etiqueta.

3) Gerar etiqueta (PDF)

POST /api/v1/whitelabel/shipments/generate-labels

Envie apenas um dos campos: ids ou barcodes. O retorno é o próprio arquivo PDF.

{ "ids": [123, 456] }
// OU
{ "barcodes": ["AC817953643BR"] }

Envios com status "Cancelado" ou "Aguardando pagamento" serão rejeitados.

4) Listar envios

GET /api/v1/whitelabel/shipments?page=1&limit=50&sort_order=desc

Lista paginada (máximo de 50 por página). Filtros opcionais: barcode, status, delivery_mode, ids[], created_from, created_to, cpf.

5) Rastrear envio

GET /api/v1/whitelabel/shipments/{barcode_ou_id}

Retorna os detalhes do envio e o histórico completo de status (com datas). Aceita ID numérico ou código de barras.

Endpoints adicionais

• Cancelar envio: POST /api/v1/whitelabel/shipments/{id_ou_barcode}/cancel — auto-cancela se < 10 min; senão abre solicitação. Body: { "reason": "..." } (opcional).
• Duplicar envio: GET /shipments/{id}/duplicate-data e POST /shipments/{id}/duplicate.
• Conferência de expedição: POST /api/v1/whitelabel/expedition/scan (bipa etiquetas), POST /expedition/reports/{id}/close, POST /expedition/reports/{id}/labels-pdf, POST /expedition/reports/{id}/summary-pdf.
• Gerenciar token: POST /api/v1/whitelabel/token para gerar/renovar.
• Dados do usuário: GET /api/v1/whitelabel/user/me.

Documentação completa (Swagger UI)

A documentação interativa completa — com todos os endpoints, parâmetros, exemplos e a opção de testar pelo navegador — está disponível no Swagger UI. Acesse o botão "Abrir Swagger UI" na própria tela Integrar via API dentro da sua conta.

O OpenAPI JSON também pode ser baixado e importado no Postman, Insomnia ou qualquer ferramenta compatível com OpenAPI 3.0.

Exemplo rápido com cURL

curl -X POST https://envioecom.com.br/api/v1/whitelabel/shipping/quote \
  -H "X-Partner-Token: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "postal_code_destination": "01456010",
    "products": [{ "weight": 0.5, "length": 16, "height": 5, "width": 12, "quantity": 1, "price": 100.00 }]
  }'

Boas práticas

• Token só no backend. Nunca em código frontend público.
• Use o valor exato de carrier retornado na cotação no campo shipping_company ao criar o envio.
• Guarde shipping_id e barcode retornados ao criar — você precisará deles para etiqueta, cancelamento e rastreio.
• Trate erros 4xx/5xx com retry para falhas transitórias e log estruturado das respostas.
• Ambiente de testes: use uma conta de homologação antes de subir para produção.

Precisa de ajuda?

Se algo não funcionou, abra um chamado pelo nosso suporte enviando: endpoint chamado, payload (sem o token), código HTTP e corpo da resposta. Isso acelera bastante o atendimento.

⚠️ Importante:

A Envio Ecom é uma plataforma de intermediação logística que conecta usuários às transportadoras parceiras para cotação, emissão de etiquetas e gerenciamento de envios.
A execução do transporte, incluindo coleta, movimentação, armazenagem, entrega e devolução das encomendas, é realizada exclusivamente pela transportadora escolhida no momento da contratação do frete.
Dessa forma, a Envio Ecom não possui contato físico com as mercadorias e atua exclusivamente como intermediadora tecnológica, oferecendo ferramentas de gestão, rastreamento e suporte para os envios realizados na plataforma.