API Documentation - DUIMP External

Environment

Production: https://api.kestraa.com.br

QA: https://api-qa.kestraa.com.br

POST DUIMP (manual receipt)

Receives DUIMP data sent by a trading partner without the need for a digital certificate. The corporation is resolved from the API Key — no corporation id is sent in the URL. The request is processed synchronously and the persisted content is returned.

Method: POST

Path: /v1/duimp/external

Request

curl --location --request POST '${environment}/v1/duimp/external' \
    --header 'Authorization: Apikey <your-api-key>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "identificacao": {
        "numero": "24BR000001234",
        "versao": 1,
        "dataRegistro": "2026-06-01T10:00:00-0300"
      },
      "situacao": {
        "situacaoDuimp": "REGISTRADA_AGUARDANDO_CANAL"
      }
    }'

Required Headers

Name	Description
Authorization	API Key in the format `Apikey <your-api-key>`. The corporation is resolved from it. (required)
Content-Type	Request content type (application/json). (required)
userName	Identifier of the sending user/system, recorded in the audit trail. (optional)

Request Body — Minimal (required fields only)

{
  "identificacao": {
    "numero": "24BR000001234",
    "versao": 1,
    "dataRegistro": "2026-06-01T10:00:00-0300"
  },
  "situacao": {
    "situacaoDuimp": "REGISTRADA_AGUARDANDO_CANAL",
    "situacaoAnaliseRetificacao": "SEM_ANALISE"
  }
}

Request Body — Complete (all fields)

{
  "identificacao": {
    "numero": "24BR000001234",
    "versao": 1,
    "dataRegistro": "2026-06-01T10:00:00-0300",
    "importador": {
      "tipoImportador": "CNPJ",
      "ni": "12345678000100"
    },
    "informacaoComplementar": "observação livre",
    "chaveAcesso": "string"
  },
  "situacao": {
    "situacaoDuimp": "REGISTRADA_AGUARDANDO_CANAL",
    "situacaoAnaliseRetificacao": "string",
    "situacaoLicenciamento": "string",
    "controleCarga": "string"
  },
  "carga": {
    "unidadeDeclarada": { "codigo": "string" },
    "tipoIdentificacaoCarga": "string",
    "identificacao": "string",
    "seguro": { "codigoMoedaNegociada": "USD", "valorMoedaNegociada": 100.00 },
    "frete": { "codigoMoedaNegociada": "USD", "valorMoedaNegociada": 500.00 },
    "paisProcedencia": { "codigo": "249" },
    "motivoSituacaoEspecial": { "codigo": "string" }
  },
  "documentos": {
    "documentosInstrucao": [
      {
        "tipo": { "codigo": "string" },
        "palavrasChave": [{ "codigo": 1, "valor": "string" }]
      }
    ],
    "processos": [
      { "identificacao": "string", "tipo": "string" }
    ],
    "declaracoesExportacaoEstrangeira": [
      { "numero": "string", "faixaInicio": "string", "faixaFim": "string" }
    ],
    "dossies": [{ "numero": "string" }]
  },
  "adicoes": [
    { "numero": 1, "itens": [1, 2] }
  ],
  "tributos": {
    "mercadoria": {
      "valorTotalLocalEmbarqueBRL": 10000.00,
      "valorTotalLocalEmbarqueUSD": 2000.00
    },
    "tributosCalculados": [
      {
        "tipo": "II",
        "valoresBRL": {
          "calculado": 500.00,
          "aReduzir": 0.00,
          "devido": 500.00,
          "suspenso": 0.00,
          "arecolher": 500.00,
          "recolhido": 0.00
        }
      }
    ]
  },
  "pagamentos": [
    {
      "versaoOrigem": "1",
      "principal": {
        "dataPagamento": "2026-06-01",
        "codigoReceita": "string",
        "banco": "001",
        "agencia": "1234",
        "conta": "12345-6",
        "tributo": { "tipo": "II" },
        "valor": 500.00,
        "juros": {
          "codigoReceita": "string",
          "valor": 0.00,
          "dataPagamentoJuros": "2026-06-01",
          "bancoJuros": "001",
          "agenciaJuros": "1234",
          "contaJuros": "12345-6"
        }
      }
    }
  ],
  "itensData": [
    {
      "status": "string",
      "identificacao": {
        "numero": "24BR000001234",
        "versao": "1",
        "numeroItem": 1
      },
      "produto": {
        "codigo": 1234567,
        "versao": 1,
        "niResponsavel": "string",
        "ncm": "84715010"
      },
      "mercadoria": {
        "tipoAplicacao": { "codigo": "string" },
        "condicao": "string",
        "unidadeComercial": "UN",
        "quantidadeComercial": 10,
        "quantidadeMedidaEstatistica": 10,
        "pesoLiquido": 100.00,
        "moedaNegociada": { "codigo": "USD" },
        "valorUnitarioMoedaNegociada": 200.00,
        "descricao": "Descrição do produto"
      },
      "condicaoVenda": {
        "metodoValoracao": { "codigo": 1 },
        "incoterm": { "codigo": "CIF", "complemento": "string" },
        "valorBRL": 1000.00,
        "valorMoedaNegociada": 200.00,
        "frete": { "valorBRL": 50.00 },
        "seguro": { "valorBRL": 10.00 }
      },
      "tributos": {
        "mercadoria": {
          "valorLocalEmbarqueBRL": 1000.00,
          "valorAduaneiroBRL": 1000.00
        },
        "tributosAplicados": [
          {
            "tributo": { "codigo": "II" },
            "regime": { "codigo": 1 },
            "fundamento": { "codigo": 1 },
            "atributos": [{ "codigo": "string", "valor": "string" }]
          }
        ],
        "tributosCalculados": [
          {
            "tipo": "II",
            "valoresBRL": {
              "calculado": 500.00,
              "devido": 500.00,
              "arecolher": 500.00
            }
          }
        ]
      },
      "dadosCambiais": {
        "coberturaCambial": { "codigo": "string" },
        "numeroROF": "string",
        "valorCoberturaCambial": 200.00
      }
    }
  ]
}

Field Explanation

Field	Type	Required	Description
identificacao.numero	string	Yes	DUIMP registration number (e.g. "24BR000001234").
identificacao.versao	integer	Yes	DUIMP version, positive integer (≥ 1).
situacao.situacaoDuimp	string	Yes	DUIMP status code (e.g. "REGISTRADA_AGUARDANDO_CANAL").
identificacao.dataRegistro	string	Yes	Registration date in ISO 8601 format with timezone offset (e.g. "2026-06-23T10:00:00-0300").
identificacao.importador.tipoImportador	string	No	Importer type code (e.g. "CNPJ", "CPF").
identificacao.importador.ni	string	No	Importer tax identification number.
identificacao.informacaoComplementar	string	No	Free-text supplementary information.
identificacao.chaveAcesso	string	No	Portal Único access key.
situacao.situacaoAnaliseRetificacao	string	Yes	Rectification analysis status. Valid values: `SEM_ANALISE`, `NA`, `PENDENTE_AGUARDANDO_ANALISE`, `DEFERIDA`, `DEFERIDA_COM_EXIGENCIA`, `SEM_ANALISE_POR_CANCELAMENTO`, `DEFERIDA_AUTOMATICAMENTE`. Use `SEM_ANALISE` for new (non-rectified) DUIMPs.
situacao.situacaoLicenciamento	string	No	Licensing status.
situacao.controleCarga	string	No	Cargo control status.
carga	object	No	Cargo data: unit, identification, insurance, freight, country of origin.
carga.seguro / carga.frete	object	No	Monetary value with `codigoMoedaNegociada` (ISO 4217) and `valorMoedaNegociada`.
carga.paisProcedencia.codigo	string	No	Country of origin code (SISCOMEX numeric code, e.g. "249" for USA).
documentos	object	No	Instruction documents, administrative processes, foreign export declarations, and dossiers.
adicoes	array	No	List of additions: `numero` (addition number) and `itens` (array of item indices).
tributos	object	No	Duty summary: `mercadoria` (total value in BRL/USD) and `tributosCalculados` (list of taxes by type).
tributos.tributosCalculados[].tipo	string	No	Tax type code (e.g. "II", "IPI", "PIS", "COFINS").
tributos.tributosCalculados[].valoresBRL.arecolher	number	No	Amount due for payment in BRL. Field key is `arecolher` (no accent, Portal Único format).
pagamentos	array	No	Payment records. Each entry has `versaoOrigem` and `principal` (date, revenue code, bank info, tax type, amount, and optional interest data).
itensData	array	No	DUIMP line items. Each item includes product identification, commercial quantity/value, sale condition (incoterm, valuation method), duties applied and calculated, and exchange data.
itensData[].produto.ncm	string	No	NCM (Nomenclatura Comum do Mercosul) code for the product.
itensData[].mercadoria.unidadeComercial	string	No	Commercial unit of measure (e.g. "UN", "KG", "M2").
itensData[].condicaoVenda.incoterm.codigo	string	No	Incoterm code (e.g. "CIF", "FOB", "EXW").

201 - Response

The same (numero, versao) pair is idempotent: a new pair is created, and a re-sent pair is updated — never duplicated.

{
  "numero": "24BR000001234",
  "versao": 1,
  "situacaoDuimp": "REGISTRADA_AGUARDANDO_CANAL",
  "action": "created",
  "corporationId": 365527
}

Response Fields

Field	Description
action	`created` for a new pair or `updated` for an idempotent re-send.
corporationId	Corporation resolved from the API Key.

HTTP Status Codes

Code	Description
201	Created — DUIMP received and processed.
400	Bad Request — invalid payload (missing `numero`, `versao` ≤ 0, or blank `situacaoDuimp`).
403	Forbidden — invalid API Key or corporation could not be resolved.
409	Conflict — the same DUIMP `(numero, versao)` is already being processed.
429	Too Many Requests — rate limit exceeded for the corporation.
500	Internal Server Error.

POST DUIMP (consolidated receipt)

Receives a DUIMP in the consolidated Portal Único (Siscomex) format: a single JSON with the four root blocks that Portal Único returns from its separate routes (dados_gerais, itens, operador_estrangeiro, produto). Intended for the NCO scenario (no digital certificate). The corporation is resolved from the API Key. The request is processed synchronously and the persisted content is returned.

Method: POST

Path: /v1/duimp/external/consolidated

Required Headers

Name	Description
Authorization	API Key in the format `Apikey <your-api-key>`. The corporation is resolved from it. (required)
Content-Type	Request content type (application/json). (required)
userName	Identifier of the sending user/system, recorded in the audit trail. (optional)

Payload structure

The body has four root blocks, matching the responses of the Portal Único routes:

This endpoint accepts the Portal Único raw JSON without filtering. Fields not listed in this documentation are accepted and ignored — do not strip or transform the original payload before sending.

Block	Type	Required	Description
dados_gerais	object	Yes	DUIMP cover — return of the main Portal Único route (identification, status, cargo, additions, taxes, payments).
itens	array	Yes	DUIMP items — return of the items route. Only items with `status = "ATIVO"` are processed.
operador_estrangeiro	array	No	Foreign operators (manufacturer/exporter) — return of the operators route. Enriches each item by matching `codigo`.
produto	array	No	Product catalog — return of the catalog route.

Cross-references: itens[].fabricante.codigo and itens[].exportador.codigo reference operador_estrangeiro[].codigo; itens[].produto.codigo references produto[].codigo.

Request

curl --location --request POST '${environment}/v1/duimp/external/consolidated' \
    --header 'Authorization: Apikey <your-api-key>' \
    --header 'Content-Type: application/json' \
    --data-raw '{ ...consolidated JSON (four blocks)... }'

Request Body — Example (abbreviated)

{
  "dados_gerais": {
    "identificacao": {
      "numero": "26BR00001372913",
      "versao": 1,
      "importador": { "tipoImportador": "CNPJ", "ni": "04626426000700" },
      "dataRegistro": "2026-02-18T17:28:29-0300",
      "chaveAcesso": "26WfT002126090"
    },
    "situacao": {
      "situacaoDuimp": "DESEMBARACADA_CARGA_ENTREGUE",
      "situacaoAnaliseRetificacao": "NA",
      "situacaoLicenciamento": "DISPENSADO",
      "controleCarga": "ENTREGUE"
    },
    "carga": {
      "unidadeDeclarada": { "codigo": "0727600" },
      "tipoIdentificacaoCarga": "CE",
      "identificacao": "122605012237562",
      "frete": { "codigoMoedaNegociada": "USD", "valorMoedaNegociada": 35860.00 },
      "seguro": { "codigoMoedaNegociada": "USD", "valorMoedaNegociada": 21.97 },
      "paisProcedencia": { "codigo": "MX" }
    },
    "adicoes": [ { "numero": 1, "itens": [1] } ],
    "tributos": {
      "tributosCalculados": [
        { "tipo": "II",  "valoresBRL": { "calculado": 0.00, "devido": 0.00, "aRecolher": 0.00 } },
        { "tipo": "IPI", "valoresBRL": { "calculado": 0.00, "devido": 0.00, "aRecolher": 0.00 } },
        { "tipo": "PIS", "valoresBRL": { "calculado": 16086.18, "devido": 16086.18, "aRecolher": 16086.18 } },
        { "tipo": "COFINS", "valoresBRL": { "calculado": 73919.83, "devido": 73919.83, "aRecolher": 73919.83 } },
        { "tipo": "TAXA_UTILIZACAO", "valoresBRL": { "aRecolher": 154.23, "recolhido": 154.23 } }
      ]
    },
    "pagamentos": [
      {
        "versaoOrigem": 1,
        "principal": {
          "dataPagamento": "2026-02-18T17:28:36-0300",
          "codigoReceita": "5602",
          "banco": "033", "agencia": "3689", "conta": "13001871",
          "tributo": { "tipo": "PIS" },
          "valor": 16086.18
        }
      }
    ]
  },
  "itens": [
    {
      "status": "ATIVO",
      "identificacao": { "numero": "26BR00001372913", "versao": 1, "numeroItem": 1 },
      "produto": { "codigo": "14666", "versao": "1", "niResponsavel": "04626426", "ncm": "38029010" },
      "caracterizacaoImportacao": { "indicador": "IMPORTACAO_POR_CONTA_E_ORDEM", "ni": "07526557001181" },
      "fabricante": { "codigo": "OPE_652", "versao": "1", "pais": { "codigo": "MX" } },
      "exportador": { "codigo": "OPE_650", "versao": "1", "pais": { "codigo": "US" } },
      "mercadoria": {
        "unidadeComercial": "KILO",
        "quantidadeComercial": "200210.00000",
        "moedaNegociada": { "codigo": "USD" },
        "valorUnitarioMoedaNegociada": "0.5524999"
      },
      "condicaoVenda": {
        "incoterm": { "codigo": "EXW" },
        "valorBRL": "578388.94",
        "valorMoedaNegociada": "110616.00",
        "frete": { "valorBRL": "187504.77" },
        "seguro": { "valorBRL": "114.88" }
      },
      "dadosCambiais": { "coberturaCambial": { "codigo": "ATE_180_DIAS" } },
      "tributos": {
        "tributosCalculados": [
          { "tipo": "II", "valoresBRL": { "calculado": 0.00, "devido": 0.00, "aRecolher": 0.00 } }
        ]
      },
      "atributosDuimp": [ { "codigo": "ATT_15540", "valor": "000001" } ]
    }
  ],
  "operador_estrangeiro": [
    {
      "cpfCnpjRaiz": "04626426",
      "codigo": "OPE_652",
      "versao": "1",
      "tin": "ALM740506GK9",
      "nome": "IMERYS ALMERIA, S.A. DE C.V.",
      "situacao": "Ativado",
      "logradouro": "JOSE ANTONIO TORRES, 400",
      "nomeCidade": "ZACOALCO DE TORRES",
      "codigoPais": "MX",
      "codigoInterno": "39872"
    },
    {
      "cpfCnpjRaiz": "04626426",
      "codigo": "OPE_650",
      "versao": "1",
      "tin": "770298773",
      "nome": "IMERYS FILTRATION MINERALS INC.",
      "situacao": "Ativado",
      "logradouro": "MANSEL COURT EAST, 100",
      "nomeCidade": "ROSWELL",
      "codigoPais": "US",
      "codigoInterno": "161001"
    }
  ],
  "produto": [
    {
      "codigo": 14666,
      "descricao": "TESTE",
      "denominacao": "TESTE",
      "cpfCnpjRaiz": "04626426",
      "situacao": "Ativado",
      "modalidade": "IMPORTACAO",
      "ncm": "38029010",
      "versao": "1",
      "codigosInterno": ["xpto"],
      "atributos": []
    }
  ]
}

Field Explanation

Field	Type	Required	Description
dados_gerais.identificacao.numero	string	Yes	DUIMP number.
dados_gerais.identificacao.versao	integer	Yes	DUIMP version, positive integer (≥ 1).
dados_gerais.situacao.situacaoDuimp	string	Yes	DUIMP status code (e.g. "DESEMBARACADA_CARGA_ENTREGUE").
dados_gerais.identificacao.dataRegistro	string	No	Registration date, ISO 8601 with offset. May be null in the raw Siscomex format.
dados_gerais.identificacao.importador.ni	string	No	Importer CNPJ.
dados_gerais.situacao.situacaoAnaliseRetificacao	string	No	Rectification analysis status. May be null in the raw Siscomex format.
dados_gerais.carga	object	No	Cargo: declared unit, cargo identification, freight/insurance (currency + value), country of origin.
dados_gerais.adicoes	array	No	Additions: `numero` and `itens` (item indices).
dados_gerais.tributos.tributosCalculados	array	No	Taxes by type (II, IPI, PIS, COFINS, TAXA_UTILIZACAO) with BRL values.
dados_gerais.pagamentos	array	No	Payment records: revenue code, bank/agency/account, tax type, amount.
itens[].status	string	Yes	Item status. Only `ATIVO` is processed.
itens[].identificacao.numeroItem	integer	Yes	Item number within the DUIMP.
itens[].produto.codigo	string	No	Product code — references `produto[].codigo`.
itens[].produto.ncm	string	No	NCM code.
itens[].caracterizacaoImportacao.ni	string	No	Acquirer CNPJ (import on behalf of / by order).
itens[].fabricante.codigo	string	No	Manufacturer code — references `operador_estrangeiro[].codigo`.
itens[].exportador.codigo	string	No	Exporter code — references `operador_estrangeiro[].codigo`.
itens[].mercadoria	object	No	Commercial quantity/unit, negotiated currency and unit value.
itens[].condicaoVenda	object	No	Incoterm, BRL/negotiated values, freight and insurance in BRL.
itens[].tributos.tributosCalculados	array	No	Item taxes (II, IPI, PIS, COFINS) with values.
operador_estrangeiro[].codigo	string	No	Operator code, referenced by `itens[].fabricante/exportador.codigo`.
operador_estrangeiro[].tin / nome / logradouro / nomeCidade / codigoPais	string	No	Operator identification and address.
produto[].codigo	integer	No	Catalog product code, referenced by `itens[].produto.codigo`.
produto[].ncm / descricao / denominacao / modalidade	string	No	Catalog product data.

200 - Response

Processed synchronously. The same (numero, versao) pair is idempotent: a new pair is created, and a re-sent pair is updated — never duplicated.

{
  "numero": "26BR00001372913",
  "versao": 1,
  "situacaoDuimp": "DESEMBARACADA_CARGA_ENTREGUE",
  "action": "created",
  "corporationId": 365527
}

Error Response

{
  "error": "Field 'numero' in 'dados_gerais.identificacao' is required and cannot be blank"
}

HTTP Status Codes

Code	Description
200	OK — DUIMP received and processed.
400	Bad Request — invalid payload (missing `dados_gerais.identificacao.numero`, `versao` ≤ 0, or blank `situacaoDuimp`).
401	Unauthorized — missing or invalid API Key.
403	Forbidden — corporation could not be resolved from the API Key.
409	Conflict — the same DUIMP `(numero, versao)` is already being processed.
429	Too Many Requests — rate limit exceeded for the corporation.
500	Internal Server Error.