Pular para conteúdo

Etiquetas de envio (tags)

No Gubee, tag é a etiqueta de envio (em inglês: shipping label) que a transportadora ou marketplace exige anexada ao pacote. Equivale ao conceito de PLP (Pedido de Liberação Postal) dos Correios.

Este documento descreve o fluxo completo: identificar pedidos pendentes, agrupar em lote, gerar etiquetas individuais e merged (PLP consolidada), baixar em PDF e gerenciar o ciclo de vida do grupo.

As etiquetas são geradas por plataforma (Correios, Mercado Livre Envios, Shopee SLS, Casas Bahia, KaBuM!, Carrefour, AliExpress, Temu, etc.). O platform no path determina qual transportadora será consultada.

Pré-requisitos

  • Pedido em status INVOICED (NF emitida). Veja Faturamento e DANFE. Para a API conferir isso (e a integração da NF ao marketplace) antes de gerar, use validateInvoiceIntegration=true.
  • Conta (accountId) da plataforma configurada com credenciais válidas.
  • Tipos de pacote (packageTypes) suportados pela plataforma:
  • SMALL (até 0.6kg ou dimensão mínima)
  • MEDIUM (até 5kg)
  • LARGE (> 5kg ou dimensão grande)

Visão geral do fluxo

1. Descobrir pedidos pendentes
   GET /tags/order/searchByPendingTags/{platform}
        │
        ▼
2. Criar grupo de etiquetas
   POST /tags/group/{platform}?packageTypes=&accountId=
        │  retorna groupId
        ▼
3. (opcional) Listar pacotes do grupo
   GET /tags/package/list/all/{groupId}
        │
        ▼
4. Baixar etiquetas
   ├── individual: GET /tags/package/download/{packageId}?packageType=
   ├── merged:     GET /tags/package/download/merged/{groupId}/{packageType}
        │
        ▼
5. (opcional) Reorganizar
   ├── merge:    POST /tags/group/merge/{groupId}/{packageType}
   └── ungroup:  PUT /tags/group/ungroup/{groupId}

1. Descobrir pedidos pendentes

Antes de gerar etiquetas, identifique quais pedidos precisam de tag. Existem três variantes para busca:

Scroll (recomendado para alto volume)

curl 'https://api.gubee.com.br/integration/tags/order/searchByPendingTags/MERCADO_LIVRE?limit=50&dateFilterType=ORDER_CREATED' \
  -H 'Authorization: Bearer $TOKEN'

Retorna ScrollSupport<OrderTagApiDTO> — paginação via cursor:

{
  "items": [
    {
      "orderId": "MLB1234567890",
      "platform": "MERCADO_LIVRE",
      "accountId": "acct-seller-a",
      "shipmentCode": "ML-shipment-1",
      "shippingMethod": "Mercado Envios Standard",
      "recipient": {
        "name": "Maria Silva",
        "address": { "...": "..." }
      },
      "items": [
        { "skuId": "sku-uuid-1001-blk", "qty": 1, "name": "Galaxy S24" }
      ]
    }
  ],
  "scrollId": "eyJjdXJzb3IiOjUwfQ==",
  "hasMore": true,
  "total": 187
}

Para a próxima página, passe scrollId:

curl 'https://api.gubee.com.br/integration/tags/order/searchByPendingTags/MERCADO_LIVRE?limit=50&scrollId=eyJjdXJzb3IiOjUwfQ==' \
  -H 'Authorization: Bearer $TOKEN'

Paginado (tradicional)

curl 'https://api.gubee.com.br/integration/tags/order/searchByPendingTags/page/MERCADO_LIVRE?page=0&size=50' \
  -H 'Authorization: Bearer $TOKEN'

Retorna PagedModel<OrderTagApiDTO> (HATEOAS com first/next/last).

Apenas IDs (lightweight)

Para alto volume, use a variante que retorna só os orderId:

curl 'https://api.gubee.com.br/integration/tags/order/searchByPendingTags/ids/MERCADO_LIVRE' \
  -H 'Authorization: Bearer $TOKEN'
["MLB1234567890", "MLB1234567891", "MLB1234567892"]

Filtros opcionais

Parâmetro Tipo Descrição
startDt ISO-8601 Início do período (por dateFilterType).
endDt ISO-8601 Fim do período.
limit int Default 50.
scrollId string Cursor da próxima página (apenas scroll).
searchText string Busca textual livre (recipient, orderId, etc.).
accountIds List Filtra por contas específicas (multi-conta por seller).
accountId string Variante singular (ids endpoint).
dateFilterType enum ORDER_CREATED (default), ORDER_PAID, ORDER_INVOICED.

2. Criar grupo de etiquetas

POST /integration/tags/group/{platform} cria um lote de tags para uma lista de orderId. A plataforma gera as etiquetas e as agrupa sob um groupId.

curl -X POST 'https://api.gubee.com.br/integration/tags/group/MERCADO_LIVRE?packageTypes=SMALL,MEDIUM&accountId=acct-seller-a' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    "MLB1234567890",
    "MLB1234567891",
    "MLB1234567892",
    "MLB1234567893",
    "MLB1234567894"
  ]'

Query params

Parâmetro Tipo Obrigatório Descrição
packageTypes List<String> sim Tipos de pacote aceitos: SMALL, MEDIUM, LARGE.
accountId string sim (multi-conta) Conta específica dentro do seller.
validateInvoiceIntegration boolean não (default false) Com true, só gera se todos os pedidos estiverem faturados e com a NF integrada ao marketplace. Veja Validar faturamento e integração da NF.

Response (CreateTagResponseApiDTO)

{
  "groupId": "tag-group-uuid-abc123",
  "platform": "MERCADO_LIVRE",
  "accountId": "acct-seller-a",
  "packageCount": 5,
  "createdAt": "2026-07-07T10:30:00Z",
  "status": "GENERATED"
}

Guarde o groupId — todas as operações subsequentes o usam.

Validar faturamento e integração da NF

Por padrão, o POST /group/{platform} envia o lote para a transportadora sem conferir o status dos pedidos. Se você quer a mesma garantia da tela de etiquetas do painel Gubee, envie validateInvoiceIntegration=true:

curl -X POST 'https://api.gubee.com.br/integration/tags/group/MERCADO_LIVRE?packageTypes=SMALL&accountId=acct-seller-a&validateInvoiceIntegration=true' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '["MLB1234567890", "MLB1234567891"]'

Com o parâmetro, cada pedido do lote precisa passar em todas as regras abaixo, nesta ordem:

  1. Não é fulfillment (logística do marketplace).
  2. Tem a tag eligible_for_tags (o marketplace emite a etiqueta).
  3. Status atual é INVOICED.
  4. A NF foi integrada ao marketplace (plataformIntegrationStatus = INTEGRATED).

O lote é tudo ou nada: se um pedido falhar, nenhuma etiqueta é gerada e a resposta é 422 com a lista dos pedidos recusados em blockedOrders:

{
  "status": 422,
  "message": "error.tagOrdersNotEligible",
  "blockedOrders": [
    { "orderId": "MLB1234567891", "reason": "INVOICED_ERROR", "message": "chave da NF invalida" }
  ]
}
reason Significado O que fazer
ORDER_NOT_FOUND Pedido não encontrado para o seller nesta plataforma. Confira o orderId e o platform do path.
FULFILLMENT Pedido com logística do marketplace — não gera etiqueta própria. Retire do lote.
MISSING_TAG Pedido sem eligible_for_tags (logística própria). Retire do lote.
NOT_INVOICED Status atual não é INVOICED (message traz o status atual). Fature o pedido antes.
INVOICED_NOT_INTEGRATED Faturado, mas a NF ainda não foi enviada ao marketplace. Aguarde a integração e reenvie.
INVOICED_PROCESSING NF sendo integrada (RUNNING / IN_VALIDATION). Aguarde alguns minutos e reenvie.
INVOICED_ERROR O marketplace recusou a NF (message traz o erro). Corrija a NF e reenvie.

Para gerar o restante, retire do lote os pedidos de blockedOrders e reenvie. Sem o parâmetro (ou com false), o comportamento é o de sempre.

Plataformas suportadas (SupportedPlatform)

  • MERCADO_LIVRE
  • SHOPEE
  • AMAZON
  • MAGALU
  • B2W
  • SHEIN
  • VIAVAREJO (Casas Bahia)
  • KABUM (KaBuM!)
  • CARREFOURV2 (Carrefour)
  • ALIEXPRESS (AliExpress)
  • TEMU (Temu)
  • CORREIOS
  • GUBEE (próprio)

A lista completa é definida no enum SupportedPlatform. Consulte o suporte para confirmar disponibilidade.

3. Listar pacotes do grupo

curl 'https://api.gubee.com.br/integration/tags/package/list/all/tag-group-uuid-abc123' \
  -H 'Authorization: Bearer $TOKEN'

Response (List<TagPackageApiDTO>)

[
  {
    "packageId": "pkg-uuid-001",
    "groupId": "tag-group-uuid-abc123",
    "orderId": "MLB1234567890",
    "packageType": "SMALL",
    "status": "READY",
    "trackingCode": "ON123456789BR",
    "carrier": "Correios",
    "shippingMethod": "SEDEX",
    "downloadUrl": "https://storage.gubee.com.br/tags/pkg-uuid-001.pdf"
  },
  {
    "packageId": "pkg-uuid-002",
    "groupId": "tag-group-uuid-abc123",
    "orderId": "MLB1234567891",
    "packageType": "MEDIUM",
    "status": "READY",
    "trackingCode": "ON123456790BR",
    "downloadUrl": "https://storage.gubee.com.br/tags/pkg-uuid-002.pdf"
  }
]

4. Scroll de grupos

Para listar todos os grupos já criados de uma plataforma:

curl 'https://api.gubee.com.br/integration/tags/group/list/all/MERCADO_LIVRE?limit=50' \
  -H 'Authorization: Bearer $TOKEN'

Query params

Parâmetro Tipo Default Descrição
limit int 50 Tamanho da página.
scrollId string — Cursor para próxima página.
search string — Busca livre (orderId, groupId, etc).

Response (ScrollSupport<TagGroupApiDTO>)

{
  "items": [
    {
      "groupId": "tag-group-uuid-abc123",
      "platform": "MERCADO_LIVRE",
      "accountId": "acct-seller-a",
      "packageCount": 5,
      "createdAt": "2026-07-07T10:30:00Z",
      "status": "GENERATED"
    }
  ],
  "scrollId": "eyJjdXJzb3IiOjUwfQ==",
  "hasMore": false,
  "total": 1
}

Detalhes de um grupo específico

curl 'https://api.gubee.com.br/integration/tags/tag-group-uuid-abc123' \
  -H 'Authorization: Bearer $TOKEN'

Retorna TagGroupApiDTO.

5. Download de etiquetas

Individual (um pacote)

curl 'https://api.gubee.com.br/integration/tags/package/download/pkg-uuid-001?packageType=SMALL' \
  -H 'Authorization: Bearer $TOKEN'

Response (text/plain):

https://storage.gubee.com.br/tags/pkg-uuid-001.pdf

URL pré-assinada com expiração de ~1h. Use -o para salvar direto em arquivo:

curl -o etiqueta-001.pdf \
  "$(curl -s 'https://api.gubee.com.br/integration/tags/package/download/pkg-uuid-001?packageType=SMALL' \
    -H 'Authorization: Bearer $TOKEN')" \
  -H 'Authorization: Bearer $TOKEN'

Merged (todos pacotes do grupo em um PDF)

curl 'https://api.gubee.com.br/integration/tags/package/download/merged/tag-group-uuid-abc123/SMALL' \
  -H 'Authorization: Bearer $TOKEN'

Response (text/plain) — URL para o PDF consolidado:

https://storage.gubee.com.br/tags/merged/tag-group-uuid-abc123_SMALL.pdf

Atenção: o merge é assíncrono. Se chamado imediatamente após a criação do grupo, pode retornar 404. Aguarde alguns segundos (ou use o POST /group/merge explícito abaixo) e refaça.

6. Operações sobre o grupo

Forçar merge

Dispara explicitamente a consolidação de todos os pacotes em um único PDF:

curl -X POST 'https://api.gubee.com.br/integration/tags/group/merge/tag-group-uuid-abc123/SMALL' \
  -H 'Authorization: Bearer $TOKEN'

Retorna 200 sem body. Após o merge concluir (1-5s), o endpoint de download merged retorna a URL.

Desagrupar (ungroup)

Remove pedidos do grupo (mantém as etiquetas geradas, mas dissocia do grupo lógico):

# Desagrupar todo o grupo
curl -X PUT 'https://api.gubee.com.br/integration/tags/group/ungroup/tag-group-uuid-abc123' \
  -H 'Authorization: Bearer $TOKEN'

# Desagrupar pedidos específicos
curl -X PUT 'https://api.gubee.com.br/integration/tags/group/ungroup/tag-group-uuid-abc123' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '["MLB1234567890", "MLB1234567891"]'

Response (UngroupTagsResponseApiDTO):

{
  "groupId": "tag-group-uuid-abc123",
  "removedOrderIds": ["MLB1234567890", "MLB1234567891"],
  "status": "UNGROUPED"
}

Fluxo completo end-to-end

Script típico de um worker de expedição:

#!/bin/bash
TOKEN="..."
PLATFORM="MERCADO_LIVRE"
ACCOUNT_ID="acct-seller-a"
PACKAGES="SMALL,MEDIUM"

# 1. Pega IDs pendentes
PENDING=$(curl -s "https://api.gubee.com.br/integration/tags/order/searchByPendingTags/ids/$PLATFORM?accountId=$ACCOUNT_ID" \
  -H "Authorization: Bearer $TOKEN")

if [ "$PENDING" == "[]" ]; then
  echo "Nenhum pedido pendente"
  exit 0
fi

# 2. Cria grupo (validateInvoiceIntegration=true: 422 se algum pedido não tiver a NF integrada)
GROUP=$(curl -s -X POST "https://api.gubee.com.br/integration/tags/group/$PLATFORM?packageTypes=$PACKAGES&accountId=$ACCOUNT_ID&validateInvoiceIntegration=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$PENDING")

GROUP_ID=$(echo "$GROUP" | jq -r .groupId)
echo "Grupo criado: $GROUP_ID"

# 3. Aguarda processamento (worker gera etiqueta em background)
sleep 5

# 4. Força merge e baixa PDF consolidado
curl -s -X POST "https://api.gubee.com.br/integration/tags/group/merge/$GROUP_ID/SMALL" \
  -H "Authorization: Bearer $TOKEN"

sleep 3

PDF_URL=$(curl -s "https://api.gubee.com.br/integration/tags/package/download/merged/$GROUP_ID/SMALL" \
  -H "Authorization: Bearer $TOKEN")

# 5. Baixa o PDF
curl -o "expedicao-$(date +%Y%m%d).pdf" "$PDF_URL"
echo "PDF salvo."

Tipos de pacote

Tipo Peso máximo Dimensões típicas Uso
SMALL até 0.6kg 16x11x5cm até 30x15x10cm Celulares, acessórios pequenos.
MEDIUM até 5kg 30x20x10cm até 50x30x20cm Eletrônicos médios, calçados.
LARGE > 5kg dimensões acima de MEDIUM Eletrodomésticos, móveis.

A escolha do tipo depende da plataforma. Algumas plataformas (Correios) usam calculação automática baseada em peso e dimensão; outras (Mercado Livre) têm faixas pré-definidas.

Status de grupo e pacote

Grupo (TagGroupApiDTO.status)

Status Significado
GENERATING Etiquetas em geração (ainda não prontas).
GENERATED Prontas para download.
MERGED PDF consolidado disponível.
UNGROUPED Pedido(s) removido(s) do grupo.
EXPIRED URLs de download expiraram (gerar de novo).

Pacote (TagPackageApiDTO.status)

Status Significado
PENDING Aguardando geração.
READY Etiqueta pronta, downloadUrl disponível.
FAILED Falha na geração (transportadora rejeitou, payload inválido).
EXPIRED URL de download expirou.

Tratamento de erros

Status Causa Ação
400 packageTypes inválido ou ausente Verifique os tipos aceitos pela plataforma.
403 accountId não pertence ao seller logado Use a conta correta.
404 Pedido não encontrado, não INVOICED, ou sem shipping Verifique status do pedido via GET /orders/{id}.
404 Grupo/pacote inexistente Confirme o ID via listagem.
409 Pedido já pertence a outro grupo ativo Ungroup o grupo anterior ou aguarde expiração.
422 Plataforma não suporta o tipo de pacote solicitado Refaça com tipo suportado.
422 Com validateInvoiceIntegration=true: pedido não faturado ou NF não integrada (blockedOrders) Veja os motivos, ajuste o lote e reenvie.
5xx Transportadora indisponível Backoff exponencial (até 3 retries).

Testar o tratamento de erros (pedidos de teste)

Para o Mercado Livre existe um fluxo de teste com resultado fixo. Ele serve para validar as rotinas da sua integração antes de usar pedidos reais: receber a notificação, baixar a etiqueta pronta e tratar a etiqueta recusada. Não é preciso criar pedido nenhum. O resultado depende só do texto do orderId enviado no lote.

orderId contém Resultado simulado Webhook esperado
MOCKSUCCESS Etiqueta gerada com um arquivo de exemplo (PDF ou ZPL, conforme packageTypes). TAG_COMPLETE
MOCKERROR Etiqueta recusada com o erro tags.error.initdownload. TAG_ERROR

O resultado é assíncrono: escute os webhooks de etiqueta

Assim como no fluxo real, o POST /integration/tags/group/{platform} só aceita o lote e devolve o groupId. A etiqueta (ou o erro) chega alguns segundos depois. O sinal de que o processamento acabou é o webhook do domínio TAG (TAG_COMPLETE, TAG_PARTIALLY_COMPLETE ou TAG_ERROR). Veja Eventos de Webhook. Use este fluxo justamente para provar que a sua integração reage à notificação, sem depender da resposta do POST nem de polling.

Pré-requisitos do teste

  • platform = MERCADOLIVRE. O fluxo de teste só existe para o Mercado Livre.
  • accountId de uma conta Mercado Livre real do seller, conectada e com a geração de etiquetas ativa. A conta é conferida antes de processar o lote.
  • packageTypes com um único valor: PDF ou ZPL.
  • Sem validateInvoiceIntegration=true. Os pedidos de teste não existem, então essa validação recusaria o lote com 422 (ORDER_NOT_FOUND).
  • Webhook do domínio TAG assinado para o seller.

Exemplo: etiqueta gerada

curl -X POST 'https://api.gubee.com.br/integration/tags/group/MERCADOLIVRE?packageTypes=PDF&accountId=acct-seller-a' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '["MOCKSUCCESS-001", "MOCKSUCCESS-002"]'

Ao receber o webhook TAG_COMPLETE com itemId igual ao groupId, siga o fluxo normal: liste os pacotes e baixe a etiqueta.

Exemplo: etiqueta recusada

curl -X POST 'https://api.gubee.com.br/integration/tags/group/MERCADOLIVRE?packageTypes=PDF&accountId=acct-seller-a' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '["MOCKERROR-001"]'

O webhook TAG_ERROR chega para o groupId. Ao consultar o grupo e os pacotes, o pedido aparece com o erro tags.error.initdownload. Use esse retorno para testar a sua rotina de falha: avisar o operador, marcar o pedido para revisão e não recriar o grupo inteiro automaticamente.

Cuidados

  • Todos os orderId do lote precisam conter MOCK. Se um único pedido real entrar no lote, o lote inteiro vai para o fluxo real do Mercado Livre.
  • Um orderId com MOCK mas sem MOCKSUCCESS nem MOCKERROR (por exemplo, MOCK-001) não gera resultado nenhum: o grupo fica em processamento e o webhook não chega.
  • Teste sucesso e erro em grupos separados. O lote misto (MOCKSUCCESS e MOCKERROR juntos) não tem resultado garantido. Não o use para validar TAG_PARTIALLY_COMPLETE.
  • O grupo de teste é criado de verdade na conta do seller e aparece na listagem de grupos e no painel. O arquivo da etiqueta é um exemplo: não use para despachar pedido.

Após gerar etiqueta

Quando a etiqueta está pronta, despache o pedido:

curl -X PUT 'https://api.gubee.com.br/integration/orders/shipped/MLB1234567890' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "SHIPPED",
    "transport": {
      "name": "Correios",
      "trackingCode": "ON123456789BR",
      "method": "SEDEX",
      "type": "CARRIER"
    },
    "items": [{ "skuId": "sku-uuid-1001-blk", "qty": 1 }],
    "estimatedDeliveryDt": "2026-07-12T18:00:00"
  }'

Veja Receber pedidos para o lifecycle completo.

Padrões de otimização

Cache local de PDFs

Após o primeiro download, salve o PDF localmente. URLs do Gubee expiram em ~1h; evite re-pegar a URL dentro desse período.

def download_tag(package_id):
    cache_path = f"/var/tags/{package_id}.pdf"
    if os.path.exists(cache_path):
        return cache_path

    url = api.get_tag_url(package_id)
    download(url, cache_path)
    return cache_path

Batch por transportadora

Agrupe pedidos da mesma transportadora em grupos distintos para evitar conflito de packageTypes. Não misture SMALL e LARGE no mesmo grupo — isso dificulta a geração do merged PDF.

Anti-patterns

  • Gerar etiqueta antes de faturar: a maioria das plataformas exige NF anexada antes de gerar etiqueta. Use validateInvoiceIntegration=true para a API recusar o lote em vez de mandar à transportadora.
  • Re-gerar etiqueta sem ungroup: gera 409 se o pedido ainda está em grupo ativo.
  • Polling agressivo do merged PDF: use o POST /merge explícito para forçar a geração, em vez de ficar re-chamando GET /download/merged.

Próximos passos