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
platformno 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, usevalidateInvoiceIntegration=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'
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:
- Não é fulfillment (logística do marketplace).
- Tem a tag
eligible_for_tags(o marketplace emite a etiqueta). - Status atual é
INVOICED. - 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_LIVRESHOPEEAMAZONMAGALUB2WSHEINVIAVAREJO(Casas Bahia)KABUM(KaBuM!)CARREFOURV2(Carrefour)ALIEXPRESS(AliExpress)TEMU(Temu)CORREIOSGUBEE(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):
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:
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/mergeexplí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.accountIdde uma conta Mercado Livre real do seller, conectada e com a geração de etiquetas ativa. A conta é conferida antes de processar o lote.packageTypescom um único valor:PDFouZPL.- Sem
validateInvoiceIntegration=true. Os pedidos de teste não existem, então essa validação recusaria o lote com422(ORDER_NOT_FOUND). - Webhook do domínio
TAGassinado 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
orderIddo lote precisam conterMOCK. Se um único pedido real entrar no lote, o lote inteiro vai para o fluxo real do Mercado Livre. - Um
orderIdcomMOCKmas semMOCKSUCCESSnemMOCKERROR(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 (
MOCKSUCCESSeMOCKERRORjuntos) não tem resultado garantido. Não o use para validarTAG_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=truepara 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 /mergeexplícito para forçar a geração, em vez de ficar re-chamandoGET /download/merged.
Próximos passos¶
- Faturamento e DANFE — emitir NF antes da etiqueta.
- Receber pedidos — fluxo completo do pedido.