O que vem no JSON

A forma

A carga está dentro do contêiner

Esta é a diferença que mais economiza código do seu lado. Para saber o que vem no FCIU6596670, você lê o contêiner e lê o que está dentro. Não existe lista de vínculos para cruzar.

{
  "container_number": "FCIU6596670",
  "seal_numbers": ["UL-2443323"],
  "container_type": "20GP",
  "size_in_feet": 20,
  "package_count": 18,
  "gross_weight":                { "value": 20291.664, "unit": "KG" },
  "tare_weight_empty_container": { "value": 2100,      "unit": "KG" },
  "cargo_weight_excluding_tare": { "value": 18191.664, "unit": "KG" },
  "measurement_volume":          { "value": 25,        "unit": "M3" },
  "cargo": [ ... ]
}

cargo_weight_excluding_tare é o bruto menos a tara, calculado aqui para você não refazer. Quando o documento não declara tara ele vem null, e nunca o bruto: armadores discordam sobre o que o peso bruto de um contêiner inclui, e escolher uma interpretação por você gravaria no seu sistema uma carga mais pesada do que é.

Quando a mesma carga está em dois contêineres

Acontece com frequência: 36 totes repartidos em 18 e 18. Uma carga e dois contêineres não cabem numa árvore sem repetir alguma coisa, então a carga aparece dentro dos dois — e três campos dizem isso em voz alta, para ninguém somar errado.

{
  "cargo_id": 1,
  "description": "EVOTHERM P25, TE, 2100 LB, HAZARDOUS CHEMICALS...",
  "ncm_codes": [{ "code": "3824", "digit_count": 4 }],

  "package_count_in_this_container": 18,
  "gross_weight_in_this_container": { "value": 18191.664, "unit": "KG" },

  "also_loaded_in_containers": ["HLBU3614917"],
  "total_in_all_containers": {
    "package_count": 36,
    "gross_weight": { "value": 36383.328, "unit": "KG" }
  }
}

Quando a carga cabe num contêiner só, also_loaded_in_containers vem vazio e a parte é igual ao total.

Carga que o documento não repartiu

Um BL com três contêineres e três cargas frequentemente não diz qual carga está em qual. Nesse caso a plataforma não distribui por conta própria: essas cargas saem em cargo_without_container, inteiras, e quem responde pela carga decide na conferência.

Distribuir por plausibilidade produziria um vínculo com cara de dado lido, e esse vínculo vira declaração aduaneira com o NCM no contêiner errado.

Carga perigosa

Quando o documento declara carga perigosa, cada carga traz a lista dangerous_goods, com uma entrada por declaração impressa: número ONU, nome, classe, grupo de embalagem e o que mais o emissor escreveu junto. Carga comum vem com a lista vazia.

{
  "cargo_id": 2,
  "description": "ALUMINIUM PROFILES AND ACCESSORIES",
  "hazardous_material_marked": true,
  "dangerous_goods": [
    {
      "un_number": "1219",
      "un_number_as_printed": "UN1219",
      "proper_shipping_name": "ISOPROPANOL",
      "technical_name": "ISOPROPANOL SOLUTION",
      "hazard_class": "3",
      "subsidiary_hazard_classes": [],
      "packing_group": "II",
      "flash_point": { "value": 12.0, "unit": "CEL", "method": "closed_cup", "as_printed": "12.0 C C.C." },
      "shipped_as_limited_quantity": true,
      "marine_pollutant": null,
      "ems": null,
      "package_count": 4,
      "package_type": "BOX",
      "emergency_contact": "+4917843374341"
    },
    { "un_number": "1133", "proper_shipping_name": "ADHESIVES", "hazard_class": "3", "packing_group": "II", ... }
  ]
}

hazardous_material_marked é a coluna HM do formulário: true quando marcada, false quando existe e está em branco, null quando o formulário não tem a coluna.

Tudo separado, até o CEP

Seu sistema raramente quer o texto como está no papel. Às vezes quer só o CNPJ, às vezes só o CEP. Cada parte vem quebrada até o último pedaço:

{
  "name": "INGEVITY QUIMICA LTD",
  "tax_ids": [
    { "type": "cnpj", "label": "CNPJ",
      "number": "30381107001160", "as_printed": "30.381.107/0011-60" }
  ],
  "address": {
    "street": "AV CONSTANTE PAVAN",
    "street_number": "4327",
    "complement": null,
    "district": "BETEL",
    "city": "PAULINIA",
    "state": "SP",
    "postal_code": { "as_printed": "13148-198", "digits_only": "13148198" },
    "country": "BRAZIL",
    "country_code": "BR"
  },
  "contact": { "phone": "+55 19 3514-1600", "email": null, "fax": null, "attention_to": null }
}

tax_ids é uma lista porque o mesmo bloco pode trazer CNPJ e inscrição estadual, ou um documento estrangeiro. number é o valor limpo, para comparar e gravar; as_printed é o que estava escrito, para conferir sem abrir o PDF.

Quantidade sempre vem com unidade

Peso, cubagem e medidas nunca vêm como número solto. Vêm como { value, unit }, com a unidade que o documento usou, sem conversão. Um BL em libras chega em libras: converter por você seria transformar em silêncio um número que vira declaração aduaneira.

"gross_weight":       { "value": 18450.5, "unit": "KGS" },
"measurement_volume": { "value": 58.2,    "unit": "CBM" }

Como a leitura foi feita

Página de origem de cada campo, endereço como estava impresso, base de cada vínculo, correções automáticas e o texto que não coube em campo nenhum: nada disso é o BL, então nada disso está dentro de data. Fica em extraction, e vem completo só quando pedido.

"extraction": {
  "contradictions_found": 0,
  "unmapped_text_blocks": 2,
  "auto_corrections_applied": 0,
  "url": "/v1/ebl/documents/{job_id}?include=extraction"
}

O resumo aparece sempre, mesmo sem pedir. Um documento com texto que não coube em campo nenhum precisa avisar que isso existe: a garantia de que nada se perde não pode depender de você adivinhar um parâmetro.

GET /v1/ebl/documents/{job_id}?include=extraction

Campo ausente e campo nulo

null significa que o documento não trazia aquilo. Não é zero, não é vazio, e nunca é um valor inventado para tapar a lacuna. Se o BL não declara o IMO do navio, vessel_imo_number vem null.

A chave continua presente de propósito: sem ela você não distingue "não consta no documento" de "o campo saiu da API". Se o tamanho da resposta importar mais que essa distinção, peça omit_null=true e as chaves nulas somem. Lista vazia e texto vazio continuam, porque já são um valor.

GET /v1/ebl/documents/{job_id}?omit_null=true

Versão do formato

Todo resultado carrega schema_version. Campo novo pode aparecer sem aviso, então trate desconhecido como ignorável. Campo existente não muda de significado nem some dentro da mesma versão.