Pré-requisito
Você precisa do shipmentId retornado pela
criação do envio.
Emitir
POST /api/v1/labels/shipments/{shipmentId}/emit
Authorization: Bearer <accessToken>
X-Tenant-Id: <lojaId>
Content-Type: application/json{
"paymentMethod": "wallet"
}Campos:
| Campo | Obrigatório | Uso |
|---|---|---|
paymentMethod | Sim | Use wallet para pagar com saldo. |
pickupRequested | Não | Solicita coleta se o serviço suportar. |
couponCode | Não | Cupom autorizado para a operação. |
invoice | Condicional | Dados solicitados pelo fluxo de emissão. |
Resposta concluída
{
"status": "READY",
"shipmentId": "6a4eaf6d-d962-4b0c-a421-f2d426128e92",
"labelId": "e59a7410-394d-4b22-b79f-299c33038127",
"trackingCode": "AA123456789BR",
"fileUrl": "shipping/loja/labels/referencia-interna",
"priceCents": 1850,
"subtotalCents": 1850,
"discountCents": 0,
"couponCode": null,
"paymentMethod": "wallet",
"transactionId": "21e7e8b1-0d10-4aeb-b1e9-2e69b14df78f",
"chargeAlreadyCaptured": false
}fileUrl é interno. Use labelId no endpoint de download.
Resposta pendente
HTTP 202:
{
"status": "PENDING",
"shipmentId": "6a4eaf6d-d962-4b0c-a421-f2d426128e92",
"providerJobId": "REFERENCIA_DO_PROCESSAMENTO"
}Não repita a emissão. O fluxo que forneceu o shipmentId deve informar como consultar a conclusão assíncrona.
Timeout
Se a conexão cair após o envio da requisição, não é possível concluir que a emissão falhou. Reconcilie o estado pelo fluxo contratado antes de tentar novamente.
Baixar
GET /api/v1/labels/{labelId}/download{
"downloadUrl": "https://endereco-temporario.example/etiqueta.pdf"
}Baixe imediatamente. Não salve a URL temporária, não a exponha em logs e solicite outra quando expirar.