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, etc.). O platform no path determina qual transportadora será consultada.

Pré-requisitos¶

Pedido em status INVOICED (NF emitida). Veja Faturamento e DANFE.
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.

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.

Plataformas suportadas (`SupportedPlatform`)¶

MERCADO_LIVRE
SHOPEE
AMAZON
MAGALU
B2W
SHEIN
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
GROUP=$(curl -s -X POST "https://api.gubee.com.br/integration/tags/group/$PLATFORM?packageTypes=$PACKAGES&accountId=$ACCOUNT_ID" \
  -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.
5xx	Transportadora indisponível	Backoff exponencial (até 3 retries).

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.
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¶

Faturamento e DANFE — emitir NF antes da etiqueta.
Receber pedidos — fluxo completo do pedido.

Etiquetas de envio (tags)¶

Pré-requisitos¶

Visão geral do fluxo¶

1. Descobrir pedidos pendentes¶

Scroll (recomendado para alto volume)¶

Paginado (tradicional)¶

Apenas IDs (lightweight)¶

Filtros opcionais¶

2. Criar grupo de etiquetas¶

Query params¶

Response (CreateTagResponseApiDTO)¶

Plataformas suportadas (SupportedPlatform)¶

3. Listar pacotes do grupo¶

Response (List<TagPackageApiDTO>)¶

4. Scroll de grupos¶

Query params¶

Response (ScrollSupport<TagGroupApiDTO>)¶

Detalhes de um grupo específico¶

5. Download de etiquetas¶

Individual (um pacote)¶

Merged (todos pacotes do grupo em um PDF)¶

6. Operações sobre o grupo¶

Forçar merge¶

Desagrupar (ungroup)¶

Fluxo completo end-to-end¶

Tipos de pacote¶

Status de grupo e pacote¶

Grupo (TagGroupApiDTO.status)¶

Pacote (TagPackageApiDTO.status)¶

Tratamento de erros¶

Após gerar etiqueta¶

Padrões de otimização¶

Cache local de PDFs¶

Batch por transportadora¶

Anti-patterns¶

Próximos passos¶

Response (`CreateTagResponseApiDTO`)¶

Plataformas suportadas (`SupportedPlatform`)¶

Response (`List<TagPackageApiDTO>`)¶

Response (`ScrollSupport<TagGroupApiDTO>`)¶

Grupo (`TagGroupApiDTO.status`)¶

Pacote (`TagPackageApiDTO.status`)¶