Foreign Trade Shipment

O campo foreign_trade_shipment representa o embarque de um processo de exportação ou importação. Ele consolida informações como transporte internacional (marítimo, aéreo ou rodoviário), containers, faturas comerciais, documentos aduaneiros e legs rodoviários nacionais.

Este bloco não possui endpoint próprio — ele deve ser incluído no corpo da requisição durante a criação ou atualização de processos via os endpoints de /processes.

Os exemplos apresentados nesta página são simplificados e não abrangem todos os campos disponíveis no foreign_trade_shipment e seus subcampos. Para visualizar a estrutura completa, consulte a API Docs da Flowls.

Campos com IDs obrigatórios

Alguns campos do foreign_trade_shipment exigem valores já cadastrados na plataforma Flowls. Esses IDs não podem ser criados via API e devem ser obtidos previamente com a equipe de integração.

Campo	Descrição	Fonte/Consulta
`sealine_id`	Armador (companhia marítima)	Fornecido pela Flowls
`loading_port_id`	Porto de embarque	Fornecido pela Flowls
`discharge_port_id`	Porto de descarga	Fornecido pela Flowls
`airport_id`	Aeroporto	Fornecido pela Flowls
`vessel_id`	Navio	`GET /api/vessel`
`route_id`	Rota rodoviária nacional	`GET /api/routes`

Caso você não possua esses IDs, verifique o material enviado pela equipe de integrações da Flowls ou acesse https://www.flowls.app/integrations/docs.

Estrutura geral

A estrutura do foreign_trade_shipment é composta por blocos opcionais e customizáveis, conforme o tipo de operação e a fase logística.
Abaixo, um exemplo simplificado de uso com modal marítimo, fatura, item e container:

"foreign_trade_shipment": {
  "maritime_transport_shipment": {
    "bl": "MEDUGB760924",
    "booking": "BOOK123",
    "loading_port_id": 1,
    "discharge_port_id": 2,
    "voyage_number": "VYG7890",
    "type": "FCL"
  },
  "items": [
    {
      "order_reference_code": "REF1234",
      "line_reference": "1",
      "quantity": 10
    }
  ],
  "invoices": [
    {
      "number": "INV-2025-001",
      "currency_code": "USD",
      "emitted_at": "2025-05-10T00:00:00Z",
      "incoterm": "FOB",
      "items": [
        {
          "product_description": "Produto A",
          "product_sku": "SKU-001",
          "quantity": 5,
          "unitary_amount": "12.34"
        }
      ]
    }
  ],
  "transportables": [
    {
      "container": {
        "code": "CONT001",
        "type": "DRY",
        "size_foot_type": "HC_40",
        "gross_weight_kg": 1000,
        "tare_weight_kg": 2300
      }
    }
  ]
}

Blocos Principais

`Modal de transporte (obrigatório)`

É obrigatório informar um único modal por processo. Os campos aceitos são:

maritime_transport_shipment
air_transport_shipment
road_transport_shipment

No exemplo abaixo, utilizamos o modal marítimo com os campos principais preenchidos:

"maritime_transport_shipment": {
  "bl": "MEDUGB760924",
  "booking": "BOOK123",
  "loading_port_id": 1,
  "discharge_port_id": 2,
  "voyage_number": "VYG7890",
  "type": "FCL",
  "sealine_id": 4,
  "vessel_id": 12
}

Os campos loading_port_id e discharge_port_id representam os portos de embarque e descarga e devem ser preenchidos com IDs previamente fornecidos pela equipe de integração da Flowls. Esses valores são fixos e não podem ser criados via API.

O campo vessel_id deve ser preenchido com o ID de um navio já cadastrado. Para consultar os navios disponíveis, utilize o endpoint GET /api/vessel.

Exemplo da Requisição:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY" \
  https://api.flowls.app/api/vessel

Resposta esperada:

{
  "data": [
    {
      "id": 1,
      "name": "WILFRED SYKES",
      "country": null,
      "callsign": null,
      "dimensions": null,
      "is_active_mercante": false,
      "external_data_updated_at": null,
      "imo_number": "5389554",
      "last_position_update": null,
      "mmsi_number": "367082220",
      "ship_sub_type": null,
      "ship_type": null
    }
  ]
}

`items`

Define os itens de pedidos que serão embarcados.
Você deve informar:

order_reference_code: código do pedido original
line_reference: referência da linha do item (usada na criação do pedido)
quantity: quantidade embarcada

"items": [
  {
    "order_reference_code": "REF1234",
    "line_reference": "1",
    "quantity": 10
  }
]

`invoices`

Bloco usado para declarar faturas comerciais associadas ao embarque.

"invoices": [
  {
    "number": "INV-2025-001",
    "currency_code": "USD",
    "emitted_at": "2025-05-10T00:00:00Z",
    "incoterm": "FOB",
    "items": [
      {
        "product_description": "Produto A",
        "product_sku": "SKU-001",
        "quantity": 5,
        "unitary_amount": "12.34"
      }
    ]
  }
]

`transportables`

Lista os containers ou volumes embarcados:

"transportables": [
  {
    "container": {
      "code": "CONT001",
      "type": "DRY",
      "size_foot_type": "HC_40",
      "gross_weight_kg": 1000,
      "tare_weight_kg": 2300
    }
  }
]

`national_road_transports`

Define legs rodoviários nacionais envolvidos antes ou depois do transporte internacional. Cada leg deve referenciar uma route_id previamente cadastrada na plataforma Flowls.

O campo route_id deve ser preenchido com um valor existente na plataforma. Para consultar as rotas disponíveis, utilize o endpoint GET /api/routes.

Exemplo de preenchimento:

"national_road_transports": [
  {
    "route_id": 1,
    "leg_slug": "Porto > Armazém",
    "collection_scheduled_at": "2025-05-01T12:00:00Z",
    "delivery_planned_at": "2025-05-03T10:00:00Z"
  }
]

Exemplo de requisição para consultar rotas existentes:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY" \
  https://api.flowls.app/api/routes

`parcel_shipments`

Usado em embarques com transportadora/courier:

"parcel_shipments": [
  {
    "slug": "CourierWidget",
    "tracking_number": "BR123456789"
  }
]

`Blocos de documentos aduaneiros`

Você pode informar documentos de importação ligados ao embarque por meio dos blocos:

shipment_duimps
shipment_import_declarations
shipment_import_licenses

Esses campos são objetos que contêm identificadores como número da DI, DUIMP ou licença. O único campo obrigatório no envio é o number, que deve conter o número do documento. As demais informações — como data de aprovação, status e observações — são automaticamente preenchidas pela plataforma Flowls com base no número enviado, por meio do nosso sistema de tracking automático.

{
  "shipment_duimps": [
    {
      "duimp": {
        "number": "21BR00000012345"
      }
    }
  ],
  "shipment_import_declarations": [
    {
      "import_declaration": {
        "number": "2212614470"
      }
    }
  ],
  "shipment_import_licenses": [
    {
      "import_license": {
        "number": "LIC-987654"
      }
    }
  ]
}

Próximos passos

Extra Fields — campos personalizados que complementam os dados do embarque

Foreign Trade Shipment

Campos com IDs obrigatórios​

Estrutura geral​

Blocos Principais​

Modal de transporte (obrigatório)​

items​

invoices​

transportables​

national_road_transports​

parcel_shipments​

Blocos de documentos aduaneiros​

Próximos passos​