> For the complete documentation index, see [llms.txt](https://changelog.maino.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://changelog.maino.com.br/api-reference-maino/15.-processos-de-comex.md).

# 15. ⚓ Processos De Comex

**Gestão completa de comércio exterior** Controle end-to-end de processos de importação e exportação. **Cobertura:**

* Processos de importação e exportação
* Controle documental completo
* Gestão de câmbio e remessas
* Drawback e regimes especiais

## Vincula DI ou DUIMP ao processo

> \*\*Vincula uma DI ou uma DUIMP a um processo existente\*\*\
> \
> Informe \*\*exatamente um\*\* identificador dentro da raiz \`documento\`:\
> \
> \| Chave | Resolve |\
> \|---|---|\
> \| \`numero\` | DI \*\*ou\*\* DUIMP — o servidor decide qual, comparando o número normalizado (sem máscara) contra as duas bases |\
> \| \`di\_id\` | DI pelo id exato |\
> \| \`duimp\_id\` | DUIMP pelo id exato (UUID) |\
> \
> \*\*Requer permissão:\*\* o usuário precisa ter permissão de escrita em "processos". Sem ela a\
> resposta é \*\*403\*\*, com o envelope \`{"message": "Você não tem autorização para acessar esta página."}\`.\
> \
> \*\*Status 200, não 201:\*\* o processo já existia — o vínculo altera um processo, não cria recurso novo.\
> \
> \*\*O 200 confirma o vínculo, não o preenchimento.\*\* Produtos, valores e custos vindos do\
> documento são carregados por processamento assíncrono. Para ver o processo já preenchido,\
> reconsulte \`GET /processos/{uuid}\` alguns instantes depois.\
> \
> \*\*Nenhum identificador informado\*\* (ex: \`{"documento": {"numero": ""}}\`) → 422 no ponteiro\
> \`/documento\`. \*\*Raiz \`documento\` ausente ou vazia\*\* → 400 (\`ActionController::ParameterMissing\`),\
> com envelope diferente do 422.\
> \
> \*\*Mais de um identificador\*\* → 422 no ponteiro \`/documento\`, listando o que foi recebido.\
> \
> \*\*\`numero\` ambíguo\*\* (casa mais de uma DI/DUIMP) → 422 no ponteiro \`/numero\`, instruindo o\
> reenvio com \`di\_id\` ou \`duimp\_id\`.\
> \
> \*\*A API não substitui documento já vinculado.\*\* Processo que já tem DI ou DUIMP devolve 422\
> em \`/documento\`; documento já vinculado a outro processo devolve 422 no ponteiro do\
> identificador enviado. Reenviar o mesmo vínculo que já existe é idempotente (200, sem alteração).\
> \
> \*\*Processo inexistente ou de outra empresa\*\* → 404 \*\*sem corpo\*\*.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"15. ⚓ Processos de Comex","description":"**Gestão completa de comércio exterior**\nControle end-to-end de processos de importação e exportação.\n**Cobertura:**\n- Processos de importação e exportação\n- Controle documental completo\n- Gestão de câmbio e remessas\n- Drawback e regimes especiais"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}},"schemas":{"Processo":{"type":"object","description":"Processo de comércio exterior serializado pela API v2. Mesma forma devolvida pelo item do GET /processos, pelo 201 do POST /processos e pelos 200 dos endpoints de vínculo de documento e de ordem de compra.","properties":{"id":{"type":"integer","description":"ID do processo"},"uuid":{"type":"string","format":"uuid","description":"Identificador público do processo (usado nos paths de vínculo)"},"numero":{"type":"string","description":"Código do processo"},"descricao":{"type":"string","nullable":true,"description":"Descrição do processo"},"data_criacao":{"type":"string","description":"Data e hora de criação"},"cliente":{"type":"string","nullable":true,"description":"Razão social do cliente"},"modalidade":{"type":"string","nullable":true,"description":"Modalidade do processo"},"tipo":{"type":"string","nullable":true,"description":"Tipo (importação/exportação)"},"via":{"type":"string","nullable":true,"description":"Via de transporte (marítima/aérea/terrestre)"},"categoria":{"type":"string","nullable":true,"description":"Categoria do processo"},"etapa":{"type":"string","nullable":true,"description":"Etapa atual do processo"},"canal":{"type":"string","nullable":true,"description":"Canal de parametrização"},"vmle":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de embarque"},"frete":{"type":"number","format":"float","nullable":true,"description":"Valor do frete"},"seguro":{"type":"number","format":"float","nullable":true,"description":"Valor do seguro"},"vmld":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de descarga"},"fornecedor":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — apesar do nome, devolve o IMPORTADOR, não o fornecedor: documento e razão social no formato \"<documento> - <razão social>\" (só a razão social quando não há documento; nome, tipo e valor mantidos por compatibilidade). O fornecedor principal do processo está em stakeholder_fornecedor; a lista de fornecedores, no array fornecedores; o importador estruturado, em importador."},"container":{"type":"string","nullable":true,"description":"Número do container"},"outra_referencia":{"type":"string","nullable":true,"description":"Outra referência"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento"},"data_cambio_antecipacao":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio de antecipação"},"codigo_purchase_order":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra (numero). Código da Purchase Order (string livre legada, mantido por compatibilidade)."},"data_purchase_order":{"type":"string","format":"date","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra. Data da Purchase Order (string livre legada, mantido por compatibilidade)."},"observacao":{"type":"string","nullable":true,"description":"Observações"},"companhia_aerea":{"type":"string","nullable":true,"description":"Companhia aérea"},"numero_do_voo":{"type":"string","nullable":true,"description":"Número do voo"},"navio":{"type":"string","nullable":true,"description":"Nome do navio"},"placa_do_veiculo_transportador":{"type":"string","nullable":true,"description":"Placa do veículo"},"armador":{"type":"string","nullable":true,"description":"Armador"},"conhecimento_de_embarque":{"type":"string","nullable":true,"description":"Conhecimento de embarque"},"pais_procedencia":{"type":"string","nullable":true,"description":"País de procedência"},"embarque":{"type":"string","nullable":true,"description":"Local de embarque"},"data_embarque":{"type":"string","format":"date","nullable":true,"description":"Data de embarque"},"pais_destino":{"type":"string","nullable":true,"description":"País de destino"},"desembarque":{"type":"string","nullable":true,"description":"Local de desembarque"},"data_chegada":{"type":"string","format":"date","nullable":true,"description":"Data de chegada"},"eta":{"type":"string","format":"date","nullable":true,"description":"ETA (Estimated Time of Arrival)"},"agente_de_carga":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o objeto agente_carga (id/razao_social/documento). Agente de carga (string legada, mantida por compatibilidade)."},"stakeholder_agente_carga_id":{"type":"integer","nullable":true,"description":"ID do stakeholder agente de carga"},"bl":{"type":"string","nullable":true,"description":"Número do BL (via marítima)"},"data_emissao_bl":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do BL"},"awb":{"type":"string","nullable":true,"description":"Número do AWB (via aérea)"},"data_emissao_awb":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do AWB"},"crt":{"type":"string","nullable":true,"description":"Número do CRT (via terrestre)"},"data_emissao_crt":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do CRT"},"fci":{"type":"string","nullable":true,"description":"FCI"},"incoterm":{"type":"string","nullable":true,"description":"Incoterm utilizado"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"status_container":{"type":"string","nullable":true,"description":"Status do container"},"presenca_carga":{"type":"string","nullable":true,"description":"Presença da carga"},"numero_invoice":{"type":"string","nullable":true,"description":"Número da invoice"},"valor_invoice":{"type":"number","format":"float","nullable":true,"description":"Valor da invoice"},"vencimento_invoice":{"type":"string","format":"date","nullable":true,"description":"Vencimento da invoice"},"data_cambio_saldo":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio do saldo"},"terminal_de_armazenagem":{"type":"string","nullable":true,"description":"Terminal de armazenagem"},"data_pedido":{"type":"string","format":"date","nullable":true,"description":"Data do pedido (AAAA-MM-DD). Mesmo campo aceito no POST/PATCH."},"numerario_cambio":{"type":"string","nullable":true,"description":"Numerário de câmbio (decimal serializado como string). Mesmo campo aceito no POST/PATCH."},"moeda_codigo_iso":{"type":"string","nullable":true,"description":"Sigla ISO da moeda do processo (ex: USD). Espelha o campo moeda_codigo_iso do POST/PATCH."},"etapa_processo_id":{"type":"string","format":"uuid","description":"Identificador da etapa atual do processo. A chave etapa continua devolvendo a descrição."},"importador":{"type":"object","nullable":true,"description":"Stakeholder importador do processo. Null quando não há importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do importador"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do importador (numero_do_documento na origem)."}}},"stakeholder_fornecedor":{"type":"object","nullable":true,"description":"Stakeholder fornecedor do processo (coluna stakeholder_fornecedor_id, preenchida por fornecedor_documento/fornecedor_razao_social no POST). Null quando não há fornecedor. Não confundir com a chave legada fornecedor, que devolve o importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}},"stakeholder_cliente":{"type":"object","nullable":true,"description":"Stakeholder cliente do processo. Null quando não há cliente. A chave cliente continua devolvendo só a razão social.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do cliente"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do cliente (numero_do_documento na origem)."}}},"anexos":{"type":"array","nullable":true,"description":"Anexos do processo","items":{"type":"object","properties":{"anexo":{"type":"object","properties":{"url":{"type":"string","description":"URL do anexo"}}}}}},"di":{"type":"object","nullable":true,"description":"Declaração de Importação","properties":{"codigo":{"type":"string","nullable":true,"description":"Código da DI"},"data_de_desembaraco":{"type":"string","format":"date","nullable":true,"description":"Data de desembaraço"},"data_registro":{"type":"string","format":"date","nullable":true,"description":"Data de registro"}}},"responsavel":{"type":"object","nullable":true,"description":"Pessoa responsável pelo processo (campo Q2). A edição da Pessoa vinculada reflete no próximo GET (cache key do fragmento inclui a associação — Slice 5).","properties":{"id":{"type":"integer","description":"ID da Pessoa"},"nome":{"type":"string","description":"Nome da Pessoa"},"foto_url":{"type":"string","nullable":true,"description":"URL da foto de perfil (CarrierWave). Null se sem upload."}}},"despachante":{"type":"object","nullable":true,"description":"Stakeholder despachante do processo (campo Q2).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do despachante"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do despachante (numero_do_documento na origem)."}}},"agente_carga":{"type":"object","nullable":true,"description":"Objeto stakeholder do agente de carga (campo Q2). Coexiste com agente_de_carga (string legada) e stakeholder_agente_carga_id (int legado).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do agente de carga"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do agente de carga."}}},"data_embarque_previsto":{"type":"string","format":"date","nullable":true,"description":"ETD — data prevista de embarque (campo Q2)."},"incoterm_legado":{"type":"string","nullable":true,"description":"Valor de incoterm fora do enum normalizado (ex: 'EXX'). Coexiste com incoterm (campo Q2)."},"fornecedores":{"type":"array","description":"Fornecedores M:N do processo (campo Q2). Sempre array — vazio quando não houver fornecedores, nunca null. Coexiste com o campo legado 'fornecedor' (string derivada do importador). Adicionar/remover fornecedor reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID do Stakeholder fornecedor"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}}},"tags":{"type":"array","description":"Nomes das custom tags vinculadas ao processo (campo Q2). Sempre array — vazio quando não houver tags, nunca null. Adicionar/remover tag reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"string"}},"conteineres":{"type":"array","description":"Lista de contêineres do processo (campo Q2). O item com monitorado: true é o contêiner principal cujos numero/peso_bruto/peso_liquido são refletidos no nível do processo (apenas um por processo). Editar o contêiner (inclusive os campos de demurrage) reflete no próximo GET (cache key do fragmento inclui a associação conteineres — Slice 5). Atenção: não confundir moeda_tarifa: 'USD' com dado intencional quando free_time é null, pois USD é o default do banco.","items":{"type":"object","properties":{"numero":{"type":"string","nullable":true,"description":"Número de identificação do contêiner"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"monitorado":{"type":"boolean","description":"Quando true, este é o contêiner principal do processo (apenas um por processo)"},"free_time":{"type":"integer","nullable":true,"description":"Free time em dias contratado com o armador"},"tarifa_demurrage":{"type":"string","nullable":true,"description":"Tarifa de demurrage por dia após o free time (decimal 15,2 serializado como string)"},"moeda_tarifa":{"type":"string","nullable":true,"enum":["BRL","USD"],"description":"Moeda da tarifa_demurrage (BRL ou USD). Default USD no banco — não confundir com dado intencional quando free_time é null"},"inicio_free_time":{"type":"string","format":"date","nullable":true,"description":"Data de início do free time (ISO 8601)"},"data_devolucao":{"type":"string","format":"date","nullable":true,"description":"Data de devolução do contêiner ao armador (ISO 8601)"}}}},"ordem_de_compra":{"type":"object","nullable":true,"description":"Ordem de Compra vinculada ao processo e itens alocados (campo Q2, Slice 4). Substitui os campos legados codigo_purchase_order/data_purchase_order (strings livres, deprecados) pelo vínculo estruturado 1:1 com a OC. Omitido (chave ausente, não null) quando não há OC vinculada. Renderizado fora do fragmento cacheado por-processo (sempre resolve no GET, padrão di/anexos — Slice 4).","properties":{"id":{"type":"integer","description":"ID da Ordem de Compra"},"numero":{"type":"string","description":"Número identificador da Ordem de Compra (OrdemDeCompra#numero)"},"itens":{"type":"array","description":"Itens da OC alocados ao processo. Array vazio quando a OC está vinculada mas sem itens alocados.","items":{"type":"object","properties":{"id":{"type":"string","description":"ID do vínculo item-OC-processo (UUID)"},"item_ordem_de_compra_id":{"type":"integer","description":"ID do item da Ordem de Compra alocado"},"quantidade_alocada":{"type":"string","description":"Quantidade alocada ao processo (decimal 15,4 serializado como string)"}}}}}},"notas_fiscais_vinculadas":{"type":"array","description":"NF-es vinculadas ao processo — a mesma lista da seção \"NF-es vinculadas\" da tela: notas com este processo atribuído, ou sem processo e com a mesma DI/DUIMP do processo, nas situações aceita e finalizada, em ordem de id. Sempre array — vazio quando não há nota, nunca null. Renderizado fora do fragmento cacheado por-processo: vincular, desvincular ou mudar a situação da nota reflete no próximo GET.","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID da NF-e"},"numero":{"type":"integer","nullable":true,"description":"Número da NF-e"},"serie":{"type":"integer","nullable":true,"description":"Série da NF-e"},"chave_acesso":{"type":"string","nullable":true,"description":"Chave de acesso de 44 dígitos. Null quando a nota não tem chave gravada."},"tipo":{"type":"string","nullable":true,"enum":["entrada","saida"],"description":"Tipo da NF-e: entrada ou saida"},"data_emissao":{"type":"string","format":"date-time","description":"Data e hora de emissão (ISO 8601)"},"valor_total":{"type":"number","format":"float","description":"Total da NF-e com 2 casas decimais — o mesmo valor da coluna \"Total da NF-e\" da tela"},"situacao":{"type":"string","enum":["aceita","finalizada"],"description":"Situação da NF-e: aceita ou finalizada"}},"required":["id","numero","serie","chave_acesso","tipo","data_emissao","valor_total","situacao"]}}},"required":["id","numero","notas_fiscais_vinculadas"]},"ErrosEstruturados":{"type":"object","description":"Envelope de erro de validação da API v2 de processos. Cada chave é um JSON Pointer para o campo recusado e o valor é a mensagem correspondente.","properties":{"errors":{"type":"object","description":"Objeto com os erros de validação no formato JSON Pointer","additionalProperties":{"type":"string"}}},"required":["errors"]}}},"paths":{"/processos/{processo_id}/documento":{"post":{"summary":"Vincula DI ou DUIMP ao processo","tags":["15. ⚓ Processos de Comex"],"description":"**Vincula uma DI ou uma DUIMP a um processo existente**\n\nInforme **exatamente um** identificador dentro da raiz `documento`:\n\n| Chave | Resolve |\n|---|---|\n| `numero` | DI **ou** DUIMP — o servidor decide qual, comparando o número normalizado (sem máscara) contra as duas bases |\n| `di_id` | DI pelo id exato |\n| `duimp_id` | DUIMP pelo id exato (UUID) |\n\n**Requer permissão:** o usuário precisa ter permissão de escrita em \"processos\". Sem ela a\nresposta é **403**, com o envelope `{\"message\": \"Você não tem autorização para acessar esta página.\"}`.\n\n**Status 200, não 201:** o processo já existia — o vínculo altera um processo, não cria recurso novo.\n\n**O 200 confirma o vínculo, não o preenchimento.** Produtos, valores e custos vindos do\ndocumento são carregados por processamento assíncrono. Para ver o processo já preenchido,\nreconsulte `GET /processos/{uuid}` alguns instantes depois.\n\n**Nenhum identificador informado** (ex: `{\"documento\": {\"numero\": \"\"}}`) → 422 no ponteiro\n`/documento`. **Raiz `documento` ausente ou vazia** → 400 (`ActionController::ParameterMissing`),\ncom envelope diferente do 422.\n\n**Mais de um identificador** → 422 no ponteiro `/documento`, listando o que foi recebido.\n\n**`numero` ambíguo** (casa mais de uma DI/DUIMP) → 422 no ponteiro `/numero`, instruindo o\nreenvio com `di_id` ou `duimp_id`.\n\n**A API não substitui documento já vinculado.** Processo que já tem DI ou DUIMP devolve 422\nem `/documento`; documento já vinculado a outro processo devolve 422 no ponteiro do\nidentificador enviado. Reenviar o mesmo vínculo que já existe é idempotente (200, sem alteração).\n\n**Processo inexistente ou de outra empresa** → 404 **sem corpo**.","parameters":[{"name":"processo_id","in":"path","format":"uuid","required":true,"description":"UUID do processo (campo `uuid` devolvido pelo GET /processos)","schema":{"type":"string"}}],"responses":{"200":{"description":"Vínculo aplicado — processo atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Processo"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Processo inexistente ou de outra empresa — sem corpo"},"422":{"description":"Erro de validação","content":{"Nenhum identificador informado":{},"Mais de um identificador":{},"Número ambíguo":{},"Processo já possui documento":{},"Documento já vinculado a outro processo":{},"application/json":{"schema":{"$ref":"#/components/schemas/ErrosEstruturados"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"documento":{"type":"object","description":"Informe exatamente uma das chaves abaixo.","properties":{"numero":{"type":"string","description":"Número da DI ou da DUIMP, com ou sem máscara. O servidor decide qual documento resolve."},"di_id":{"type":"integer","description":"ID da DI."},"duimp_id":{"type":"string","format":"uuid","description":"ID da DUIMP."}}}},"required":["documento"]}}},"required":true}}}}}
```

## Vincula ordem de compra ao processo

> \*\*Vincula uma ordem de compra a um processo existente\*\*\
> \
> Informe \*\*exatamente um\*\* identificador dentro da raiz \`ordem\_de\_compra\`:\
> \
> \| Chave | Resolve |\
> \|---|---|\
> \| \`numero\` | Ordem de compra pelo número (busca exata, entre as OCs da empresa) |\
> \| \`id\` | Ordem de compra pelo id |\
> \
> \*\*Requer permissão:\*\* o usuário precisa ter permissão de escrita em "processos". Sem ela a\
> resposta é \*\*403\*\*, com o envelope \`{"message": "Você não tem autorização para acessar esta página."}\`.\
> \
> \*\*Status 200, não 201:\*\* o processo já existia — o vínculo altera um processo, não cria recurso novo.\
> \
> \*\*O 200 confirma o vínculo, não a alocação dos itens.\*\* O bloco \`ordem\_de\_compra\` da resposta\
> traz a OC vinculada; a alocação de itens ao processo é feita à parte. Reconsulte\
> \`GET /processos/{uuid}\` para acompanhar.\
> \
> \*\*Nenhum identificador informado\*\* (ex: \`{"ordem\_de\_compra": {"numero": ""}}\`) → 422 no ponteiro\
> \`/ordem\_de\_compra\`. \*\*Raiz \`ordem\_de\_compra\` ausente ou vazia\*\* → 400\
> (\`ActionController::ParameterMissing\`), com envelope diferente do 422.\
> \
> \*\*Mais de um identificador\*\* → 422 no ponteiro \`/ordem\_de\_compra\`, listando o que foi recebido.\
> \
> \*\*A API não substitui ordem de compra já vinculada.\*\* Processo que já tem OC devolve 422 em\
> \`/ordem\_de\_compra\`. Reenviar o mesmo vínculo que já existe é idempotente (200, sem alteração).\
> \
> \*\*Processo inexistente ou de outra empresa\*\* → 404 \*\*sem corpo\*\*.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"15. ⚓ Processos de Comex","description":"**Gestão completa de comércio exterior**\nControle end-to-end de processos de importação e exportação.\n**Cobertura:**\n- Processos de importação e exportação\n- Controle documental completo\n- Gestão de câmbio e remessas\n- Drawback e regimes especiais"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}},"schemas":{"Processo":{"type":"object","description":"Processo de comércio exterior serializado pela API v2. Mesma forma devolvida pelo item do GET /processos, pelo 201 do POST /processos e pelos 200 dos endpoints de vínculo de documento e de ordem de compra.","properties":{"id":{"type":"integer","description":"ID do processo"},"uuid":{"type":"string","format":"uuid","description":"Identificador público do processo (usado nos paths de vínculo)"},"numero":{"type":"string","description":"Código do processo"},"descricao":{"type":"string","nullable":true,"description":"Descrição do processo"},"data_criacao":{"type":"string","description":"Data e hora de criação"},"cliente":{"type":"string","nullable":true,"description":"Razão social do cliente"},"modalidade":{"type":"string","nullable":true,"description":"Modalidade do processo"},"tipo":{"type":"string","nullable":true,"description":"Tipo (importação/exportação)"},"via":{"type":"string","nullable":true,"description":"Via de transporte (marítima/aérea/terrestre)"},"categoria":{"type":"string","nullable":true,"description":"Categoria do processo"},"etapa":{"type":"string","nullable":true,"description":"Etapa atual do processo"},"canal":{"type":"string","nullable":true,"description":"Canal de parametrização"},"vmle":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de embarque"},"frete":{"type":"number","format":"float","nullable":true,"description":"Valor do frete"},"seguro":{"type":"number","format":"float","nullable":true,"description":"Valor do seguro"},"vmld":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de descarga"},"fornecedor":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — apesar do nome, devolve o IMPORTADOR, não o fornecedor: documento e razão social no formato \"<documento> - <razão social>\" (só a razão social quando não há documento; nome, tipo e valor mantidos por compatibilidade). O fornecedor principal do processo está em stakeholder_fornecedor; a lista de fornecedores, no array fornecedores; o importador estruturado, em importador."},"container":{"type":"string","nullable":true,"description":"Número do container"},"outra_referencia":{"type":"string","nullable":true,"description":"Outra referência"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento"},"data_cambio_antecipacao":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio de antecipação"},"codigo_purchase_order":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra (numero). Código da Purchase Order (string livre legada, mantido por compatibilidade)."},"data_purchase_order":{"type":"string","format":"date","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra. Data da Purchase Order (string livre legada, mantido por compatibilidade)."},"observacao":{"type":"string","nullable":true,"description":"Observações"},"companhia_aerea":{"type":"string","nullable":true,"description":"Companhia aérea"},"numero_do_voo":{"type":"string","nullable":true,"description":"Número do voo"},"navio":{"type":"string","nullable":true,"description":"Nome do navio"},"placa_do_veiculo_transportador":{"type":"string","nullable":true,"description":"Placa do veículo"},"armador":{"type":"string","nullable":true,"description":"Armador"},"conhecimento_de_embarque":{"type":"string","nullable":true,"description":"Conhecimento de embarque"},"pais_procedencia":{"type":"string","nullable":true,"description":"País de procedência"},"embarque":{"type":"string","nullable":true,"description":"Local de embarque"},"data_embarque":{"type":"string","format":"date","nullable":true,"description":"Data de embarque"},"pais_destino":{"type":"string","nullable":true,"description":"País de destino"},"desembarque":{"type":"string","nullable":true,"description":"Local de desembarque"},"data_chegada":{"type":"string","format":"date","nullable":true,"description":"Data de chegada"},"eta":{"type":"string","format":"date","nullable":true,"description":"ETA (Estimated Time of Arrival)"},"agente_de_carga":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o objeto agente_carga (id/razao_social/documento). Agente de carga (string legada, mantida por compatibilidade)."},"stakeholder_agente_carga_id":{"type":"integer","nullable":true,"description":"ID do stakeholder agente de carga"},"bl":{"type":"string","nullable":true,"description":"Número do BL (via marítima)"},"data_emissao_bl":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do BL"},"awb":{"type":"string","nullable":true,"description":"Número do AWB (via aérea)"},"data_emissao_awb":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do AWB"},"crt":{"type":"string","nullable":true,"description":"Número do CRT (via terrestre)"},"data_emissao_crt":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do CRT"},"fci":{"type":"string","nullable":true,"description":"FCI"},"incoterm":{"type":"string","nullable":true,"description":"Incoterm utilizado"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"status_container":{"type":"string","nullable":true,"description":"Status do container"},"presenca_carga":{"type":"string","nullable":true,"description":"Presença da carga"},"numero_invoice":{"type":"string","nullable":true,"description":"Número da invoice"},"valor_invoice":{"type":"number","format":"float","nullable":true,"description":"Valor da invoice"},"vencimento_invoice":{"type":"string","format":"date","nullable":true,"description":"Vencimento da invoice"},"data_cambio_saldo":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio do saldo"},"terminal_de_armazenagem":{"type":"string","nullable":true,"description":"Terminal de armazenagem"},"data_pedido":{"type":"string","format":"date","nullable":true,"description":"Data do pedido (AAAA-MM-DD). Mesmo campo aceito no POST/PATCH."},"numerario_cambio":{"type":"string","nullable":true,"description":"Numerário de câmbio (decimal serializado como string). Mesmo campo aceito no POST/PATCH."},"moeda_codigo_iso":{"type":"string","nullable":true,"description":"Sigla ISO da moeda do processo (ex: USD). Espelha o campo moeda_codigo_iso do POST/PATCH."},"etapa_processo_id":{"type":"string","format":"uuid","description":"Identificador da etapa atual do processo. A chave etapa continua devolvendo a descrição."},"importador":{"type":"object","nullable":true,"description":"Stakeholder importador do processo. Null quando não há importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do importador"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do importador (numero_do_documento na origem)."}}},"stakeholder_fornecedor":{"type":"object","nullable":true,"description":"Stakeholder fornecedor do processo (coluna stakeholder_fornecedor_id, preenchida por fornecedor_documento/fornecedor_razao_social no POST). Null quando não há fornecedor. Não confundir com a chave legada fornecedor, que devolve o importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}},"stakeholder_cliente":{"type":"object","nullable":true,"description":"Stakeholder cliente do processo. Null quando não há cliente. A chave cliente continua devolvendo só a razão social.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do cliente"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do cliente (numero_do_documento na origem)."}}},"anexos":{"type":"array","nullable":true,"description":"Anexos do processo","items":{"type":"object","properties":{"anexo":{"type":"object","properties":{"url":{"type":"string","description":"URL do anexo"}}}}}},"di":{"type":"object","nullable":true,"description":"Declaração de Importação","properties":{"codigo":{"type":"string","nullable":true,"description":"Código da DI"},"data_de_desembaraco":{"type":"string","format":"date","nullable":true,"description":"Data de desembaraço"},"data_registro":{"type":"string","format":"date","nullable":true,"description":"Data de registro"}}},"responsavel":{"type":"object","nullable":true,"description":"Pessoa responsável pelo processo (campo Q2). A edição da Pessoa vinculada reflete no próximo GET (cache key do fragmento inclui a associação — Slice 5).","properties":{"id":{"type":"integer","description":"ID da Pessoa"},"nome":{"type":"string","description":"Nome da Pessoa"},"foto_url":{"type":"string","nullable":true,"description":"URL da foto de perfil (CarrierWave). Null se sem upload."}}},"despachante":{"type":"object","nullable":true,"description":"Stakeholder despachante do processo (campo Q2).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do despachante"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do despachante (numero_do_documento na origem)."}}},"agente_carga":{"type":"object","nullable":true,"description":"Objeto stakeholder do agente de carga (campo Q2). Coexiste com agente_de_carga (string legada) e stakeholder_agente_carga_id (int legado).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do agente de carga"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do agente de carga."}}},"data_embarque_previsto":{"type":"string","format":"date","nullable":true,"description":"ETD — data prevista de embarque (campo Q2)."},"incoterm_legado":{"type":"string","nullable":true,"description":"Valor de incoterm fora do enum normalizado (ex: 'EXX'). Coexiste com incoterm (campo Q2)."},"fornecedores":{"type":"array","description":"Fornecedores M:N do processo (campo Q2). Sempre array — vazio quando não houver fornecedores, nunca null. Coexiste com o campo legado 'fornecedor' (string derivada do importador). Adicionar/remover fornecedor reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID do Stakeholder fornecedor"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}}},"tags":{"type":"array","description":"Nomes das custom tags vinculadas ao processo (campo Q2). Sempre array — vazio quando não houver tags, nunca null. Adicionar/remover tag reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"string"}},"conteineres":{"type":"array","description":"Lista de contêineres do processo (campo Q2). O item com monitorado: true é o contêiner principal cujos numero/peso_bruto/peso_liquido são refletidos no nível do processo (apenas um por processo). Editar o contêiner (inclusive os campos de demurrage) reflete no próximo GET (cache key do fragmento inclui a associação conteineres — Slice 5). Atenção: não confundir moeda_tarifa: 'USD' com dado intencional quando free_time é null, pois USD é o default do banco.","items":{"type":"object","properties":{"numero":{"type":"string","nullable":true,"description":"Número de identificação do contêiner"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"monitorado":{"type":"boolean","description":"Quando true, este é o contêiner principal do processo (apenas um por processo)"},"free_time":{"type":"integer","nullable":true,"description":"Free time em dias contratado com o armador"},"tarifa_demurrage":{"type":"string","nullable":true,"description":"Tarifa de demurrage por dia após o free time (decimal 15,2 serializado como string)"},"moeda_tarifa":{"type":"string","nullable":true,"enum":["BRL","USD"],"description":"Moeda da tarifa_demurrage (BRL ou USD). Default USD no banco — não confundir com dado intencional quando free_time é null"},"inicio_free_time":{"type":"string","format":"date","nullable":true,"description":"Data de início do free time (ISO 8601)"},"data_devolucao":{"type":"string","format":"date","nullable":true,"description":"Data de devolução do contêiner ao armador (ISO 8601)"}}}},"ordem_de_compra":{"type":"object","nullable":true,"description":"Ordem de Compra vinculada ao processo e itens alocados (campo Q2, Slice 4). Substitui os campos legados codigo_purchase_order/data_purchase_order (strings livres, deprecados) pelo vínculo estruturado 1:1 com a OC. Omitido (chave ausente, não null) quando não há OC vinculada. Renderizado fora do fragmento cacheado por-processo (sempre resolve no GET, padrão di/anexos — Slice 4).","properties":{"id":{"type":"integer","description":"ID da Ordem de Compra"},"numero":{"type":"string","description":"Número identificador da Ordem de Compra (OrdemDeCompra#numero)"},"itens":{"type":"array","description":"Itens da OC alocados ao processo. Array vazio quando a OC está vinculada mas sem itens alocados.","items":{"type":"object","properties":{"id":{"type":"string","description":"ID do vínculo item-OC-processo (UUID)"},"item_ordem_de_compra_id":{"type":"integer","description":"ID do item da Ordem de Compra alocado"},"quantidade_alocada":{"type":"string","description":"Quantidade alocada ao processo (decimal 15,4 serializado como string)"}}}}}},"notas_fiscais_vinculadas":{"type":"array","description":"NF-es vinculadas ao processo — a mesma lista da seção \"NF-es vinculadas\" da tela: notas com este processo atribuído, ou sem processo e com a mesma DI/DUIMP do processo, nas situações aceita e finalizada, em ordem de id. Sempre array — vazio quando não há nota, nunca null. Renderizado fora do fragmento cacheado por-processo: vincular, desvincular ou mudar a situação da nota reflete no próximo GET.","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID da NF-e"},"numero":{"type":"integer","nullable":true,"description":"Número da NF-e"},"serie":{"type":"integer","nullable":true,"description":"Série da NF-e"},"chave_acesso":{"type":"string","nullable":true,"description":"Chave de acesso de 44 dígitos. Null quando a nota não tem chave gravada."},"tipo":{"type":"string","nullable":true,"enum":["entrada","saida"],"description":"Tipo da NF-e: entrada ou saida"},"data_emissao":{"type":"string","format":"date-time","description":"Data e hora de emissão (ISO 8601)"},"valor_total":{"type":"number","format":"float","description":"Total da NF-e com 2 casas decimais — o mesmo valor da coluna \"Total da NF-e\" da tela"},"situacao":{"type":"string","enum":["aceita","finalizada"],"description":"Situação da NF-e: aceita ou finalizada"}},"required":["id","numero","serie","chave_acesso","tipo","data_emissao","valor_total","situacao"]}}},"required":["id","numero","notas_fiscais_vinculadas"]},"ErrosEstruturados":{"type":"object","description":"Envelope de erro de validação da API v2 de processos. Cada chave é um JSON Pointer para o campo recusado e o valor é a mensagem correspondente.","properties":{"errors":{"type":"object","description":"Objeto com os erros de validação no formato JSON Pointer","additionalProperties":{"type":"string"}}},"required":["errors"]}}},"paths":{"/processos/{processo_id}/ordem_de_compra":{"post":{"summary":"Vincula ordem de compra ao processo","tags":["15. ⚓ Processos de Comex"],"description":"**Vincula uma ordem de compra a um processo existente**\n\nInforme **exatamente um** identificador dentro da raiz `ordem_de_compra`:\n\n| Chave | Resolve |\n|---|---|\n| `numero` | Ordem de compra pelo número (busca exata, entre as OCs da empresa) |\n| `id` | Ordem de compra pelo id |\n\n**Requer permissão:** o usuário precisa ter permissão de escrita em \"processos\". Sem ela a\nresposta é **403**, com o envelope `{\"message\": \"Você não tem autorização para acessar esta página.\"}`.\n\n**Status 200, não 201:** o processo já existia — o vínculo altera um processo, não cria recurso novo.\n\n**O 200 confirma o vínculo, não a alocação dos itens.** O bloco `ordem_de_compra` da resposta\ntraz a OC vinculada; a alocação de itens ao processo é feita à parte. Reconsulte\n`GET /processos/{uuid}` para acompanhar.\n\n**Nenhum identificador informado** (ex: `{\"ordem_de_compra\": {\"numero\": \"\"}}`) → 422 no ponteiro\n`/ordem_de_compra`. **Raiz `ordem_de_compra` ausente ou vazia** → 400\n(`ActionController::ParameterMissing`), com envelope diferente do 422.\n\n**Mais de um identificador** → 422 no ponteiro `/ordem_de_compra`, listando o que foi recebido.\n\n**A API não substitui ordem de compra já vinculada.** Processo que já tem OC devolve 422 em\n`/ordem_de_compra`. Reenviar o mesmo vínculo que já existe é idempotente (200, sem alteração).\n\n**Processo inexistente ou de outra empresa** → 404 **sem corpo**.","parameters":[{"name":"processo_id","in":"path","format":"uuid","required":true,"description":"UUID do processo (campo `uuid` devolvido pelo GET /processos)","schema":{"type":"string"}}],"responses":{"200":{"description":"Vínculo aplicado — processo atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Processo"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Processo inexistente ou de outra empresa — sem corpo"},"422":{"description":"Erro de validação","content":{"Processo já possui ordem de compra":{},"Nenhum identificador informado":{},"Mais de um identificador":{},"Ordem de compra inexistente":{},"application/json":{"schema":{"$ref":"#/components/schemas/ErrosEstruturados"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ordem_de_compra":{"type":"object","description":"Informe exatamente uma das chaves abaixo.","properties":{"numero":{"type":"string","description":"Número identificador da ordem de compra."},"id":{"type":"integer","description":"ID da ordem de compra."}}}},"required":["ordem_de_compra"]}}},"required":true}}}}}
```

## Desvincula a ordem de compra do processo

> \*\*Desvincula a ordem de compra de um processo existente\*\*\
> \
> Remove o vínculo da ordem de compra com o processo \*\*e\*\* os itens dessa ordem que estavam\
> alocados nele. A ordem de compra em si não é apagada nem alterada: ela volta a poder ser\
> vinculada, a este ou a outro processo, por \`POST /processos/{uuid}/ordem\_de\_compra\`.\
> \
> \*\*Sem corpo na requisição:\*\* a ordem desvinculada é sempre a que está vinculada ao processo.\
> \
> \*\*Requer permissão:\*\* o usuário precisa ter permissão de escrita em "processos". Sem ela a\
> resposta é \*\*403\*\*, com o envelope \`{"message": "Você não tem autorização para realizar esta ação."}\`.\
> \
> \*\*Status 200:\*\* devolve o processo atualizado, no mesmo formato do \`GET /processos/{uuid}\`.\
> Sem outra ordem alocada, o bloco \`ordem\_de\_compra\` some da resposta. Se o processo tiver itens\
> de \*\*outra\*\* ordem de compra alocados, eles permanecem e essa ordem passa a aparecer em\
> \`ordem\_de\_compra\`.\
> \
> \*\*Tudo ou nada:\*\* se algum item da ordem já estiver consolidado na DI ou DUIMP do processo,\
> \*\*nada\*\* é removido e a resposta é 422 no ponteiro \`/ordem\_de\_compra/itens\`, com o item e o\
> motivo do bloqueio.\
> \
> \*\*Processo sem ordem de compra vinculada\*\* → 422 no ponteiro \`/ordem\_de\_compra\`. Vale também\
> para processo que só tem itens alocados individualmente pela tela do processo: a API não os\
> remove, mesmo que o \`GET /processos/{uuid}\` mostre uma ordem de compra. Uma segunda chamada\
> depois de desvincular com sucesso cai neste mesmo 422.\
> \
> \*\*Processo inexistente ou de outra empresa\*\* → 404 \*\*sem corpo\*\*.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"15. ⚓ Processos de Comex","description":"**Gestão completa de comércio exterior**\nControle end-to-end de processos de importação e exportação.\n**Cobertura:**\n- Processos de importação e exportação\n- Controle documental completo\n- Gestão de câmbio e remessas\n- Drawback e regimes especiais"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}},"schemas":{"Processo":{"type":"object","description":"Processo de comércio exterior serializado pela API v2. Mesma forma devolvida pelo item do GET /processos, pelo 201 do POST /processos e pelos 200 dos endpoints de vínculo de documento e de ordem de compra.","properties":{"id":{"type":"integer","description":"ID do processo"},"uuid":{"type":"string","format":"uuid","description":"Identificador público do processo (usado nos paths de vínculo)"},"numero":{"type":"string","description":"Código do processo"},"descricao":{"type":"string","nullable":true,"description":"Descrição do processo"},"data_criacao":{"type":"string","description":"Data e hora de criação"},"cliente":{"type":"string","nullable":true,"description":"Razão social do cliente"},"modalidade":{"type":"string","nullable":true,"description":"Modalidade do processo"},"tipo":{"type":"string","nullable":true,"description":"Tipo (importação/exportação)"},"via":{"type":"string","nullable":true,"description":"Via de transporte (marítima/aérea/terrestre)"},"categoria":{"type":"string","nullable":true,"description":"Categoria do processo"},"etapa":{"type":"string","nullable":true,"description":"Etapa atual do processo"},"canal":{"type":"string","nullable":true,"description":"Canal de parametrização"},"vmle":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de embarque"},"frete":{"type":"number","format":"float","nullable":true,"description":"Valor do frete"},"seguro":{"type":"number","format":"float","nullable":true,"description":"Valor do seguro"},"vmld":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de descarga"},"fornecedor":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — apesar do nome, devolve o IMPORTADOR, não o fornecedor: documento e razão social no formato \"<documento> - <razão social>\" (só a razão social quando não há documento; nome, tipo e valor mantidos por compatibilidade). O fornecedor principal do processo está em stakeholder_fornecedor; a lista de fornecedores, no array fornecedores; o importador estruturado, em importador."},"container":{"type":"string","nullable":true,"description":"Número do container"},"outra_referencia":{"type":"string","nullable":true,"description":"Outra referência"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento"},"data_cambio_antecipacao":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio de antecipação"},"codigo_purchase_order":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra (numero). Código da Purchase Order (string livre legada, mantido por compatibilidade)."},"data_purchase_order":{"type":"string","format":"date","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra. Data da Purchase Order (string livre legada, mantido por compatibilidade)."},"observacao":{"type":"string","nullable":true,"description":"Observações"},"companhia_aerea":{"type":"string","nullable":true,"description":"Companhia aérea"},"numero_do_voo":{"type":"string","nullable":true,"description":"Número do voo"},"navio":{"type":"string","nullable":true,"description":"Nome do navio"},"placa_do_veiculo_transportador":{"type":"string","nullable":true,"description":"Placa do veículo"},"armador":{"type":"string","nullable":true,"description":"Armador"},"conhecimento_de_embarque":{"type":"string","nullable":true,"description":"Conhecimento de embarque"},"pais_procedencia":{"type":"string","nullable":true,"description":"País de procedência"},"embarque":{"type":"string","nullable":true,"description":"Local de embarque"},"data_embarque":{"type":"string","format":"date","nullable":true,"description":"Data de embarque"},"pais_destino":{"type":"string","nullable":true,"description":"País de destino"},"desembarque":{"type":"string","nullable":true,"description":"Local de desembarque"},"data_chegada":{"type":"string","format":"date","nullable":true,"description":"Data de chegada"},"eta":{"type":"string","format":"date","nullable":true,"description":"ETA (Estimated Time of Arrival)"},"agente_de_carga":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o objeto agente_carga (id/razao_social/documento). Agente de carga (string legada, mantida por compatibilidade)."},"stakeholder_agente_carga_id":{"type":"integer","nullable":true,"description":"ID do stakeholder agente de carga"},"bl":{"type":"string","nullable":true,"description":"Número do BL (via marítima)"},"data_emissao_bl":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do BL"},"awb":{"type":"string","nullable":true,"description":"Número do AWB (via aérea)"},"data_emissao_awb":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do AWB"},"crt":{"type":"string","nullable":true,"description":"Número do CRT (via terrestre)"},"data_emissao_crt":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do CRT"},"fci":{"type":"string","nullable":true,"description":"FCI"},"incoterm":{"type":"string","nullable":true,"description":"Incoterm utilizado"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"status_container":{"type":"string","nullable":true,"description":"Status do container"},"presenca_carga":{"type":"string","nullable":true,"description":"Presença da carga"},"numero_invoice":{"type":"string","nullable":true,"description":"Número da invoice"},"valor_invoice":{"type":"number","format":"float","nullable":true,"description":"Valor da invoice"},"vencimento_invoice":{"type":"string","format":"date","nullable":true,"description":"Vencimento da invoice"},"data_cambio_saldo":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio do saldo"},"terminal_de_armazenagem":{"type":"string","nullable":true,"description":"Terminal de armazenagem"},"data_pedido":{"type":"string","format":"date","nullable":true,"description":"Data do pedido (AAAA-MM-DD). Mesmo campo aceito no POST/PATCH."},"numerario_cambio":{"type":"string","nullable":true,"description":"Numerário de câmbio (decimal serializado como string). Mesmo campo aceito no POST/PATCH."},"moeda_codigo_iso":{"type":"string","nullable":true,"description":"Sigla ISO da moeda do processo (ex: USD). Espelha o campo moeda_codigo_iso do POST/PATCH."},"etapa_processo_id":{"type":"string","format":"uuid","description":"Identificador da etapa atual do processo. A chave etapa continua devolvendo a descrição."},"importador":{"type":"object","nullable":true,"description":"Stakeholder importador do processo. Null quando não há importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do importador"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do importador (numero_do_documento na origem)."}}},"stakeholder_fornecedor":{"type":"object","nullable":true,"description":"Stakeholder fornecedor do processo (coluna stakeholder_fornecedor_id, preenchida por fornecedor_documento/fornecedor_razao_social no POST). Null quando não há fornecedor. Não confundir com a chave legada fornecedor, que devolve o importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}},"stakeholder_cliente":{"type":"object","nullable":true,"description":"Stakeholder cliente do processo. Null quando não há cliente. A chave cliente continua devolvendo só a razão social.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do cliente"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do cliente (numero_do_documento na origem)."}}},"anexos":{"type":"array","nullable":true,"description":"Anexos do processo","items":{"type":"object","properties":{"anexo":{"type":"object","properties":{"url":{"type":"string","description":"URL do anexo"}}}}}},"di":{"type":"object","nullable":true,"description":"Declaração de Importação","properties":{"codigo":{"type":"string","nullable":true,"description":"Código da DI"},"data_de_desembaraco":{"type":"string","format":"date","nullable":true,"description":"Data de desembaraço"},"data_registro":{"type":"string","format":"date","nullable":true,"description":"Data de registro"}}},"responsavel":{"type":"object","nullable":true,"description":"Pessoa responsável pelo processo (campo Q2). A edição da Pessoa vinculada reflete no próximo GET (cache key do fragmento inclui a associação — Slice 5).","properties":{"id":{"type":"integer","description":"ID da Pessoa"},"nome":{"type":"string","description":"Nome da Pessoa"},"foto_url":{"type":"string","nullable":true,"description":"URL da foto de perfil (CarrierWave). Null se sem upload."}}},"despachante":{"type":"object","nullable":true,"description":"Stakeholder despachante do processo (campo Q2).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do despachante"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do despachante (numero_do_documento na origem)."}}},"agente_carga":{"type":"object","nullable":true,"description":"Objeto stakeholder do agente de carga (campo Q2). Coexiste com agente_de_carga (string legada) e stakeholder_agente_carga_id (int legado).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do agente de carga"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do agente de carga."}}},"data_embarque_previsto":{"type":"string","format":"date","nullable":true,"description":"ETD — data prevista de embarque (campo Q2)."},"incoterm_legado":{"type":"string","nullable":true,"description":"Valor de incoterm fora do enum normalizado (ex: 'EXX'). Coexiste com incoterm (campo Q2)."},"fornecedores":{"type":"array","description":"Fornecedores M:N do processo (campo Q2). Sempre array — vazio quando não houver fornecedores, nunca null. Coexiste com o campo legado 'fornecedor' (string derivada do importador). Adicionar/remover fornecedor reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID do Stakeholder fornecedor"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}}},"tags":{"type":"array","description":"Nomes das custom tags vinculadas ao processo (campo Q2). Sempre array — vazio quando não houver tags, nunca null. Adicionar/remover tag reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"string"}},"conteineres":{"type":"array","description":"Lista de contêineres do processo (campo Q2). O item com monitorado: true é o contêiner principal cujos numero/peso_bruto/peso_liquido são refletidos no nível do processo (apenas um por processo). Editar o contêiner (inclusive os campos de demurrage) reflete no próximo GET (cache key do fragmento inclui a associação conteineres — Slice 5). Atenção: não confundir moeda_tarifa: 'USD' com dado intencional quando free_time é null, pois USD é o default do banco.","items":{"type":"object","properties":{"numero":{"type":"string","nullable":true,"description":"Número de identificação do contêiner"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"monitorado":{"type":"boolean","description":"Quando true, este é o contêiner principal do processo (apenas um por processo)"},"free_time":{"type":"integer","nullable":true,"description":"Free time em dias contratado com o armador"},"tarifa_demurrage":{"type":"string","nullable":true,"description":"Tarifa de demurrage por dia após o free time (decimal 15,2 serializado como string)"},"moeda_tarifa":{"type":"string","nullable":true,"enum":["BRL","USD"],"description":"Moeda da tarifa_demurrage (BRL ou USD). Default USD no banco — não confundir com dado intencional quando free_time é null"},"inicio_free_time":{"type":"string","format":"date","nullable":true,"description":"Data de início do free time (ISO 8601)"},"data_devolucao":{"type":"string","format":"date","nullable":true,"description":"Data de devolução do contêiner ao armador (ISO 8601)"}}}},"ordem_de_compra":{"type":"object","nullable":true,"description":"Ordem de Compra vinculada ao processo e itens alocados (campo Q2, Slice 4). Substitui os campos legados codigo_purchase_order/data_purchase_order (strings livres, deprecados) pelo vínculo estruturado 1:1 com a OC. Omitido (chave ausente, não null) quando não há OC vinculada. Renderizado fora do fragmento cacheado por-processo (sempre resolve no GET, padrão di/anexos — Slice 4).","properties":{"id":{"type":"integer","description":"ID da Ordem de Compra"},"numero":{"type":"string","description":"Número identificador da Ordem de Compra (OrdemDeCompra#numero)"},"itens":{"type":"array","description":"Itens da OC alocados ao processo. Array vazio quando a OC está vinculada mas sem itens alocados.","items":{"type":"object","properties":{"id":{"type":"string","description":"ID do vínculo item-OC-processo (UUID)"},"item_ordem_de_compra_id":{"type":"integer","description":"ID do item da Ordem de Compra alocado"},"quantidade_alocada":{"type":"string","description":"Quantidade alocada ao processo (decimal 15,4 serializado como string)"}}}}}},"notas_fiscais_vinculadas":{"type":"array","description":"NF-es vinculadas ao processo — a mesma lista da seção \"NF-es vinculadas\" da tela: notas com este processo atribuído, ou sem processo e com a mesma DI/DUIMP do processo, nas situações aceita e finalizada, em ordem de id. Sempre array — vazio quando não há nota, nunca null. Renderizado fora do fragmento cacheado por-processo: vincular, desvincular ou mudar a situação da nota reflete no próximo GET.","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID da NF-e"},"numero":{"type":"integer","nullable":true,"description":"Número da NF-e"},"serie":{"type":"integer","nullable":true,"description":"Série da NF-e"},"chave_acesso":{"type":"string","nullable":true,"description":"Chave de acesso de 44 dígitos. Null quando a nota não tem chave gravada."},"tipo":{"type":"string","nullable":true,"enum":["entrada","saida"],"description":"Tipo da NF-e: entrada ou saida"},"data_emissao":{"type":"string","format":"date-time","description":"Data e hora de emissão (ISO 8601)"},"valor_total":{"type":"number","format":"float","description":"Total da NF-e com 2 casas decimais — o mesmo valor da coluna \"Total da NF-e\" da tela"},"situacao":{"type":"string","enum":["aceita","finalizada"],"description":"Situação da NF-e: aceita ou finalizada"}},"required":["id","numero","serie","chave_acesso","tipo","data_emissao","valor_total","situacao"]}}},"required":["id","numero","notas_fiscais_vinculadas"]},"ErrosEstruturados":{"type":"object","description":"Envelope de erro de validação da API v2 de processos. Cada chave é um JSON Pointer para o campo recusado e o valor é a mensagem correspondente.","properties":{"errors":{"type":"object","description":"Objeto com os erros de validação no formato JSON Pointer","additionalProperties":{"type":"string"}}},"required":["errors"]}}},"paths":{"/processos/{processo_id}/ordem_de_compra":{"delete":{"summary":"Desvincula a ordem de compra do processo","tags":["15. ⚓ Processos de Comex"],"description":"**Desvincula a ordem de compra de um processo existente**\n\nRemove o vínculo da ordem de compra com o processo **e** os itens dessa ordem que estavam\nalocados nele. A ordem de compra em si não é apagada nem alterada: ela volta a poder ser\nvinculada, a este ou a outro processo, por `POST /processos/{uuid}/ordem_de_compra`.\n\n**Sem corpo na requisição:** a ordem desvinculada é sempre a que está vinculada ao processo.\n\n**Requer permissão:** o usuário precisa ter permissão de escrita em \"processos\". Sem ela a\nresposta é **403**, com o envelope `{\"message\": \"Você não tem autorização para realizar esta ação.\"}`.\n\n**Status 200:** devolve o processo atualizado, no mesmo formato do `GET /processos/{uuid}`.\nSem outra ordem alocada, o bloco `ordem_de_compra` some da resposta. Se o processo tiver itens\nde **outra** ordem de compra alocados, eles permanecem e essa ordem passa a aparecer em\n`ordem_de_compra`.\n\n**Tudo ou nada:** se algum item da ordem já estiver consolidado na DI ou DUIMP do processo,\n**nada** é removido e a resposta é 422 no ponteiro `/ordem_de_compra/itens`, com o item e o\nmotivo do bloqueio.\n\n**Processo sem ordem de compra vinculada** → 422 no ponteiro `/ordem_de_compra`. Vale também\npara processo que só tem itens alocados individualmente pela tela do processo: a API não os\nremove, mesmo que o `GET /processos/{uuid}` mostre uma ordem de compra. Uma segunda chamada\ndepois de desvincular com sucesso cai neste mesmo 422.\n\n**Processo inexistente ou de outra empresa** → 404 **sem corpo**.","parameters":[{"name":"processo_id","in":"path","format":"uuid","required":true,"description":"UUID do processo (campo `uuid` devolvido pelo GET /processos)","schema":{"type":"string"}}],"responses":{"200":{"description":"Ordem de compra desvinculada — processo atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Processo"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Processo inexistente ou de outra empresa — sem corpo"},"422":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrosEstruturados"}}}}}}}}}
```

## Lista processos de comércio exterior

> \*\*Lista processos de comércio exterior\*\*\
> \
> Retorna todos os processos de importação e exportação do usuário autenticado,\
> ordenados por data de criação (mais recentes primeiro), com todos os detalhes\
> de cada processo, incluindo informações de pré-embarque, embarque e despacho aduaneiro.\
> \
> \*\*Requer permissão:\*\* O usuário precisa ter permissão de leitura em "processos".\
> \
> \*\*Paginação:\*\*\
> \- \`page\`: número da página (padrão: 1)\
> \- \`per\_page\`: itens por página — padrão e máximo: 300. Valor acima de 300 é limitado a 300\
> &#x20; (siga \`pagination.next\_page\` para o restante). Valor que não seja inteiro positivo devolve 422.\
> \
> \*\*Filtros (todos opcionais, combinados por E):\*\* sem nenhum filtro a lista traz todos os\
> processos do usuário, inclusive os \`cancelado\`. Parâmetro vazio é ignorado; parâmetro\
> desconhecido é ignorado. Formato inválido devolve \*\*um único 422\*\* com todos os erros, no\
> envelope \`{"errors": {"/\<parâmetro>": "mensagem"}}\`.\
> \- Texto (busca parcial, sem distinção de maiúsculas): \`codigo\`, \`conteiner\`, \`bl\`,\
> &#x20; \`numero\_invoice\`, \`di\_duimp\` (número da DI ou da DUIMP) e \`busca\` (código, BL, invoice, DI,\
> &#x20; cliente e fornecedores)\
> \- Datas no formato \`AAAA-MM-DD\`: \`data\_criacao\_inicio\`/\`data\_criacao\_fim\`,\
> &#x20; \`data\_embarque\_inicio\`/\`data\_embarque\_fim\`, \`data\_chegada\_inicio\`/\`data\_chegada\_fim\`\
> \- Identificadores: \`etapa\_processo\_id\` (UUID), \`cliente\_id\`, \`fornecedor\_id\` e \`tag\_id\`\
> &#x20; (inteiros positivos). \`fornecedor\_id\` casa o fornecedor do processo, o importador ou os\
> &#x20; fornecedores M:N. Id de outra empresa não dá erro: devolve lista vazia.\
> \- Valores fechados: \`tipo\` (\`importacao\`, \`exportacao\`, \`aquisicao\`) e \`status\_finalizacao\`\
> &#x20; (\`em\_andamento\`, \`concluido\`, \`cancelado\`; aceita lista separada por vírgula)\
> \
> \*\*Informações retornadas:\*\*\
> \- Dados gerais do processo (número, descrição, cliente, modalidade, tipo)\
> \- Dados de pré-embarque (fornecedores, container, ordem de compra)\
> \- Dados de embarque (navio/voo, BL/AWB, datas, incoterm)\
> \- Dados de despacho aduaneiro (invoice, terminal de armazenagem)\
> \- DI (Declaração de Importação) quando disponível\
> \- Anexos do processo\
> \- Lista de contêineres com dados de demurrage\
> \- Ordem de Compra vinculada (\`ordem\_de\_compra\`) e itens alocados — substitui\
> &#x20; os campos legados \`codigo\_purchase\_order\`/\`data\_purchase\_order\` (deprecados)\
> \
> \*\*Campos deprecados\*\* (mantidos por compatibilidade — \`deprecated: true\`):\
> \- \`fornecedor\` (string) → usar o array \`fornecedores\` (objetos estruturados)\
> \- \`agente\_de\_carga\` (string) → usar o objeto \`agente\_carga\`\
> \- \`codigo\_purchase\_order\`/\`data\_purchase\_order\` → usar o bloco \`ordem\_de\_compra\`\
> \
> \*\*Contêiner principal:\*\* dentro do array \`conteineres\`, o item com \`monitorado: true\`\
> é o contêiner principal do processo. Os campos \`container\`, \`peso\_bruto\` e\
> \`peso\_liquido\` no nível do processo são derivados desse contêiner principal\
> (ou do primeiro contêiner quando não houver monitorado).\
> \
> \*\*Cache do fragmento:\*\* o fragmento por-processo é cacheado com uma cache key\
> que inclui as associações \`responsavel\`, \`fornecedores\`, \`tags\`, \`conteineres\`,\
> cliente, fornecedor, importador, etapa e moeda. Editar essas associações\
> (inclusive os campos de demurrage do contêiner) reflete no próximo GET, mesmo sem\
> tocar o processo pai. O bloco \`ordem\_de\_compra\` é renderizado fora do fragmento\
> cacheado (sempre resolve).

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"15. ⚓ Processos de Comex","description":"**Gestão completa de comércio exterior**\nControle end-to-end de processos de importação e exportação.\n**Cobertura:**\n- Processos de importação e exportação\n- Controle documental completo\n- Gestão de câmbio e remessas\n- Drawback e regimes especiais"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}},"schemas":{"Processo":{"type":"object","description":"Processo de comércio exterior serializado pela API v2. Mesma forma devolvida pelo item do GET /processos, pelo 201 do POST /processos e pelos 200 dos endpoints de vínculo de documento e de ordem de compra.","properties":{"id":{"type":"integer","description":"ID do processo"},"uuid":{"type":"string","format":"uuid","description":"Identificador público do processo (usado nos paths de vínculo)"},"numero":{"type":"string","description":"Código do processo"},"descricao":{"type":"string","nullable":true,"description":"Descrição do processo"},"data_criacao":{"type":"string","description":"Data e hora de criação"},"cliente":{"type":"string","nullable":true,"description":"Razão social do cliente"},"modalidade":{"type":"string","nullable":true,"description":"Modalidade do processo"},"tipo":{"type":"string","nullable":true,"description":"Tipo (importação/exportação)"},"via":{"type":"string","nullable":true,"description":"Via de transporte (marítima/aérea/terrestre)"},"categoria":{"type":"string","nullable":true,"description":"Categoria do processo"},"etapa":{"type":"string","nullable":true,"description":"Etapa atual do processo"},"canal":{"type":"string","nullable":true,"description":"Canal de parametrização"},"vmle":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de embarque"},"frete":{"type":"number","format":"float","nullable":true,"description":"Valor do frete"},"seguro":{"type":"number","format":"float","nullable":true,"description":"Valor do seguro"},"vmld":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de descarga"},"fornecedor":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — apesar do nome, devolve o IMPORTADOR, não o fornecedor: documento e razão social no formato \"<documento> - <razão social>\" (só a razão social quando não há documento; nome, tipo e valor mantidos por compatibilidade). O fornecedor principal do processo está em stakeholder_fornecedor; a lista de fornecedores, no array fornecedores; o importador estruturado, em importador."},"container":{"type":"string","nullable":true,"description":"Número do container"},"outra_referencia":{"type":"string","nullable":true,"description":"Outra referência"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento"},"data_cambio_antecipacao":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio de antecipação"},"codigo_purchase_order":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra (numero). Código da Purchase Order (string livre legada, mantido por compatibilidade)."},"data_purchase_order":{"type":"string","format":"date","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra. Data da Purchase Order (string livre legada, mantido por compatibilidade)."},"observacao":{"type":"string","nullable":true,"description":"Observações"},"companhia_aerea":{"type":"string","nullable":true,"description":"Companhia aérea"},"numero_do_voo":{"type":"string","nullable":true,"description":"Número do voo"},"navio":{"type":"string","nullable":true,"description":"Nome do navio"},"placa_do_veiculo_transportador":{"type":"string","nullable":true,"description":"Placa do veículo"},"armador":{"type":"string","nullable":true,"description":"Armador"},"conhecimento_de_embarque":{"type":"string","nullable":true,"description":"Conhecimento de embarque"},"pais_procedencia":{"type":"string","nullable":true,"description":"País de procedência"},"embarque":{"type":"string","nullable":true,"description":"Local de embarque"},"data_embarque":{"type":"string","format":"date","nullable":true,"description":"Data de embarque"},"pais_destino":{"type":"string","nullable":true,"description":"País de destino"},"desembarque":{"type":"string","nullable":true,"description":"Local de desembarque"},"data_chegada":{"type":"string","format":"date","nullable":true,"description":"Data de chegada"},"eta":{"type":"string","format":"date","nullable":true,"description":"ETA (Estimated Time of Arrival)"},"agente_de_carga":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o objeto agente_carga (id/razao_social/documento). Agente de carga (string legada, mantida por compatibilidade)."},"stakeholder_agente_carga_id":{"type":"integer","nullable":true,"description":"ID do stakeholder agente de carga"},"bl":{"type":"string","nullable":true,"description":"Número do BL (via marítima)"},"data_emissao_bl":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do BL"},"awb":{"type":"string","nullable":true,"description":"Número do AWB (via aérea)"},"data_emissao_awb":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do AWB"},"crt":{"type":"string","nullable":true,"description":"Número do CRT (via terrestre)"},"data_emissao_crt":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do CRT"},"fci":{"type":"string","nullable":true,"description":"FCI"},"incoterm":{"type":"string","nullable":true,"description":"Incoterm utilizado"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"status_container":{"type":"string","nullable":true,"description":"Status do container"},"presenca_carga":{"type":"string","nullable":true,"description":"Presença da carga"},"numero_invoice":{"type":"string","nullable":true,"description":"Número da invoice"},"valor_invoice":{"type":"number","format":"float","nullable":true,"description":"Valor da invoice"},"vencimento_invoice":{"type":"string","format":"date","nullable":true,"description":"Vencimento da invoice"},"data_cambio_saldo":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio do saldo"},"terminal_de_armazenagem":{"type":"string","nullable":true,"description":"Terminal de armazenagem"},"data_pedido":{"type":"string","format":"date","nullable":true,"description":"Data do pedido (AAAA-MM-DD). Mesmo campo aceito no POST/PATCH."},"numerario_cambio":{"type":"string","nullable":true,"description":"Numerário de câmbio (decimal serializado como string). Mesmo campo aceito no POST/PATCH."},"moeda_codigo_iso":{"type":"string","nullable":true,"description":"Sigla ISO da moeda do processo (ex: USD). Espelha o campo moeda_codigo_iso do POST/PATCH."},"etapa_processo_id":{"type":"string","format":"uuid","description":"Identificador da etapa atual do processo. A chave etapa continua devolvendo a descrição."},"importador":{"type":"object","nullable":true,"description":"Stakeholder importador do processo. Null quando não há importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do importador"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do importador (numero_do_documento na origem)."}}},"stakeholder_fornecedor":{"type":"object","nullable":true,"description":"Stakeholder fornecedor do processo (coluna stakeholder_fornecedor_id, preenchida por fornecedor_documento/fornecedor_razao_social no POST). Null quando não há fornecedor. Não confundir com a chave legada fornecedor, que devolve o importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}},"stakeholder_cliente":{"type":"object","nullable":true,"description":"Stakeholder cliente do processo. Null quando não há cliente. A chave cliente continua devolvendo só a razão social.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do cliente"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do cliente (numero_do_documento na origem)."}}},"anexos":{"type":"array","nullable":true,"description":"Anexos do processo","items":{"type":"object","properties":{"anexo":{"type":"object","properties":{"url":{"type":"string","description":"URL do anexo"}}}}}},"di":{"type":"object","nullable":true,"description":"Declaração de Importação","properties":{"codigo":{"type":"string","nullable":true,"description":"Código da DI"},"data_de_desembaraco":{"type":"string","format":"date","nullable":true,"description":"Data de desembaraço"},"data_registro":{"type":"string","format":"date","nullable":true,"description":"Data de registro"}}},"responsavel":{"type":"object","nullable":true,"description":"Pessoa responsável pelo processo (campo Q2). A edição da Pessoa vinculada reflete no próximo GET (cache key do fragmento inclui a associação — Slice 5).","properties":{"id":{"type":"integer","description":"ID da Pessoa"},"nome":{"type":"string","description":"Nome da Pessoa"},"foto_url":{"type":"string","nullable":true,"description":"URL da foto de perfil (CarrierWave). Null se sem upload."}}},"despachante":{"type":"object","nullable":true,"description":"Stakeholder despachante do processo (campo Q2).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do despachante"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do despachante (numero_do_documento na origem)."}}},"agente_carga":{"type":"object","nullable":true,"description":"Objeto stakeholder do agente de carga (campo Q2). Coexiste com agente_de_carga (string legada) e stakeholder_agente_carga_id (int legado).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do agente de carga"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do agente de carga."}}},"data_embarque_previsto":{"type":"string","format":"date","nullable":true,"description":"ETD — data prevista de embarque (campo Q2)."},"incoterm_legado":{"type":"string","nullable":true,"description":"Valor de incoterm fora do enum normalizado (ex: 'EXX'). Coexiste com incoterm (campo Q2)."},"fornecedores":{"type":"array","description":"Fornecedores M:N do processo (campo Q2). Sempre array — vazio quando não houver fornecedores, nunca null. Coexiste com o campo legado 'fornecedor' (string derivada do importador). Adicionar/remover fornecedor reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID do Stakeholder fornecedor"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}}},"tags":{"type":"array","description":"Nomes das custom tags vinculadas ao processo (campo Q2). Sempre array — vazio quando não houver tags, nunca null. Adicionar/remover tag reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"string"}},"conteineres":{"type":"array","description":"Lista de contêineres do processo (campo Q2). O item com monitorado: true é o contêiner principal cujos numero/peso_bruto/peso_liquido são refletidos no nível do processo (apenas um por processo). Editar o contêiner (inclusive os campos de demurrage) reflete no próximo GET (cache key do fragmento inclui a associação conteineres — Slice 5). Atenção: não confundir moeda_tarifa: 'USD' com dado intencional quando free_time é null, pois USD é o default do banco.","items":{"type":"object","properties":{"numero":{"type":"string","nullable":true,"description":"Número de identificação do contêiner"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"monitorado":{"type":"boolean","description":"Quando true, este é o contêiner principal do processo (apenas um por processo)"},"free_time":{"type":"integer","nullable":true,"description":"Free time em dias contratado com o armador"},"tarifa_demurrage":{"type":"string","nullable":true,"description":"Tarifa de demurrage por dia após o free time (decimal 15,2 serializado como string)"},"moeda_tarifa":{"type":"string","nullable":true,"enum":["BRL","USD"],"description":"Moeda da tarifa_demurrage (BRL ou USD). Default USD no banco — não confundir com dado intencional quando free_time é null"},"inicio_free_time":{"type":"string","format":"date","nullable":true,"description":"Data de início do free time (ISO 8601)"},"data_devolucao":{"type":"string","format":"date","nullable":true,"description":"Data de devolução do contêiner ao armador (ISO 8601)"}}}},"ordem_de_compra":{"type":"object","nullable":true,"description":"Ordem de Compra vinculada ao processo e itens alocados (campo Q2, Slice 4). Substitui os campos legados codigo_purchase_order/data_purchase_order (strings livres, deprecados) pelo vínculo estruturado 1:1 com a OC. Omitido (chave ausente, não null) quando não há OC vinculada. Renderizado fora do fragmento cacheado por-processo (sempre resolve no GET, padrão di/anexos — Slice 4).","properties":{"id":{"type":"integer","description":"ID da Ordem de Compra"},"numero":{"type":"string","description":"Número identificador da Ordem de Compra (OrdemDeCompra#numero)"},"itens":{"type":"array","description":"Itens da OC alocados ao processo. Array vazio quando a OC está vinculada mas sem itens alocados.","items":{"type":"object","properties":{"id":{"type":"string","description":"ID do vínculo item-OC-processo (UUID)"},"item_ordem_de_compra_id":{"type":"integer","description":"ID do item da Ordem de Compra alocado"},"quantidade_alocada":{"type":"string","description":"Quantidade alocada ao processo (decimal 15,4 serializado como string)"}}}}}},"notas_fiscais_vinculadas":{"type":"array","description":"NF-es vinculadas ao processo — a mesma lista da seção \"NF-es vinculadas\" da tela: notas com este processo atribuído, ou sem processo e com a mesma DI/DUIMP do processo, nas situações aceita e finalizada, em ordem de id. Sempre array — vazio quando não há nota, nunca null. Renderizado fora do fragmento cacheado por-processo: vincular, desvincular ou mudar a situação da nota reflete no próximo GET.","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID da NF-e"},"numero":{"type":"integer","nullable":true,"description":"Número da NF-e"},"serie":{"type":"integer","nullable":true,"description":"Série da NF-e"},"chave_acesso":{"type":"string","nullable":true,"description":"Chave de acesso de 44 dígitos. Null quando a nota não tem chave gravada."},"tipo":{"type":"string","nullable":true,"enum":["entrada","saida"],"description":"Tipo da NF-e: entrada ou saida"},"data_emissao":{"type":"string","format":"date-time","description":"Data e hora de emissão (ISO 8601)"},"valor_total":{"type":"number","format":"float","description":"Total da NF-e com 2 casas decimais — o mesmo valor da coluna \"Total da NF-e\" da tela"},"situacao":{"type":"string","enum":["aceita","finalizada"],"description":"Situação da NF-e: aceita ou finalizada"}},"required":["id","numero","serie","chave_acesso","tipo","data_emissao","valor_total","situacao"]}}},"required":["id","numero","notas_fiscais_vinculadas"]},"ErrosEstruturados":{"type":"object","description":"Envelope de erro de validação da API v2 de processos. Cada chave é um JSON Pointer para o campo recusado e o valor é a mensagem correspondente.","properties":{"errors":{"type":"object","description":"Objeto com os erros de validação no formato JSON Pointer","additionalProperties":{"type":"string"}}},"required":["errors"]}}},"paths":{"/processos":{"get":{"summary":"Lista processos de comércio exterior","tags":["15. ⚓ Processos de Comex"],"description":"**Lista processos de comércio exterior**\n\nRetorna todos os processos de importação e exportação do usuário autenticado,\nordenados por data de criação (mais recentes primeiro), com todos os detalhes\nde cada processo, incluindo informações de pré-embarque, embarque e despacho aduaneiro.\n\n**Requer permissão:** O usuário precisa ter permissão de leitura em \"processos\".\n\n**Paginação:**\n- `page`: número da página (padrão: 1)\n- `per_page`: itens por página — padrão e máximo: 300. Valor acima de 300 é limitado a 300\n  (siga `pagination.next_page` para o restante). Valor que não seja inteiro positivo devolve 422.\n\n**Filtros (todos opcionais, combinados por E):** sem nenhum filtro a lista traz todos os\nprocessos do usuário, inclusive os `cancelado`. Parâmetro vazio é ignorado; parâmetro\ndesconhecido é ignorado. Formato inválido devolve **um único 422** com todos os erros, no\nenvelope `{\"errors\": {\"/<parâmetro>\": \"mensagem\"}}`.\n- Texto (busca parcial, sem distinção de maiúsculas): `codigo`, `conteiner`, `bl`,\n  `numero_invoice`, `di_duimp` (número da DI ou da DUIMP) e `busca` (código, BL, invoice, DI,\n  cliente e fornecedores)\n- Datas no formato `AAAA-MM-DD`: `data_criacao_inicio`/`data_criacao_fim`,\n  `data_embarque_inicio`/`data_embarque_fim`, `data_chegada_inicio`/`data_chegada_fim`\n- Identificadores: `etapa_processo_id` (UUID), `cliente_id`, `fornecedor_id` e `tag_id`\n  (inteiros positivos). `fornecedor_id` casa o fornecedor do processo, o importador ou os\n  fornecedores M:N. Id de outra empresa não dá erro: devolve lista vazia.\n- Valores fechados: `tipo` (`importacao`, `exportacao`, `aquisicao`) e `status_finalizacao`\n  (`em_andamento`, `concluido`, `cancelado`; aceita lista separada por vírgula)\n\n**Informações retornadas:**\n- Dados gerais do processo (número, descrição, cliente, modalidade, tipo)\n- Dados de pré-embarque (fornecedores, container, ordem de compra)\n- Dados de embarque (navio/voo, BL/AWB, datas, incoterm)\n- Dados de despacho aduaneiro (invoice, terminal de armazenagem)\n- DI (Declaração de Importação) quando disponível\n- Anexos do processo\n- Lista de contêineres com dados de demurrage\n- Ordem de Compra vinculada (`ordem_de_compra`) e itens alocados — substitui\n  os campos legados `codigo_purchase_order`/`data_purchase_order` (deprecados)\n\n**Campos deprecados** (mantidos por compatibilidade — `deprecated: true`):\n- `fornecedor` (string) → usar o array `fornecedores` (objetos estruturados)\n- `agente_de_carga` (string) → usar o objeto `agente_carga`\n- `codigo_purchase_order`/`data_purchase_order` → usar o bloco `ordem_de_compra`\n\n**Contêiner principal:** dentro do array `conteineres`, o item com `monitorado: true`\né o contêiner principal do processo. Os campos `container`, `peso_bruto` e\n`peso_liquido` no nível do processo são derivados desse contêiner principal\n(ou do primeiro contêiner quando não houver monitorado).\n\n**Cache do fragmento:** o fragmento por-processo é cacheado com uma cache key\nque inclui as associações `responsavel`, `fornecedores`, `tags`, `conteineres`,\ncliente, fornecedor, importador, etapa e moeda. Editar essas associações\n(inclusive os campos de demurrage do contêiner) reflete no próximo GET, mesmo sem\ntocar o processo pai. O bloco `ordem_de_compra` é renderizado fora do fragmento\ncacheado (sempre resolve).","parameters":[{"name":"page","in":"query","description":"Número da página (padrão: 1)","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"description":"Itens por página — padrão e máximo: 300. Acima de 300 é limitado a 300.","schema":{"type":"integer"}},{"name":"codigo","in":"query","required":false,"description":"Código do processo (parcial)","schema":{"type":"string"}},{"name":"etapa_processo_id","in":"query","schema":{"type":"string","format":"uuid"},"required":false,"description":"Identificador da etapa atual (UUID)"},{"name":"conteiner","in":"query","required":false,"description":"Número do contêiner (parcial)","schema":{"type":"string"}},{"name":"data_criacao_inicio","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Criados a partir desta data (AAAA-MM-DD)"},{"name":"data_criacao_fim","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Criados até esta data (AAAA-MM-DD)"},{"name":"data_embarque_inicio","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Embarque a partir desta data (AAAA-MM-DD)"},{"name":"data_embarque_fim","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Embarque até esta data (AAAA-MM-DD)"},{"name":"data_chegada_inicio","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Chegada a partir desta data (AAAA-MM-DD)"},{"name":"data_chegada_fim","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Chegada até esta data (AAAA-MM-DD)"},{"name":"di_duimp","in":"query","required":false,"description":"Número da DI ou da DUIMP (parcial)","schema":{"type":"string"}},{"name":"tipo","in":"query","schema":{"type":"string","enum":["importacao","exportacao","aquisicao"]},"required":false,"description":"Tipo do processo"},{"name":"status_finalizacao","in":"query","required":false,"description":"em_andamento, concluido ou cancelado; aceita lista separada por vírgula","schema":{"type":"string"}},{"name":"bl","in":"query","required":false,"description":"BL/AWB/CRT (parcial)","schema":{"type":"string"}},{"name":"numero_invoice","in":"query","required":false,"description":"Número da invoice (parcial)","schema":{"type":"string"}},{"name":"cliente_id","in":"query","required":false,"description":"ID do cliente","schema":{"type":"integer"}},{"name":"fornecedor_id","in":"query","required":false,"description":"ID do fornecedor (casa fornecedor do processo, importador ou fornecedores M:N)","schema":{"type":"integer"}},{"name":"tag_id","in":"query","required":false,"description":"ID da tag","schema":{"type":"integer"}},{"name":"busca","in":"query","required":false,"description":"Busca rápida em código, BL, invoice, DI, cliente e fornecedores","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de processos","content":{"application/json":{"schema":{"type":"object","properties":{"processos":{"type":"array","description":"Lista de processos","items":{"$ref":"#/components/schemas/Processo"}},"pagination":{"type":"object","description":"Informações de paginação","properties":{"total":{"type":"integer","description":"Total de registros"},"previous_page":{"type":"string","nullable":true,"description":"URL da página anterior"},"next_page":{"type":"string","nullable":true,"description":"URL da próxima página"}}}},"required":["processos","pagination"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Sem permissão","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Parâmetro de filtro ou de paginação com formato inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrosEstruturados"}}}}}}}}}
```

## Cria processo de comércio exterior

> \*\*Cria um processo de comércio exterior\*\*\
> \
> Cria o processo para a empresa autenticada e devolve o processo criado com a mesma\
> estrutura do \`GET /processos\`. Apenas \`tipo\` e \`via\` são obrigatórios.\
> \
> \*\*Requer permissão:\*\* o usuário precisa ter permissão de escrita em "processos". Sem ela a\
> resposta é \*\*403\*\*, com o envelope \`{"message": "Você não tem autorização para acessar esta página."}\`.\
> \
> \*\*Raiz \`processo\` ausente\*\* → \*\*400\*\*: o Rails recusa a requisição antes do endpoint\
> (\`ActionController::ParameterMissing\`), com envelope diferente do 422.\
> \
> \*\*Código (\`codigo\`):\*\* opcional. Quando ausente ou em branco, o servidor gera o próximo\
> código sequencial da empresa sob trava, e o código gerado volta no campo \`numero\` da resposta.\
> \
> \*\*Etapa do processo:\*\* preenchida automaticamente com a etapa marcada como inicial na\
> empresa. Se nenhuma etapa estiver cadastrada, a criação falha com 422 no ponteiro\
> \`/etapa\_processo\` — cadastre ao menos uma etapa antes de usar este endpoint.\
> \
> \*\*Moeda (\`moeda\_codigo\_iso\`):\*\* informe a sigla ISO (ex: \`USD\`). A busca é exata sobre o\
> cadastro de moedas, com a sigla normalizada para maiúsculas. Sigla inexistente devolve 422\
> em \`/moeda\_codigo\_iso\` — \*\*não há fallback para BRL\*\*.\
> \
> \*\*Stakeholders (cliente, fornecedor, importador, despachante, agente\_carga):\*\* cada papel\
> aceita dois campos, \`\<papel>\_documento\` e \`\<papel>\_razao\_social\`.\
> \- \`\<papel>\_documento\` — busca \*\*exata\*\*, com o documento normalizado (aceita máscara).\
> &#x20; \*\*Precede\*\* a razão social quando os dois vêm no mesmo payload.\
> \- \`\<papel>\_razao\_social\` — busca \*\*parcial\*\*, escopada ao papel e à empresa. Só resolve\
> &#x20; quando encontra \*\*exatamente um\*\* registro. Nenhum match ou mais de um devolve 422 no\
> &#x20; ponteiro \`/\<papel>\_razao\_social\`; no caso ambíguo a mensagem lista até 5 candidatos\
> &#x20; (documento — razão social) e pede o reenvio com \`\<papel>\_documento\`.\
> \
> \*\*Pessoa responsável:\*\* a chave é \`pessoa\_responsavel\_id\` (inteiro), resolvida entre as\
> pessoas da empresa. Enviar \`pessoa\_responsavel\` devolve 422 de campo desconhecido.\
> \
> \*\*Companhia aérea:\*\* \`campanhia\_aerea\` (grafia da coluna) e \`companhia\_aerea\` (apelido de\
> escrita) são aceitos. Quando ambos vêm no mesmo payload, a grafia da coluna prevalece.\
> \
> \*\*Chave desconhecida:\*\* qualquer chave fora do contrato devolve 422 com \*\*um ponteiro por\
> chave\*\* recusada. Exemplo: \`moeda\_codigo\` (nome antigo) devolve \`/moeda\_codigo\`.\
> \
> \*\*Ponteiros de erro do model (assimetria conhecida):\*\* os erros de validação do model usam\
> o nome do \*\*atributo\*\*, não o nome da chave enviada. Na prática o integrador recebe\
> ponteiros que não correspondem ao que enviou:\
> \
> \| Erro de validação | Ponteiro devolvido | Chave enviada |\
> \|---|---|---|\
> \| \`data\_embarque\` posterior à data de chegada | \`/datas\` | \`data\_embarque\` / \`data\_chegada\` |\
> \| fornecedor inválido na persistência | \`/stakeholder\_fornecedor\` | \`fornecedor\_documento\` / \`fornecedor\_razao\_social\` |\
> \| cliente inválido na persistência | \`/stakeholder\_cliente\` | \`cliente\_documento\` / \`cliente\_razao\_social\` |\
> \| despachante inválido na persistência | \`/stakeholder\_despachante\` | \`despachante\_documento\` / \`despachante\_razao\_social\` |\
> \| agente de carga inválido na persistência | \`/stakeholder\_agente\_carga\` | \`agente\_carga\_documento\` / \`agente\_carga\_razao\_social\` |\
> \| importador inválido na persistência | \`/importador\` | \`importador\_documento\` / \`importador\_razao\_social\` |\
> \
> Os erros levantados \*\*antes\*\* da persistência (resolução de stakeholder, moeda, etapa,\
> enum inválido, chave desconhecida) usam o ponteiro da chave enviada e não têm essa assimetria.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"15. ⚓ Processos de Comex","description":"**Gestão completa de comércio exterior**\nControle end-to-end de processos de importação e exportação.\n**Cobertura:**\n- Processos de importação e exportação\n- Controle documental completo\n- Gestão de câmbio e remessas\n- Drawback e regimes especiais"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}},"schemas":{"Processo":{"type":"object","description":"Processo de comércio exterior serializado pela API v2. Mesma forma devolvida pelo item do GET /processos, pelo 201 do POST /processos e pelos 200 dos endpoints de vínculo de documento e de ordem de compra.","properties":{"id":{"type":"integer","description":"ID do processo"},"uuid":{"type":"string","format":"uuid","description":"Identificador público do processo (usado nos paths de vínculo)"},"numero":{"type":"string","description":"Código do processo"},"descricao":{"type":"string","nullable":true,"description":"Descrição do processo"},"data_criacao":{"type":"string","description":"Data e hora de criação"},"cliente":{"type":"string","nullable":true,"description":"Razão social do cliente"},"modalidade":{"type":"string","nullable":true,"description":"Modalidade do processo"},"tipo":{"type":"string","nullable":true,"description":"Tipo (importação/exportação)"},"via":{"type":"string","nullable":true,"description":"Via de transporte (marítima/aérea/terrestre)"},"categoria":{"type":"string","nullable":true,"description":"Categoria do processo"},"etapa":{"type":"string","nullable":true,"description":"Etapa atual do processo"},"canal":{"type":"string","nullable":true,"description":"Canal de parametrização"},"vmle":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de embarque"},"frete":{"type":"number","format":"float","nullable":true,"description":"Valor do frete"},"seguro":{"type":"number","format":"float","nullable":true,"description":"Valor do seguro"},"vmld":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de descarga"},"fornecedor":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — apesar do nome, devolve o IMPORTADOR, não o fornecedor: documento e razão social no formato \"<documento> - <razão social>\" (só a razão social quando não há documento; nome, tipo e valor mantidos por compatibilidade). O fornecedor principal do processo está em stakeholder_fornecedor; a lista de fornecedores, no array fornecedores; o importador estruturado, em importador."},"container":{"type":"string","nullable":true,"description":"Número do container"},"outra_referencia":{"type":"string","nullable":true,"description":"Outra referência"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento"},"data_cambio_antecipacao":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio de antecipação"},"codigo_purchase_order":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra (numero). Código da Purchase Order (string livre legada, mantido por compatibilidade)."},"data_purchase_order":{"type":"string","format":"date","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra. Data da Purchase Order (string livre legada, mantido por compatibilidade)."},"observacao":{"type":"string","nullable":true,"description":"Observações"},"companhia_aerea":{"type":"string","nullable":true,"description":"Companhia aérea"},"numero_do_voo":{"type":"string","nullable":true,"description":"Número do voo"},"navio":{"type":"string","nullable":true,"description":"Nome do navio"},"placa_do_veiculo_transportador":{"type":"string","nullable":true,"description":"Placa do veículo"},"armador":{"type":"string","nullable":true,"description":"Armador"},"conhecimento_de_embarque":{"type":"string","nullable":true,"description":"Conhecimento de embarque"},"pais_procedencia":{"type":"string","nullable":true,"description":"País de procedência"},"embarque":{"type":"string","nullable":true,"description":"Local de embarque"},"data_embarque":{"type":"string","format":"date","nullable":true,"description":"Data de embarque"},"pais_destino":{"type":"string","nullable":true,"description":"País de destino"},"desembarque":{"type":"string","nullable":true,"description":"Local de desembarque"},"data_chegada":{"type":"string","format":"date","nullable":true,"description":"Data de chegada"},"eta":{"type":"string","format":"date","nullable":true,"description":"ETA (Estimated Time of Arrival)"},"agente_de_carga":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o objeto agente_carga (id/razao_social/documento). Agente de carga (string legada, mantida por compatibilidade)."},"stakeholder_agente_carga_id":{"type":"integer","nullable":true,"description":"ID do stakeholder agente de carga"},"bl":{"type":"string","nullable":true,"description":"Número do BL (via marítima)"},"data_emissao_bl":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do BL"},"awb":{"type":"string","nullable":true,"description":"Número do AWB (via aérea)"},"data_emissao_awb":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do AWB"},"crt":{"type":"string","nullable":true,"description":"Número do CRT (via terrestre)"},"data_emissao_crt":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do CRT"},"fci":{"type":"string","nullable":true,"description":"FCI"},"incoterm":{"type":"string","nullable":true,"description":"Incoterm utilizado"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"status_container":{"type":"string","nullable":true,"description":"Status do container"},"presenca_carga":{"type":"string","nullable":true,"description":"Presença da carga"},"numero_invoice":{"type":"string","nullable":true,"description":"Número da invoice"},"valor_invoice":{"type":"number","format":"float","nullable":true,"description":"Valor da invoice"},"vencimento_invoice":{"type":"string","format":"date","nullable":true,"description":"Vencimento da invoice"},"data_cambio_saldo":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio do saldo"},"terminal_de_armazenagem":{"type":"string","nullable":true,"description":"Terminal de armazenagem"},"data_pedido":{"type":"string","format":"date","nullable":true,"description":"Data do pedido (AAAA-MM-DD). Mesmo campo aceito no POST/PATCH."},"numerario_cambio":{"type":"string","nullable":true,"description":"Numerário de câmbio (decimal serializado como string). Mesmo campo aceito no POST/PATCH."},"moeda_codigo_iso":{"type":"string","nullable":true,"description":"Sigla ISO da moeda do processo (ex: USD). Espelha o campo moeda_codigo_iso do POST/PATCH."},"etapa_processo_id":{"type":"string","format":"uuid","description":"Identificador da etapa atual do processo. A chave etapa continua devolvendo a descrição."},"importador":{"type":"object","nullable":true,"description":"Stakeholder importador do processo. Null quando não há importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do importador"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do importador (numero_do_documento na origem)."}}},"stakeholder_fornecedor":{"type":"object","nullable":true,"description":"Stakeholder fornecedor do processo (coluna stakeholder_fornecedor_id, preenchida por fornecedor_documento/fornecedor_razao_social no POST). Null quando não há fornecedor. Não confundir com a chave legada fornecedor, que devolve o importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}},"stakeholder_cliente":{"type":"object","nullable":true,"description":"Stakeholder cliente do processo. Null quando não há cliente. A chave cliente continua devolvendo só a razão social.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do cliente"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do cliente (numero_do_documento na origem)."}}},"anexos":{"type":"array","nullable":true,"description":"Anexos do processo","items":{"type":"object","properties":{"anexo":{"type":"object","properties":{"url":{"type":"string","description":"URL do anexo"}}}}}},"di":{"type":"object","nullable":true,"description":"Declaração de Importação","properties":{"codigo":{"type":"string","nullable":true,"description":"Código da DI"},"data_de_desembaraco":{"type":"string","format":"date","nullable":true,"description":"Data de desembaraço"},"data_registro":{"type":"string","format":"date","nullable":true,"description":"Data de registro"}}},"responsavel":{"type":"object","nullable":true,"description":"Pessoa responsável pelo processo (campo Q2). A edição da Pessoa vinculada reflete no próximo GET (cache key do fragmento inclui a associação — Slice 5).","properties":{"id":{"type":"integer","description":"ID da Pessoa"},"nome":{"type":"string","description":"Nome da Pessoa"},"foto_url":{"type":"string","nullable":true,"description":"URL da foto de perfil (CarrierWave). Null se sem upload."}}},"despachante":{"type":"object","nullable":true,"description":"Stakeholder despachante do processo (campo Q2).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do despachante"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do despachante (numero_do_documento na origem)."}}},"agente_carga":{"type":"object","nullable":true,"description":"Objeto stakeholder do agente de carga (campo Q2). Coexiste com agente_de_carga (string legada) e stakeholder_agente_carga_id (int legado).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do agente de carga"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do agente de carga."}}},"data_embarque_previsto":{"type":"string","format":"date","nullable":true,"description":"ETD — data prevista de embarque (campo Q2)."},"incoterm_legado":{"type":"string","nullable":true,"description":"Valor de incoterm fora do enum normalizado (ex: 'EXX'). Coexiste com incoterm (campo Q2)."},"fornecedores":{"type":"array","description":"Fornecedores M:N do processo (campo Q2). Sempre array — vazio quando não houver fornecedores, nunca null. Coexiste com o campo legado 'fornecedor' (string derivada do importador). Adicionar/remover fornecedor reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID do Stakeholder fornecedor"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}}},"tags":{"type":"array","description":"Nomes das custom tags vinculadas ao processo (campo Q2). Sempre array — vazio quando não houver tags, nunca null. Adicionar/remover tag reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"string"}},"conteineres":{"type":"array","description":"Lista de contêineres do processo (campo Q2). O item com monitorado: true é o contêiner principal cujos numero/peso_bruto/peso_liquido são refletidos no nível do processo (apenas um por processo). Editar o contêiner (inclusive os campos de demurrage) reflete no próximo GET (cache key do fragmento inclui a associação conteineres — Slice 5). Atenção: não confundir moeda_tarifa: 'USD' com dado intencional quando free_time é null, pois USD é o default do banco.","items":{"type":"object","properties":{"numero":{"type":"string","nullable":true,"description":"Número de identificação do contêiner"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"monitorado":{"type":"boolean","description":"Quando true, este é o contêiner principal do processo (apenas um por processo)"},"free_time":{"type":"integer","nullable":true,"description":"Free time em dias contratado com o armador"},"tarifa_demurrage":{"type":"string","nullable":true,"description":"Tarifa de demurrage por dia após o free time (decimal 15,2 serializado como string)"},"moeda_tarifa":{"type":"string","nullable":true,"enum":["BRL","USD"],"description":"Moeda da tarifa_demurrage (BRL ou USD). Default USD no banco — não confundir com dado intencional quando free_time é null"},"inicio_free_time":{"type":"string","format":"date","nullable":true,"description":"Data de início do free time (ISO 8601)"},"data_devolucao":{"type":"string","format":"date","nullable":true,"description":"Data de devolução do contêiner ao armador (ISO 8601)"}}}},"ordem_de_compra":{"type":"object","nullable":true,"description":"Ordem de Compra vinculada ao processo e itens alocados (campo Q2, Slice 4). Substitui os campos legados codigo_purchase_order/data_purchase_order (strings livres, deprecados) pelo vínculo estruturado 1:1 com a OC. Omitido (chave ausente, não null) quando não há OC vinculada. Renderizado fora do fragmento cacheado por-processo (sempre resolve no GET, padrão di/anexos — Slice 4).","properties":{"id":{"type":"integer","description":"ID da Ordem de Compra"},"numero":{"type":"string","description":"Número identificador da Ordem de Compra (OrdemDeCompra#numero)"},"itens":{"type":"array","description":"Itens da OC alocados ao processo. Array vazio quando a OC está vinculada mas sem itens alocados.","items":{"type":"object","properties":{"id":{"type":"string","description":"ID do vínculo item-OC-processo (UUID)"},"item_ordem_de_compra_id":{"type":"integer","description":"ID do item da Ordem de Compra alocado"},"quantidade_alocada":{"type":"string","description":"Quantidade alocada ao processo (decimal 15,4 serializado como string)"}}}}}},"notas_fiscais_vinculadas":{"type":"array","description":"NF-es vinculadas ao processo — a mesma lista da seção \"NF-es vinculadas\" da tela: notas com este processo atribuído, ou sem processo e com a mesma DI/DUIMP do processo, nas situações aceita e finalizada, em ordem de id. Sempre array — vazio quando não há nota, nunca null. Renderizado fora do fragmento cacheado por-processo: vincular, desvincular ou mudar a situação da nota reflete no próximo GET.","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID da NF-e"},"numero":{"type":"integer","nullable":true,"description":"Número da NF-e"},"serie":{"type":"integer","nullable":true,"description":"Série da NF-e"},"chave_acesso":{"type":"string","nullable":true,"description":"Chave de acesso de 44 dígitos. Null quando a nota não tem chave gravada."},"tipo":{"type":"string","nullable":true,"enum":["entrada","saida"],"description":"Tipo da NF-e: entrada ou saida"},"data_emissao":{"type":"string","format":"date-time","description":"Data e hora de emissão (ISO 8601)"},"valor_total":{"type":"number","format":"float","description":"Total da NF-e com 2 casas decimais — o mesmo valor da coluna \"Total da NF-e\" da tela"},"situacao":{"type":"string","enum":["aceita","finalizada"],"description":"Situação da NF-e: aceita ou finalizada"}},"required":["id","numero","serie","chave_acesso","tipo","data_emissao","valor_total","situacao"]}}},"required":["id","numero","notas_fiscais_vinculadas"]},"ErrosEstruturados":{"type":"object","description":"Envelope de erro de validação da API v2 de processos. Cada chave é um JSON Pointer para o campo recusado e o valor é a mensagem correspondente.","properties":{"errors":{"type":"object","description":"Objeto com os erros de validação no formato JSON Pointer","additionalProperties":{"type":"string"}}},"required":["errors"]},"ProcessoInput":{"type":"object","description":"Corpo aceito por POST /processos (raiz `processo`). Apenas `tipo` e `via` são obrigatórios.","properties":{"tipo":{"type":"string","enum":["importacao","exportacao","aquisicao"],"description":"Tipo do processo. Obrigatório."},"via":{"type":"string","enum":["maritima","aerea","rodoviaria"],"description":"Via de transporte. Obrigatório."},"modalidade":{"type":"string","enum":["importacao_direta","conta_e_ordem","encomenda"],"description":"Modalidade da importação."},"incoterm":{"type":"string","enum":["EXW","FCA","CPT","CIP","DAP","DPU","DDP","FAS","FOB","CFR","CIF"],"description":"Incoterm da operação."},"codigo":{"type":"string","description":"Código do processo. Quando ausente ou em branco, o servidor gera o próximo código da empresa."},"moeda_codigo_iso":{"type":"string","description":"Sigla ISO da moeda (ex: 'USD', 'BRL'). Resolvida contra o cadastro de moedas — sigla inexistente devolve 422 em /moeda_codigo_iso, sem fallback para BRL."},"cliente_razao_social":{"type":"string","description":"Razão social do cliente (busca parcial entre os clientes da empresa)."},"cliente_documento":{"type":"string","description":"CNPJ/CPF do cliente (busca exata, normalizada). Precede cliente_razao_social quando ambos vêm."},"fornecedor_razao_social":{"type":"string","description":"Razão social do fornecedor (busca parcial entre os fornecedores da empresa)."},"fornecedor_documento":{"type":"string","description":"CNPJ/CPF do fornecedor (busca exata, normalizada). Precede fornecedor_razao_social quando ambos vêm."},"importador_razao_social":{"type":"string","description":"Razão social do importador (busca parcial entre os stakeholders da empresa)."},"importador_documento":{"type":"string","description":"CNPJ/CPF do importador (busca exata, normalizada). Precede importador_razao_social quando ambos vêm."},"despachante_razao_social":{"type":"string","description":"Razão social do despachante aduaneiro (busca parcial entre os despachantes da empresa)."},"despachante_documento":{"type":"string","description":"CNPJ/CPF do despachante aduaneiro (busca exata, normalizada). Precede despachante_razao_social quando ambos vêm."},"agente_carga_razao_social":{"type":"string","description":"Razão social do agente de carga (busca parcial entre os agentes de carga da empresa)."},"agente_carga_documento":{"type":"string","description":"CNPJ/CPF do agente de carga (busca exata, normalizada). Precede agente_carga_razao_social quando ambos vêm."},"pessoa_responsavel_id":{"type":"integer","description":"ID da Pessoa responsável pelo processo, resolvido entre as pessoas da empresa. Atenção: a chave é pessoa_responsavel_id — pessoa_responsavel devolve 422 de campo desconhecido."},"data_pedido":{"type":"string","format":"date","description":"Data do pedido."},"data_purchase_order":{"type":"string","format":"date","description":"Data da Purchase Order (campo legado)."},"data_cambio_antecipacao":{"type":"string","format":"date","description":"Data do câmbio de antecipação."},"data_embarque":{"type":"string","format":"date-time","description":"Data de embarque."},"eta":{"type":"string","format":"date-time","description":"ETA — chegada estimada."},"data_chegada":{"type":"string","format":"date-time","description":"Data de chegada."},"numerario_cambio":{"type":"number","description":"Numerário de câmbio."},"array_custom_tags":{"type":"array","items":{"type":"string"},"description":"Nomes das custom tags a vincular ao processo."},"descricao":{"type":"string","description":"Descrição do processo."},"numero_invoice":{"type":"string","description":"Número da invoice."},"condicao_pagamento":{"type":"string","description":"Condição de pagamento."},"categoria":{"type":"string","description":"Categoria do processo."},"observacao":{"type":"string","description":"Observações."},"outra_referencia":{"type":"string","description":"Outra referência."},"codigo_purchase_order":{"type":"string","description":"Código da Purchase Order (campo legado)."},"campanhia_aerea":{"type":"string","description":"Companhia aérea (grafia da coluna). Prevalece sobre companhia_aerea quando ambas vêm no mesmo payload."},"companhia_aerea":{"type":"string","description":"Companhia aérea (apelido de escrita aceito). Gravado em campanhia_aerea, que é a grafia devolvida na resposta."},"numero_do_voo":{"type":"string","description":"Número do voo."}},"required":["tipo","via"]}}},"paths":{"/processos":{"post":{"summary":"Cria processo de comércio exterior","tags":["15. ⚓ Processos de Comex"],"description":"**Cria um processo de comércio exterior**\n\nCria o processo para a empresa autenticada e devolve o processo criado com a mesma\nestrutura do `GET /processos`. Apenas `tipo` e `via` são obrigatórios.\n\n**Requer permissão:** o usuário precisa ter permissão de escrita em \"processos\". Sem ela a\nresposta é **403**, com o envelope `{\"message\": \"Você não tem autorização para acessar esta página.\"}`.\n\n**Raiz `processo` ausente** → **400**: o Rails recusa a requisição antes do endpoint\n(`ActionController::ParameterMissing`), com envelope diferente do 422.\n\n**Código (`codigo`):** opcional. Quando ausente ou em branco, o servidor gera o próximo\ncódigo sequencial da empresa sob trava, e o código gerado volta no campo `numero` da resposta.\n\n**Etapa do processo:** preenchida automaticamente com a etapa marcada como inicial na\nempresa. Se nenhuma etapa estiver cadastrada, a criação falha com 422 no ponteiro\n`/etapa_processo` — cadastre ao menos uma etapa antes de usar este endpoint.\n\n**Moeda (`moeda_codigo_iso`):** informe a sigla ISO (ex: `USD`). A busca é exata sobre o\ncadastro de moedas, com a sigla normalizada para maiúsculas. Sigla inexistente devolve 422\nem `/moeda_codigo_iso` — **não há fallback para BRL**.\n\n**Stakeholders (cliente, fornecedor, importador, despachante, agente_carga):** cada papel\naceita dois campos, `<papel>_documento` e `<papel>_razao_social`.\n- `<papel>_documento` — busca **exata**, com o documento normalizado (aceita máscara).\n  **Precede** a razão social quando os dois vêm no mesmo payload.\n- `<papel>_razao_social` — busca **parcial**, escopada ao papel e à empresa. Só resolve\n  quando encontra **exatamente um** registro. Nenhum match ou mais de um devolve 422 no\n  ponteiro `/<papel>_razao_social`; no caso ambíguo a mensagem lista até 5 candidatos\n  (documento — razão social) e pede o reenvio com `<papel>_documento`.\n\n**Pessoa responsável:** a chave é `pessoa_responsavel_id` (inteiro), resolvida entre as\npessoas da empresa. Enviar `pessoa_responsavel` devolve 422 de campo desconhecido.\n\n**Companhia aérea:** `campanhia_aerea` (grafia da coluna) e `companhia_aerea` (apelido de\nescrita) são aceitos. Quando ambos vêm no mesmo payload, a grafia da coluna prevalece.\n\n**Chave desconhecida:** qualquer chave fora do contrato devolve 422 com **um ponteiro por\nchave** recusada. Exemplo: `moeda_codigo` (nome antigo) devolve `/moeda_codigo`.\n\n**Ponteiros de erro do model (assimetria conhecida):** os erros de validação do model usam\no nome do **atributo**, não o nome da chave enviada. Na prática o integrador recebe\nponteiros que não correspondem ao que enviou:\n\n| Erro de validação | Ponteiro devolvido | Chave enviada |\n|---|---|---|\n| `data_embarque` posterior à data de chegada | `/datas` | `data_embarque` / `data_chegada` |\n| fornecedor inválido na persistência | `/stakeholder_fornecedor` | `fornecedor_documento` / `fornecedor_razao_social` |\n| cliente inválido na persistência | `/stakeholder_cliente` | `cliente_documento` / `cliente_razao_social` |\n| despachante inválido na persistência | `/stakeholder_despachante` | `despachante_documento` / `despachante_razao_social` |\n| agente de carga inválido na persistência | `/stakeholder_agente_carga` | `agente_carga_documento` / `agente_carga_razao_social` |\n| importador inválido na persistência | `/importador` | `importador_documento` / `importador_razao_social` |\n\nOs erros levantados **antes** da persistência (resolução de stakeholder, moeda, etapa,\nenum inválido, chave desconhecida) usam o ponteiro da chave enviada e não têm essa assimetria.","parameters":[],"responses":{"201":{"description":"Processo criado com payload completo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Processo"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"422":{"description":"Erro de validação","content":{"Chave desconhecida (moeda_codigo em vez de moeda_codigo_iso)":{},"Razão social ambígua":{},"Moeda inexistente":{},"Nenhuma etapa cadastrada":{},"Ponteiro do model (assimetria)":{},"application/json":{"schema":{"$ref":"#/components/schemas/ErrosEstruturados"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"processo":{"$ref":"#/components/schemas/ProcessoInput"}},"required":["processo"]}}},"required":true}}}}}
```

## Exclui processo de comércio exterior

> \*\*Exclui um processo de comércio exterior sem vínculos em outros domínios\*\*\
> \
> Apaga o processo da empresa autenticada junto com o que pertence a ele (contêineres, anexos,\
> tags, fornecedores, notificações). DI ou DUIMP vinculada \*\*não\*\* é apagada: ela permanece e\
> fica sem processo, podendo ser vinculada de novo por \`POST /processos/{uuid}/documento\`.\
> \
> \*\*Requer permissão:\*\* o usuário precisa ter permissão de exclusão em "processos". Sem ela a\
> resposta é \*\*403\*\*, com o envelope \`{"message": "Você não tem autorização para acessar esta página."}\`.\
> \
> \*\*Recusa por vínculo (422):\*\* a exclusão é recusada, e \*\*nada é apagado\*\*, quando o processo tem\
> qualquer um dos vínculos abaixo. A resposta lista \*\*todos\*\* os motivos de uma vez, um ponteiro por\
> vínculo, dizendo o que desfazer antes de tentar de novo:\
> \
> \| Ponteiro | Vínculo |\
> \|---|---|\
> \| \`/processo/conta\_a\_pagars\` | Conta a pagar, inclusive excluída |\
> \| \`/processo/contas\_a\_recebers\` | Conta a receber, inclusive excluída |\
> \| \`/processo/transferencias\` | Transferência financeira |\
> \| \`/processo/transferencias\_de\_saldo\` | Transferência de saldo enviada ou recebida |\
> \| \`/processo/contratos\_de\_cambio\` | Contrato de câmbio |\
> \| \`/processo/operacoes\_de\_cambio\` | Operação de câmbio |\
> \| \`/processo/nota\_fiscals\` | Nota fiscal |\
> \| \`/processo/pedidos\` | Pedido |\
> \| \`/processo/compras\` | Compra |\
> \| \`/processo/ordem\_de\_compra\` | Ordem de compra |\
> \| \`/processo/itens\_ordem\_de\_compra\` | Itens de ordem de compra alocados |\
> \| \`/processo/conteineres\` | Contêiner monitorado com rastreamento ativo |\
> \
> \*\*Sem exclusão parcial:\*\* a verificação e a exclusão acontecem na mesma transação; em qualquer\
> recusa o processo e todos os registros dele continuam intactos.\
> \
> \*\*Processo inexistente ou de outra empresa\*\* → \*\*404\*\*, sem corpo.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"15. ⚓ Processos de Comex","description":"**Gestão completa de comércio exterior**\nControle end-to-end de processos de importação e exportação.\n**Cobertura:**\n- Processos de importação e exportação\n- Controle documental completo\n- Gestão de câmbio e remessas\n- Drawback e regimes especiais"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}},"schemas":{"ErrosEstruturados":{"type":"object","description":"Envelope de erro de validação da API v2 de processos. Cada chave é um JSON Pointer para o campo recusado e o valor é a mensagem correspondente.","properties":{"errors":{"type":"object","description":"Objeto com os erros de validação no formato JSON Pointer","additionalProperties":{"type":"string"}}},"required":["errors"]}}},"paths":{"/processos/{uuid}":{"delete":{"summary":"Exclui processo de comércio exterior","tags":["15. ⚓ Processos de Comex"],"description":"**Exclui um processo de comércio exterior sem vínculos em outros domínios**\n\nApaga o processo da empresa autenticada junto com o que pertence a ele (contêineres, anexos,\ntags, fornecedores, notificações). DI ou DUIMP vinculada **não** é apagada: ela permanece e\nfica sem processo, podendo ser vinculada de novo por `POST /processos/{uuid}/documento`.\n\n**Requer permissão:** o usuário precisa ter permissão de exclusão em \"processos\". Sem ela a\nresposta é **403**, com o envelope `{\"message\": \"Você não tem autorização para acessar esta página.\"}`.\n\n**Recusa por vínculo (422):** a exclusão é recusada, e **nada é apagado**, quando o processo tem\nqualquer um dos vínculos abaixo. A resposta lista **todos** os motivos de uma vez, um ponteiro por\nvínculo, dizendo o que desfazer antes de tentar de novo:\n\n| Ponteiro | Vínculo |\n|---|---|\n| `/processo/conta_a_pagars` | Conta a pagar, inclusive excluída |\n| `/processo/contas_a_recebers` | Conta a receber, inclusive excluída |\n| `/processo/transferencias` | Transferência financeira |\n| `/processo/transferencias_de_saldo` | Transferência de saldo enviada ou recebida |\n| `/processo/contratos_de_cambio` | Contrato de câmbio |\n| `/processo/operacoes_de_cambio` | Operação de câmbio |\n| `/processo/nota_fiscals` | Nota fiscal |\n| `/processo/pedidos` | Pedido |\n| `/processo/compras` | Compra |\n| `/processo/ordem_de_compra` | Ordem de compra |\n| `/processo/itens_ordem_de_compra` | Itens de ordem de compra alocados |\n| `/processo/conteineres` | Contêiner monitorado com rastreamento ativo |\n\n**Sem exclusão parcial:** a verificação e a exclusão acontecem na mesma transação; em qualquer\nrecusa o processo e todos os registros dele continuam intactos.\n\n**Processo inexistente ou de outra empresa** → **404**, sem corpo.","responses":{"200":{"description":"Processo excluído","content":{"application/json":{"schema":{"type":"object","properties":{"mensagem":{"type":"string"}},"required":["mensagem"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Processo inexistente ou de outra empresa — sem corpo"},"422":{"description":"Processo com vínculos em outros domínios","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrosEstruturados"}}}}}}}}}
```

## Edita processo de comércio exterior

> \*\*Edita um processo de comércio exterior existente\*\*\
> \
> Altera o processo da empresa autenticada e devolve o processo atualizado com a mesma\
> estrutura do item de \`GET /processos\`. As chaves aceitas são as mesmas do \`POST /processos\`,\
> todas opcionais, e as mensagens de erro são as mesmas.\
> \
> \*\*Requer permissão:\*\* o usuário precisa ter permissão de escrita em "processos". Sem ela a\
> resposta é \*\*403\*\*, com o envelope \`{"message": "Você não tem autorização para acessar esta página."}\`.\
> \
> \*\*Semântica parcial:\*\*\
> \- Só as chaves enviadas são alteradas; as ausentes ficam como estão.\
> \- \`null\` é \*\*ignorado\*\* (não limpa o campo).\
> \- \`""\` limpa campos de texto e de data.\
> \- Enums e associações (stakeholders, moeda, pessoa responsável) não são limpos por esta rota:\
> &#x20; enviar um valor troca, omitir mantém.\
> \- \`array\_custom\_tags\` \*\*substitui\*\* a lista inteira; \`\[]\` remove todas as tags.\
> \
> \*\*Payload vazio:\*\* corpo sem a raiz \`processo\`, ou com \`{"processo": {}}\`, devolve \*\*200\*\* com o\
> processo inalterado.\
> \
> \*\*Etapa do processo:\*\* esta rota \*\*não\*\* altera a etapa. O processo continua na etapa em que\
> está, e \`etapa\_processo\_id\` (ou \`etapa\_processo\`) devolve 422 de campo desconhecido.\
> \
> \*\*Transferência de saldo:\*\* não é exposta por esta rota.\
> \
> \*\*Notificações e automações:\*\* editar pela API produz o mesmo efeito que editar pela tela —\
> dispara as notificações de alteração de campo e de tags (inclusive para terceiros) e as\
> automações configuradas por tag.\
> \
> \*\*Processo inexistente ou de outra empresa\*\* → \*\*404\*\*, sem corpo.\
> \
> \*\*Ponteiros de erro do model:\*\* seguem a mesma assimetria documentada no \`POST /processos\`.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"15. ⚓ Processos de Comex","description":"**Gestão completa de comércio exterior**\nControle end-to-end de processos de importação e exportação.\n**Cobertura:**\n- Processos de importação e exportação\n- Controle documental completo\n- Gestão de câmbio e remessas\n- Drawback e regimes especiais"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}},"schemas":{"Processo":{"type":"object","description":"Processo de comércio exterior serializado pela API v2. Mesma forma devolvida pelo item do GET /processos, pelo 201 do POST /processos e pelos 200 dos endpoints de vínculo de documento e de ordem de compra.","properties":{"id":{"type":"integer","description":"ID do processo"},"uuid":{"type":"string","format":"uuid","description":"Identificador público do processo (usado nos paths de vínculo)"},"numero":{"type":"string","description":"Código do processo"},"descricao":{"type":"string","nullable":true,"description":"Descrição do processo"},"data_criacao":{"type":"string","description":"Data e hora de criação"},"cliente":{"type":"string","nullable":true,"description":"Razão social do cliente"},"modalidade":{"type":"string","nullable":true,"description":"Modalidade do processo"},"tipo":{"type":"string","nullable":true,"description":"Tipo (importação/exportação)"},"via":{"type":"string","nullable":true,"description":"Via de transporte (marítima/aérea/terrestre)"},"categoria":{"type":"string","nullable":true,"description":"Categoria do processo"},"etapa":{"type":"string","nullable":true,"description":"Etapa atual do processo"},"canal":{"type":"string","nullable":true,"description":"Canal de parametrização"},"vmle":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de embarque"},"frete":{"type":"number","format":"float","nullable":true,"description":"Valor do frete"},"seguro":{"type":"number","format":"float","nullable":true,"description":"Valor do seguro"},"vmld":{"type":"number","format":"float","nullable":true,"description":"Valor da mercadoria no local de descarga"},"fornecedor":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — apesar do nome, devolve o IMPORTADOR, não o fornecedor: documento e razão social no formato \"<documento> - <razão social>\" (só a razão social quando não há documento; nome, tipo e valor mantidos por compatibilidade). O fornecedor principal do processo está em stakeholder_fornecedor; a lista de fornecedores, no array fornecedores; o importador estruturado, em importador."},"container":{"type":"string","nullable":true,"description":"Número do container"},"outra_referencia":{"type":"string","nullable":true,"description":"Outra referência"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento"},"data_cambio_antecipacao":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio de antecipação"},"codigo_purchase_order":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra (numero). Código da Purchase Order (string livre legada, mantido por compatibilidade)."},"data_purchase_order":{"type":"string","format":"date","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o bloco ordem_de_compra. Data da Purchase Order (string livre legada, mantido por compatibilidade)."},"observacao":{"type":"string","nullable":true,"description":"Observações"},"companhia_aerea":{"type":"string","nullable":true,"description":"Companhia aérea"},"numero_do_voo":{"type":"string","nullable":true,"description":"Número do voo"},"navio":{"type":"string","nullable":true,"description":"Nome do navio"},"placa_do_veiculo_transportador":{"type":"string","nullable":true,"description":"Placa do veículo"},"armador":{"type":"string","nullable":true,"description":"Armador"},"conhecimento_de_embarque":{"type":"string","nullable":true,"description":"Conhecimento de embarque"},"pais_procedencia":{"type":"string","nullable":true,"description":"País de procedência"},"embarque":{"type":"string","nullable":true,"description":"Local de embarque"},"data_embarque":{"type":"string","format":"date","nullable":true,"description":"Data de embarque"},"pais_destino":{"type":"string","nullable":true,"description":"País de destino"},"desembarque":{"type":"string","nullable":true,"description":"Local de desembarque"},"data_chegada":{"type":"string","format":"date","nullable":true,"description":"Data de chegada"},"eta":{"type":"string","format":"date","nullable":true,"description":"ETA (Estimated Time of Arrival)"},"agente_de_carga":{"type":"string","nullable":true,"deprecated":true,"description":"DEPRECADO — usar o objeto agente_carga (id/razao_social/documento). Agente de carga (string legada, mantida por compatibilidade)."},"stakeholder_agente_carga_id":{"type":"integer","nullable":true,"description":"ID do stakeholder agente de carga"},"bl":{"type":"string","nullable":true,"description":"Número do BL (via marítima)"},"data_emissao_bl":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do BL"},"awb":{"type":"string","nullable":true,"description":"Número do AWB (via aérea)"},"data_emissao_awb":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do AWB"},"crt":{"type":"string","nullable":true,"description":"Número do CRT (via terrestre)"},"data_emissao_crt":{"type":"string","format":"date","nullable":true,"description":"Data de emissão do CRT"},"fci":{"type":"string","nullable":true,"description":"FCI"},"incoterm":{"type":"string","nullable":true,"description":"Incoterm utilizado"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"status_container":{"type":"string","nullable":true,"description":"Status do container"},"presenca_carga":{"type":"string","nullable":true,"description":"Presença da carga"},"numero_invoice":{"type":"string","nullable":true,"description":"Número da invoice"},"valor_invoice":{"type":"number","format":"float","nullable":true,"description":"Valor da invoice"},"vencimento_invoice":{"type":"string","format":"date","nullable":true,"description":"Vencimento da invoice"},"data_cambio_saldo":{"type":"string","format":"date","nullable":true,"description":"Data do câmbio do saldo"},"terminal_de_armazenagem":{"type":"string","nullable":true,"description":"Terminal de armazenagem"},"data_pedido":{"type":"string","format":"date","nullable":true,"description":"Data do pedido (AAAA-MM-DD). Mesmo campo aceito no POST/PATCH."},"numerario_cambio":{"type":"string","nullable":true,"description":"Numerário de câmbio (decimal serializado como string). Mesmo campo aceito no POST/PATCH."},"moeda_codigo_iso":{"type":"string","nullable":true,"description":"Sigla ISO da moeda do processo (ex: USD). Espelha o campo moeda_codigo_iso do POST/PATCH."},"etapa_processo_id":{"type":"string","format":"uuid","description":"Identificador da etapa atual do processo. A chave etapa continua devolvendo a descrição."},"importador":{"type":"object","nullable":true,"description":"Stakeholder importador do processo. Null quando não há importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do importador"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do importador (numero_do_documento na origem)."}}},"stakeholder_fornecedor":{"type":"object","nullable":true,"description":"Stakeholder fornecedor do processo (coluna stakeholder_fornecedor_id, preenchida por fornecedor_documento/fornecedor_razao_social no POST). Null quando não há fornecedor. Não confundir com a chave legada fornecedor, que devolve o importador.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}},"stakeholder_cliente":{"type":"object","nullable":true,"description":"Stakeholder cliente do processo. Null quando não há cliente. A chave cliente continua devolvendo só a razão social.","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do cliente"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do cliente (numero_do_documento na origem)."}}},"anexos":{"type":"array","nullable":true,"description":"Anexos do processo","items":{"type":"object","properties":{"anexo":{"type":"object","properties":{"url":{"type":"string","description":"URL do anexo"}}}}}},"di":{"type":"object","nullable":true,"description":"Declaração de Importação","properties":{"codigo":{"type":"string","nullable":true,"description":"Código da DI"},"data_de_desembaraco":{"type":"string","format":"date","nullable":true,"description":"Data de desembaraço"},"data_registro":{"type":"string","format":"date","nullable":true,"description":"Data de registro"}}},"responsavel":{"type":"object","nullable":true,"description":"Pessoa responsável pelo processo (campo Q2). A edição da Pessoa vinculada reflete no próximo GET (cache key do fragmento inclui a associação — Slice 5).","properties":{"id":{"type":"integer","description":"ID da Pessoa"},"nome":{"type":"string","description":"Nome da Pessoa"},"foto_url":{"type":"string","nullable":true,"description":"URL da foto de perfil (CarrierWave). Null se sem upload."}}},"despachante":{"type":"object","nullable":true,"description":"Stakeholder despachante do processo (campo Q2).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do despachante"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do despachante (numero_do_documento na origem)."}}},"agente_carga":{"type":"object","nullable":true,"description":"Objeto stakeholder do agente de carga (campo Q2). Coexiste com agente_de_carga (string legada) e stakeholder_agente_carga_id (int legado).","properties":{"id":{"type":"integer","description":"ID do Stakeholder"},"razao_social":{"type":"string","description":"Razão social do agente de carga"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do agente de carga."}}},"data_embarque_previsto":{"type":"string","format":"date","nullable":true,"description":"ETD — data prevista de embarque (campo Q2)."},"incoterm_legado":{"type":"string","nullable":true,"description":"Valor de incoterm fora do enum normalizado (ex: 'EXX'). Coexiste com incoterm (campo Q2)."},"fornecedores":{"type":"array","description":"Fornecedores M:N do processo (campo Q2). Sempre array — vazio quando não houver fornecedores, nunca null. Coexiste com o campo legado 'fornecedor' (string derivada do importador). Adicionar/remover fornecedor reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID do Stakeholder fornecedor"},"razao_social":{"type":"string","description":"Razão social do fornecedor"},"documento":{"type":"string","nullable":true,"description":"CNPJ/CPF do fornecedor (numero_do_documento na origem)."}}}},"tags":{"type":"array","description":"Nomes das custom tags vinculadas ao processo (campo Q2). Sempre array — vazio quando não houver tags, nunca null. Adicionar/remover tag reflete no próximo GET (cache key do fragmento inclui a associação M:N — Slice 5).","items":{"type":"string"}},"conteineres":{"type":"array","description":"Lista de contêineres do processo (campo Q2). O item com monitorado: true é o contêiner principal cujos numero/peso_bruto/peso_liquido são refletidos no nível do processo (apenas um por processo). Editar o contêiner (inclusive os campos de demurrage) reflete no próximo GET (cache key do fragmento inclui a associação conteineres — Slice 5). Atenção: não confundir moeda_tarifa: 'USD' com dado intencional quando free_time é null, pois USD é o default do banco.","items":{"type":"object","properties":{"numero":{"type":"string","nullable":true,"description":"Número de identificação do contêiner"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto em kg"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido em kg"},"monitorado":{"type":"boolean","description":"Quando true, este é o contêiner principal do processo (apenas um por processo)"},"free_time":{"type":"integer","nullable":true,"description":"Free time em dias contratado com o armador"},"tarifa_demurrage":{"type":"string","nullable":true,"description":"Tarifa de demurrage por dia após o free time (decimal 15,2 serializado como string)"},"moeda_tarifa":{"type":"string","nullable":true,"enum":["BRL","USD"],"description":"Moeda da tarifa_demurrage (BRL ou USD). Default USD no banco — não confundir com dado intencional quando free_time é null"},"inicio_free_time":{"type":"string","format":"date","nullable":true,"description":"Data de início do free time (ISO 8601)"},"data_devolucao":{"type":"string","format":"date","nullable":true,"description":"Data de devolução do contêiner ao armador (ISO 8601)"}}}},"ordem_de_compra":{"type":"object","nullable":true,"description":"Ordem de Compra vinculada ao processo e itens alocados (campo Q2, Slice 4). Substitui os campos legados codigo_purchase_order/data_purchase_order (strings livres, deprecados) pelo vínculo estruturado 1:1 com a OC. Omitido (chave ausente, não null) quando não há OC vinculada. Renderizado fora do fragmento cacheado por-processo (sempre resolve no GET, padrão di/anexos — Slice 4).","properties":{"id":{"type":"integer","description":"ID da Ordem de Compra"},"numero":{"type":"string","description":"Número identificador da Ordem de Compra (OrdemDeCompra#numero)"},"itens":{"type":"array","description":"Itens da OC alocados ao processo. Array vazio quando a OC está vinculada mas sem itens alocados.","items":{"type":"object","properties":{"id":{"type":"string","description":"ID do vínculo item-OC-processo (UUID)"},"item_ordem_de_compra_id":{"type":"integer","description":"ID do item da Ordem de Compra alocado"},"quantidade_alocada":{"type":"string","description":"Quantidade alocada ao processo (decimal 15,4 serializado como string)"}}}}}},"notas_fiscais_vinculadas":{"type":"array","description":"NF-es vinculadas ao processo — a mesma lista da seção \"NF-es vinculadas\" da tela: notas com este processo atribuído, ou sem processo e com a mesma DI/DUIMP do processo, nas situações aceita e finalizada, em ordem de id. Sempre array — vazio quando não há nota, nunca null. Renderizado fora do fragmento cacheado por-processo: vincular, desvincular ou mudar a situação da nota reflete no próximo GET.","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID da NF-e"},"numero":{"type":"integer","nullable":true,"description":"Número da NF-e"},"serie":{"type":"integer","nullable":true,"description":"Série da NF-e"},"chave_acesso":{"type":"string","nullable":true,"description":"Chave de acesso de 44 dígitos. Null quando a nota não tem chave gravada."},"tipo":{"type":"string","nullable":true,"enum":["entrada","saida"],"description":"Tipo da NF-e: entrada ou saida"},"data_emissao":{"type":"string","format":"date-time","description":"Data e hora de emissão (ISO 8601)"},"valor_total":{"type":"number","format":"float","description":"Total da NF-e com 2 casas decimais — o mesmo valor da coluna \"Total da NF-e\" da tela"},"situacao":{"type":"string","enum":["aceita","finalizada"],"description":"Situação da NF-e: aceita ou finalizada"}},"required":["id","numero","serie","chave_acesso","tipo","data_emissao","valor_total","situacao"]}}},"required":["id","numero","notas_fiscais_vinculadas"]},"ErrosEstruturados":{"type":"object","description":"Envelope de erro de validação da API v2 de processos. Cada chave é um JSON Pointer para o campo recusado e o valor é a mensagem correspondente.","properties":{"errors":{"type":"object","description":"Objeto com os erros de validação no formato JSON Pointer","additionalProperties":{"type":"string"}}},"required":["errors"]},"ProcessoEdicaoInput":{"type":"object","description":"Corpo aceito por PATCH /processos/{uuid} (raiz `processo`). Mesmas chaves do POST, todas opcionais: só as chaves enviadas são alteradas.","properties":{"tipo":{"type":"string","enum":["importacao","exportacao","aquisicao"],"description":"Tipo do processo. Obrigatório."},"via":{"type":"string","enum":["maritima","aerea","rodoviaria"],"description":"Via de transporte. Obrigatório."},"modalidade":{"type":"string","enum":["importacao_direta","conta_e_ordem","encomenda"],"description":"Modalidade da importação."},"incoterm":{"type":"string","enum":["EXW","FCA","CPT","CIP","DAP","DPU","DDP","FAS","FOB","CFR","CIF"],"description":"Incoterm da operação."},"codigo":{"type":"string","description":"Código do processo. Quando ausente ou em branco, o servidor gera o próximo código da empresa."},"moeda_codigo_iso":{"type":"string","description":"Sigla ISO da moeda (ex: 'USD', 'BRL'). Resolvida contra o cadastro de moedas — sigla inexistente devolve 422 em /moeda_codigo_iso, sem fallback para BRL."},"cliente_razao_social":{"type":"string","description":"Razão social do cliente (busca parcial entre os clientes da empresa)."},"cliente_documento":{"type":"string","description":"CNPJ/CPF do cliente (busca exata, normalizada). Precede cliente_razao_social quando ambos vêm."},"fornecedor_razao_social":{"type":"string","description":"Razão social do fornecedor (busca parcial entre os fornecedores da empresa)."},"fornecedor_documento":{"type":"string","description":"CNPJ/CPF do fornecedor (busca exata, normalizada). Precede fornecedor_razao_social quando ambos vêm."},"importador_razao_social":{"type":"string","description":"Razão social do importador (busca parcial entre os stakeholders da empresa)."},"importador_documento":{"type":"string","description":"CNPJ/CPF do importador (busca exata, normalizada). Precede importador_razao_social quando ambos vêm."},"despachante_razao_social":{"type":"string","description":"Razão social do despachante aduaneiro (busca parcial entre os despachantes da empresa)."},"despachante_documento":{"type":"string","description":"CNPJ/CPF do despachante aduaneiro (busca exata, normalizada). Precede despachante_razao_social quando ambos vêm."},"agente_carga_razao_social":{"type":"string","description":"Razão social do agente de carga (busca parcial entre os agentes de carga da empresa)."},"agente_carga_documento":{"type":"string","description":"CNPJ/CPF do agente de carga (busca exata, normalizada). Precede agente_carga_razao_social quando ambos vêm."},"pessoa_responsavel_id":{"type":"integer","description":"ID da Pessoa responsável pelo processo, resolvido entre as pessoas da empresa. Atenção: a chave é pessoa_responsavel_id — pessoa_responsavel devolve 422 de campo desconhecido."},"data_pedido":{"type":"string","format":"date","description":"Data do pedido."},"data_purchase_order":{"type":"string","format":"date","description":"Data da Purchase Order (campo legado)."},"data_cambio_antecipacao":{"type":"string","format":"date","description":"Data do câmbio de antecipação."},"data_embarque":{"type":"string","format":"date-time","description":"Data de embarque."},"eta":{"type":"string","format":"date-time","description":"ETA — chegada estimada."},"data_chegada":{"type":"string","format":"date-time","description":"Data de chegada."},"numerario_cambio":{"type":"number","description":"Numerário de câmbio."},"array_custom_tags":{"type":"array","items":{"type":"string"},"description":"Nomes das custom tags a vincular ao processo."},"descricao":{"type":"string","description":"Descrição do processo."},"numero_invoice":{"type":"string","description":"Número da invoice."},"condicao_pagamento":{"type":"string","description":"Condição de pagamento."},"categoria":{"type":"string","description":"Categoria do processo."},"observacao":{"type":"string","description":"Observações."},"outra_referencia":{"type":"string","description":"Outra referência."},"codigo_purchase_order":{"type":"string","description":"Código da Purchase Order (campo legado)."},"campanhia_aerea":{"type":"string","description":"Companhia aérea (grafia da coluna). Prevalece sobre companhia_aerea quando ambas vêm no mesmo payload."},"companhia_aerea":{"type":"string","description":"Companhia aérea (apelido de escrita aceito). Gravado em campanhia_aerea, que é a grafia devolvida na resposta."},"numero_do_voo":{"type":"string","description":"Número do voo."}}}}},"paths":{"/processos/{uuid}":{"patch":{"summary":"Edita processo de comércio exterior","tags":["15. ⚓ Processos de Comex"],"description":"**Edita um processo de comércio exterior existente**\n\nAltera o processo da empresa autenticada e devolve o processo atualizado com a mesma\nestrutura do item de `GET /processos`. As chaves aceitas são as mesmas do `POST /processos`,\ntodas opcionais, e as mensagens de erro são as mesmas.\n\n**Requer permissão:** o usuário precisa ter permissão de escrita em \"processos\". Sem ela a\nresposta é **403**, com o envelope `{\"message\": \"Você não tem autorização para acessar esta página.\"}`.\n\n**Semântica parcial:**\n- Só as chaves enviadas são alteradas; as ausentes ficam como estão.\n- `null` é **ignorado** (não limpa o campo).\n- `\"\"` limpa campos de texto e de data.\n- Enums e associações (stakeholders, moeda, pessoa responsável) não são limpos por esta rota:\n  enviar um valor troca, omitir mantém.\n- `array_custom_tags` **substitui** a lista inteira; `[]` remove todas as tags.\n\n**Payload vazio:** corpo sem a raiz `processo`, ou com `{\"processo\": {}}`, devolve **200** com o\nprocesso inalterado.\n\n**Etapa do processo:** esta rota **não** altera a etapa. O processo continua na etapa em que\nestá, e `etapa_processo_id` (ou `etapa_processo`) devolve 422 de campo desconhecido.\n\n**Transferência de saldo:** não é exposta por esta rota.\n\n**Notificações e automações:** editar pela API produz o mesmo efeito que editar pela tela —\ndispara as notificações de alteração de campo e de tags (inclusive para terceiros) e as\nautomações configuradas por tag.\n\n**Processo inexistente ou de outra empresa** → **404**, sem corpo.\n\n**Ponteiros de erro do model:** seguem a mesma assimetria documentada no `POST /processos`.","parameters":[],"responses":{"200":{"description":"Processo atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Processo"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Processo inexistente ou de outra empresa — sem corpo"},"422":{"description":"Erro de validação","content":{"Chave fora do contrato (etapa)":{},"Código vazio":{},"application/json":{"schema":{"$ref":"#/components/schemas/ErrosEstruturados"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"processo":{"$ref":"#/components/schemas/ProcessoEdicaoInput"}}}}}}}}}}
```
