Criar envio

Crie o envio depois de selecionar uma opção de cotação. A resposta devolve o shipmentId usado para emitir a etiqueta, consultar o DACE e acompanhar o rastreamento.

POST /api/v1/shipments
Authorization: Bearer <accessToken>
X-Tenant-Id: <lojas[].id>
Content-Type: application/json

1. Use a opção escolhida na cotação

Da mesma opção em shippingOptions, preserve exatamente:

• quoteId;
• carrierId;
• serviceLevelId.

Use a cotação antes de expiresAt. O pacote e a rota enviados na criação devem ser os mesmos que foram cotados.

2. Monte os endereços do envio

originAddress recebe os dados do remetente. destAddress recebe os dados do destinatário.

Se você usou os endpoints de remetente e destinatário:

• copie para originAddress os campos de endereço retornados por GET /api/v1/addresses;
• em destAddress, use name, cpfCnpj, phone e email do destinatário e complete os demais campos com o objeto address retornado por GET /api/v1/recipients.

Não envie id, lojaId, addressId, addressType, datas ou campos de paginação dentro dos endereços do envio.

3. Envie a criação

Exemplo de uma caixa nacional com NF-e:

{
  "externalRef": "PEDIDO-1001",
  "quoteId": "64b232e7-8f9c-4d65-bb1d-95bf5c21ea46",
  "carrierId": "aaf3b0d6-bf2a-4af0-bb97-bd056a749ad1",
  "serviceLevelId": "22222222-2222-4222-8222-222222222222",
  "originAddress": {
    "name": "Matriz São Paulo",
    "personName": "João Silva",
    "phone": "11999999999",
    "email": "expedicao@empresa.com.br",
    "company": "Loja Exemplo Ltda.",
    "ieNumber": "110042490114",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Conjunto 101",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zip": "01310100",
    "cpfCnpj": "11222333000181",
    "country": "BR"
  },
  "destAddress": {
    "name": "Maria Oliveira",
    "personName": "Maria Oliveira",
    "phone": "21999999999",
    "email": "maria@example.com",
    "street": "Rua do Mercado",
    "number": "45",
    "complement": "Apto 302",
    "district": "Centro",
    "city": "Rio de Janeiro",
    "state": "RJ",
    "zip": "20040020",
    "cpfCnpj": "52998224725",
    "country": "BR"
  },
  "parcel": {
    "format": "2",
    "weightKg": 1.5,
    "lengthCm": 30,
    "widthCm": 20,
    "heightCm": 10,
    "declaredValueCents": 8990,
    "productValueCents": 8990,
    "quantity": 1,
    "hasPackaging": true,
    "contentDescription": "Vestuário",
    "products": [
      {
        "content": "Camiseta de algodão",
        "quantity": 1,
        "valueCents": 8990,
        "ncm": "61091000"
      }
    ]
  },
  "invoice": {
    "type": "NFE",
    "numero": "12345",
    "serie": "1",
    "valor": 89.9,
    "chaveNFe": "35260811222333000181550010000123451000123456",
    "dataEmissao": "2026-08-05"
  }
}

Exemplo com cURL:

curl -X POST "$API_URL/api/v1/shipments" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Tenant-Id: $LOJA_ID" \
  -H "Content-Type: application/json" \
  --data @envio.json

4. Guarde o shipmentId

Resposta 201:

{
  "shipment": {
    "id": "6a4eaf6d-d962-4b0c-a421-f2d426128e92",
    "status": "created"
  },
  "shipmentId": "6a4eaf6d-d962-4b0c-a421-f2d426128e92",
  "status": "created"
}

Persista shipmentId. Ele identifica o envio nas etapas seguintes.

Campos principais

Formatos do pacote

weightKg é sempre obrigatório. Use quilogramas para peso, centímetros para dimensões e centavos para os campos terminados em Cents.

Em endereços brasileiros, envie CEP com oito dígitos e CPF/CNPJ do remetente e do destinatário. Em rotas internacionais, use o código postal do país e não informe cpfCnpj quando esse documento brasileiro não existir.

Documento fiscal

Para uma NF-e existente, use invoice.type: "NFE" e envie a chave de acesso de 44 dígitos em chaveNFe.

Para declaração de conteúdo/DC-e, use invoice.type: "DCE", informe o valor e envie em parcel.products a descrição, quantidade e valor dos itens. A emissão aplicará as regras fiscais da transportadora selecionada.

Validação da cotação

A criação só é aceita quando a cotação:

• pertence à loja de X-Tenant-Id;
• ainda está dentro de expiresAt;
• corresponde ao carrierId e ao serviceLevelId enviados;
• possui a mesma origem, destino, peso, dimensões, formato, valor declarado, volumes e serviços adicionais do envio.

Se algum desses dados mudar, faça uma nova cotação e use o novo quoteId.

Emita a etiqueta →