> 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/18.-catalogo-de-produtos.md).

# 18. 📦 Catálogo De Produtos

**Catálogo de Produtos do Portal Único** Gestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os produtos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex. **Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar produtos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo feita pelo fluxo da tela. **Funcionalidades:**

* Criação de projeto de catálogo (importação ou exportação)
* Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único

## Listar produtos do projeto de catálogo

> Lista os produtos já adicionados a um projeto de catálogo, com paginação e filtros combináveis de \`status\` e \`texto\`. \
> \
> \`produto\_estoque\` vem \`null\` quando o produto veio direto do Portal Único, sem vínculo com produto de estoque do Mainô. \`ncm\` vem \`null\` quando o produto ainda não foi classificado. \
> \
> O filtro \`status\` aceita \*\*apenas o nome\*\* do status — o valor inteiro do enum (usado internamente) é recusado com \`422\`.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos/{projeto_id}/produtos":{"get":{"summary":"Listar produtos do projeto de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Lista os produtos já adicionados a um projeto de catálogo, com paginação e filtros combináveis de `status` e `texto`. \n\n`produto_estoque` vem `null` quando o produto veio direto do Portal Único, sem vínculo com produto de estoque do Mainô. `ncm` vem `null` quando o produto ainda não foi classificado. \n\nO filtro `status` aceita **apenas o nome** do status — o valor inteiro do enum (usado internamente) é recusado com `422`.","parameters":[{"name":"texto","in":"query","required":false,"schema":{"type":"string"},"description":"Busca por código, descrição, denominação ou código interno do produto"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["transmitido","inativo","em_preenchimento","nao_iniciado","aguardando_revisao","preenchimento_reprovado","aprovado","informacoes_insuficientes","erro_ao_sincronizar","em_transmissao"]},"description":"Filtra por status. Aceita apenas o nome do status"},{"name":"page","in":"query","required":false,"description":"Número da página para paginação (padrão: 1)","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","required":false,"description":"Quantidade de itens por página (padrão: 25; acima de 100 aplica o teto de 100)","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Produtos listados","content":{"application/json":{"schema":{"type":"object","required":["produtos","pagination"],"properties":{"produtos":{"type":"array","items":{"type":"object","required":["id","codigo","descricao","denominacao","ncm","status","produto_estoque"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do produto"},"codigo":{"type":"integer","nullable":true,"description":"Código do produto no catálogo (Portal Único), ou `null` quando não informado"},"descricao":{"type":"string","nullable":true,"description":"Descrição do produto, ou `null` quando não informada"},"denominacao":{"type":"string","description":"Denominação do produto"},"ncm":{"type":"string","nullable":true,"description":"Código do NCM, ou `null` quando o produto ainda não foi classificado"},"status":{"type":"string","enum":["transmitido","inativo","em_preenchimento","nao_iniciado","aguardando_revisao","preenchimento_reprovado","aprovado","informacoes_insuficientes","erro_ao_sincronizar","em_transmissao"],"description":"Status do produto"},"produto_estoque":{"type":"object","nullable":true,"description":"Produto de estoque vinculado (id e código), ou `null` quando o produto veio direto do Portal Único","properties":{"id":{"type":"integer","description":"Identificador do produto de estoque"},"codigo":{"type":"string","description":"Código do produto de estoque"}}}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total de produtos que casam os filtros"},"previous_page":{"type":"string","nullable":true,"description":"URL da página anterior, quando existir"},"next_page":{"type":"string","nullable":true,"description":"URL da próxima página, quando existir"}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"404":{"description":"Projeto de catálogo não encontrado ou de outra empresa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"422":{"description":"Filtro inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}}}}
```

## Adicionar produtos ao projeto de catálogo

> Adiciona produtos a um projeto de catálogo, a partir de produtos de estoque do Mainô e/ou de códigos de produto já existentes no Portal Único. Informe \*\*ao menos um\*\* dos dois campos, não vazio; a soma dos dois arrays tem teto de 100 itens por requisição. \
> \
> \*\*Adicionar produto NÃO transmite nada ao Portal Único\*\* — a transmissão continua sendo feita pelo fluxo da tela. \
> \
> \*\*Três faixas de resposta:\*\* \`201\` quando ao menos um produto entrou (inclusive parcialmente — os que reprovaram vêm em \`erros\`); \`200\` quando nenhum produto entrou porque todos já estavam no projeto (requisição idempotente, \`adicionados: 0\` e \`erros: \[]\`); \`422\` quando nada entrou e há motivo. \
> \
> \*\*Duas semânticas de erro:\*\* erro de contrato (empresa sem integração de Catálogo de Produtos configurada, id de outra empresa, payload vazio, teto excedido, código do Portal não numérico) é \*\*atômico\*\* — nada é criado; erro de domínio por item (NCM inválido, código inexistente no Portal) é \*\*parcial\*\* — os itens válidos entram e os motivos vêm em \`erros\`. \
> \
> O \`404\` cobre tanto projeto inexistente quanto projeto de outra empresa, de propósito.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos/{projeto_id}/produtos":{"post":{"summary":"Adicionar produtos ao projeto de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Adiciona produtos a um projeto de catálogo, a partir de produtos de estoque do Mainô e/ou de códigos de produto já existentes no Portal Único. Informe **ao menos um** dos dois campos, não vazio; a soma dos dois arrays tem teto de 100 itens por requisição. \n\n**Adicionar produto NÃO transmite nada ao Portal Único** — a transmissão continua sendo feita pelo fluxo da tela. \n\n**Três faixas de resposta:** `201` quando ao menos um produto entrou (inclusive parcialmente — os que reprovaram vêm em `erros`); `200` quando nenhum produto entrou porque todos já estavam no projeto (requisição idempotente, `adicionados: 0` e `erros: []`); `422` quando nada entrou e há motivo. \n\n**Duas semânticas de erro:** erro de contrato (empresa sem integração de Catálogo de Produtos configurada, id de outra empresa, payload vazio, teto excedido, código do Portal não numérico) é **atômico** — nada é criado; erro de domínio por item (NCM inválido, código inexistente no Portal) é **parcial** — os itens válidos entram e os motivos vêm em `erros`. \n\nO `404` cobre tanto projeto inexistente quanto projeto de outra empresa, de propósito.","parameters":[],"responses":{"200":{"description":"Nenhum produto novo — todos já estavam no projeto (idempotente)","content":{"application/json":{"schema":{"type":"object","required":["produtos"],"properties":{"produtos":{"type":"object","required":["adicionados","total_processado","erros"],"properties":{"adicionados":{"type":"integer","description":"Sempre `0` nesta faixa"},"total_processado":{"type":"integer","description":"Quantidade de itens processados na requisição"},"erros":{"type":"array","items":{"type":"string"},"description":"Sempre vazio nesta faixa"}}}}}}}},"201":{"description":"Ao menos um produto foi adicionado ao projeto","content":{"application/json":{"schema":{"type":"object","required":["produtos"],"properties":{"produtos":{"type":"object","required":["adicionados","total_processado","erros"],"properties":{"adicionados":{"type":"integer","description":"Quantidade de produtos efetivamente criados no projeto"},"total_processado":{"type":"integer","description":"Quantidade de itens processados na requisição"},"erros":{"type":"array","items":{"type":"string"},"description":"Motivos dos itens que não entraram. Vazio quando todos entraram."}}}}}}}},"400":{"description":"Corpo da requisição sem a raiz `produtos`","content":{"application/json":{"schema":{"type":"object","required":["error","validation"],"properties":{"error":{"type":"string","description":"Mensagem de erro"},"validation":{"type":"string","description":"Detalhe do parâmetro ausente"}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"404":{"description":"Projeto de catálogo não encontrado ou de outra empresa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"422":{"description":"Nenhum produto pôde ser adicionado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["produtos"],"properties":{"produtos":{"type":"object","description":"Ao menos um dos dois campos deve vir preenchido. A soma dos dois arrays não pode passar de 100 itens.","properties":{"produtos_estoques_ids":{"type":"array","items":{"type":"integer"},"description":"Ids de produtos de estoque da própria empresa"},"produtos_portal_ids":{"type":"array","items":{"type":"string","pattern":"^[0-9]+$"},"description":"Códigos de produto já existentes no Portal Único. Apenas dígitos — código não numérico é recusado com 422."}}}}}}},"required":true}}}}}
```

## Detalhar produto do projeto de catálogo

> Devolve a ficha completa de um produto do projeto de catálogo: os mesmos campos do \`index\`, mais as respostas dos atributos NCM (simples e compostas), os fabricantes vinculados e os operadores estrangeiros vinculados. \
> \
> Leitura pura — não altera nada no banco nem transmite ao Portal Único. É legível em \*\*qualquer\*\* status do produto, inclusive já transmitido. \
> \
> O \`404\` cobre tanto produto inexistente quanto produto de outro projeto/empresa, de propósito — nunca \`403\`.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos/{projeto_id}/produtos/{id}":{"get":{"summary":"Detalhar produto do projeto de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Devolve a ficha completa de um produto do projeto de catálogo: os mesmos campos do `index`, mais as respostas dos atributos NCM (simples e compostas), os fabricantes vinculados e os operadores estrangeiros vinculados. \n\nLeitura pura — não altera nada no banco nem transmite ao Portal Único. É legível em **qualquer** status do produto, inclusive já transmitido. \n\nO `404` cobre tanto produto inexistente quanto produto de outro projeto/empresa, de propósito — nunca `403`.","responses":{"200":{"description":"Produto detalhado","content":{"application/json":{"schema":{"type":"object","required":["produto"],"properties":{"produto":{"type":"object","required":["id","codigo","descricao","denominacao","ncm","status","produto_estoque","respostas","fabricantes","operadores_estrangeiros"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do produto"},"codigo":{"type":"integer","nullable":true,"description":"Código do produto no catálogo (Portal Único), ou `null` quando não informado"},"descricao":{"type":"string","nullable":true,"description":"Descrição do produto, ou `null` quando não informada"},"denominacao":{"type":"string","description":"Denominação do produto"},"ncm":{"type":"string","nullable":true,"description":"Código do NCM, ou `null` quando o produto ainda não foi classificado"},"status":{"type":"string","enum":["transmitido","inativo","em_preenchimento","nao_iniciado","aguardando_revisao","preenchimento_reprovado","aprovado","informacoes_insuficientes","erro_ao_sincronizar","em_transmissao"],"description":"Status do produto"},"produto_estoque":{"type":"object","nullable":true,"description":"Produto de estoque vinculado (id e código), ou `null` quando o produto veio direto do Portal Único","properties":{"id":{"type":"integer","description":"Identificador do produto de estoque"},"codigo":{"type":"string","description":"Código do produto de estoque"}}},"respostas":{"type":"array","description":"Respostas dos atributos NCM preenchidos para o produto","items":{"type":"object","required":["atributo_code","atributo_referencia_code","valor"],"properties":{"atributo_code":{"type":"string","description":"Código do atributo NCM respondido"},"atributo_referencia_code":{"type":"string","nullable":true,"description":"Código do atributo pai, presente quando a resposta é composta; `null` quando é simples"},"valor":{"type":"array","items":{"type":"string"},"description":"Valor bruto da resposta"}}}},"fabricantes":{"type":"array","description":"Fabricantes vinculados ao produto","items":{"type":"object","required":["id","conhecido","operador_estrangeiro_id","pais"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do fabricante"},"conhecido":{"type":"boolean","description":"Verdadeiro quando o fabricante é identificado (`known`); falso quando só o país é conhecido"},"operador_estrangeiro_id":{"type":"string","format":"uuid","nullable":true,"description":"Identificador do operador estrangeiro vinculado, quando conhecido"},"pais":{"type":"object","nullable":true,"description":"País do fabricante, quando informado","required":["id","codigo","nome"],"properties":{"id":{"type":"integer","description":"Identificador do país"},"codigo":{"type":"string","nullable":true,"description":"Código ISO alfa-2 do país, ou `null` quando o país de referência não tem esse código cadastrado"},"nome":{"type":"string","nullable":true,"description":"Nome do país, ou `null` quando o país de referência não tem nome cadastrado"}}}}}},"operadores_estrangeiros":{"type":"array","description":"Operadores estrangeiros vinculados ao produto","items":{"type":"object","required":["id","codigo","nome"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do operador estrangeiro"},"codigo":{"type":"string","nullable":true,"description":"Código do operador estrangeiro"},"nome":{"type":"string","description":"Nome do operador estrangeiro"}}}}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"404":{"description":"Produto ou projeto de catálogo não encontrado, ou de outra empresa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}}}}
```

## Remover produto do projeto de catálogo

> Remove um produto do projeto de catálogo, escopado à empresa autenticada. Exige a \*\*mesma permissão que a tela usa hoje\*\* para remover produto do projeto — a permissão de edição do submenu de catálogo, não a de exclusão. \
> \
> Produto \`transmitido\` ao Portal Único, \`em\_transmissao\` (sincronização em andamento no exato momento da chamada) ou \`inativo\` não pode ser removido — 422 e nada é apagado. \
> \
> A remoção apaga junto os dependentes do produto — respostas, fabricantes, anexos e mensagens. \
> \
> Produto de outro projeto ou de outra empresa devolve 404 — nunca 403, que confirmaria a existência do id para quem não deveria saber. \
> \
> A resposta de sucesso traz o corpo do produto excluído, no mesmo formato do \`GET\`. A exclusão bem-sucedida fica registrada no histórico com o autor identificado.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos/{projeto_id}/produtos/{id}":{"delete":{"summary":"Remover produto do projeto de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Remove um produto do projeto de catálogo, escopado à empresa autenticada. Exige a **mesma permissão que a tela usa hoje** para remover produto do projeto — a permissão de edição do submenu de catálogo, não a de exclusão. \n\nProduto `transmitido` ao Portal Único, `em_transmissao` (sincronização em andamento no exato momento da chamada) ou `inativo` não pode ser removido — 422 e nada é apagado. \n\nA remoção apaga junto os dependentes do produto — respostas, fabricantes, anexos e mensagens. \n\nProduto de outro projeto ou de outra empresa devolve 404 — nunca 403, que confirmaria a existência do id para quem não deveria saber. \n\nA resposta de sucesso traz o corpo do produto excluído, no mesmo formato do `GET`. A exclusão bem-sucedida fica registrada no histórico com o autor identificado.","responses":{"200":{"description":"Produto do catálogo removido","content":{"application/json":{"schema":{"type":"object","required":["produto"],"properties":{"produto":{"type":"object","required":["id","codigo","descricao","denominacao","ncm","status","produto_estoque","respostas","fabricantes","operadores_estrangeiros"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do produto removido"},"codigo":{"type":"integer","nullable":true,"description":"Código do produto no catálogo (Portal Único), ou `null` quando não informado"},"descricao":{"type":"string","nullable":true,"description":"Descrição do produto, ou `null` quando não informada"},"denominacao":{"type":"string","description":"Denominação do produto"},"ncm":{"type":"string","nullable":true,"description":"Código do NCM, ou `null` quando o produto ainda não foi classificado"},"status":{"type":"string","enum":["transmitido","inativo","em_preenchimento","nao_iniciado","aguardando_revisao","preenchimento_reprovado","aprovado","informacoes_insuficientes","erro_ao_sincronizar","em_transmissao"],"description":"Status do produto no momento da remoção"},"produto_estoque":{"type":"object","nullable":true,"description":"Produto de estoque vinculado (id e código), ou `null` quando o produto veio direto do Portal Único","properties":{"id":{"type":"integer","description":"Identificador do produto de estoque"},"codigo":{"type":"string","description":"Código do produto de estoque"}}},"respostas":{"type":"array","description":"Respostas dos atributos NCM preenchidos para o produto removido","items":{"type":"object"}},"fabricantes":{"type":"array","description":"Fabricantes vinculados ao produto removido","items":{"type":"object"}},"operadores_estrangeiros":{"type":"array","description":"Operadores estrangeiros vinculados ao produto removido","items":{"type":"object"}}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"403":{"description":"Pessoa sem a permissão que a tela exige para remover produto","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem de autorização negada"}}}}}},"404":{"description":"Produto ou projeto de catálogo não encontrado, ou de outra empresa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"422":{"description":"Produto transmitido, em transmissão ao Portal Único ou inativado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}}}}
```

## Editar produto do projeto de catálogo

> Edita um produto do projeto de catálogo, escopado à empresa autenticada. É atualização parcial — só as chaves enviadas são alteradas. Exige a \*\*mesma permissão que a tela usa hoje\*\* para editar produto do projeto (a permissão de edição do submenu de catálogo). \
> \
> \`status\`, \`tipo\_edicao\` e \`codigo\` são somente leitura: enviar qualquer uma dessas chaves devolve 422 nomeando o campo, e nada é alterado — a API nunca transmite nem aprova um produto. \
> \
> Só é possível editar produto \*\*em preenchimento\*\* (\`nao\_iniciado\`, \`em\_preenchimento\`, \`preenchimento\_reprovado\`, \`informacoes\_insuficientes\`); nos demais status, 422. Toda edição bem-sucedida deixa o produto em \`em\_preenchimento\` (mesma invariante do autosave da tela). \
> \
> \`ncm\` só pode ser trocado em \`nao\_iniciado\`/\`em\_preenchimento\`; a troca sincroniza a classificação fiscal do produto de estoque vinculado. Reenviar o NCM já vigente é aceito em qualquer status editável (no-op). NCM inexistente ou inativo, ou tentativa de troca fora desses dois status, devolvem 422. \
> \
> \`respostas\` usa o mesmo formato do \`GET\` (\`atributo\_code\`, \`atributo\_referencia\_code\` para respostas compostas, \`valor\` como lista de textos) e é validado contra a árvore de atributos oficial do NCM — código fora da árvore devolve 422 nomeando o código, sem criar cadastro de atributo novo. \
> \
> \`operador\_estrangeiro\_ids\` e \`pais\_fabricante\_id\` formam um único campo lógico de fabricante: nenhuma das duas chaves presente preserva o fabricante atual; qualquer uma presente substitui o fabricante (ids → fabricante identificado, ids vazios/país → fabricante só-país); as duas com valor ao mesmo tempo devolvem 422. Operador de outra integração devolve 422 nomeando o id, sem vincular. \
> \
> \`descricao\` acima de 3700 caracteres devolve 422; \`null\`/\`""\` limpa a descrição. \`denominacao\` vazia devolve 422; acima de 100 caracteres é truncada (mesmo comportamento do model). \
> \
> Produto de outro projeto ou de outra empresa devolve 404, nunca 403. Toda edição bem-sucedida fica registrada no histórico com o autor identificado — inclusive quando a pessoa da chave de API não é colaboradora do projeto.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos/{projeto_id}/produtos/{id}":{"patch":{"summary":"Editar produto do projeto de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Edita um produto do projeto de catálogo, escopado à empresa autenticada. É atualização parcial — só as chaves enviadas são alteradas. Exige a **mesma permissão que a tela usa hoje** para editar produto do projeto (a permissão de edição do submenu de catálogo). \n\n`status`, `tipo_edicao` e `codigo` são somente leitura: enviar qualquer uma dessas chaves devolve 422 nomeando o campo, e nada é alterado — a API nunca transmite nem aprova um produto. \n\nSó é possível editar produto **em preenchimento** (`nao_iniciado`, `em_preenchimento`, `preenchimento_reprovado`, `informacoes_insuficientes`); nos demais status, 422. Toda edição bem-sucedida deixa o produto em `em_preenchimento` (mesma invariante do autosave da tela). \n\n`ncm` só pode ser trocado em `nao_iniciado`/`em_preenchimento`; a troca sincroniza a classificação fiscal do produto de estoque vinculado. Reenviar o NCM já vigente é aceito em qualquer status editável (no-op). NCM inexistente ou inativo, ou tentativa de troca fora desses dois status, devolvem 422. \n\n`respostas` usa o mesmo formato do `GET` (`atributo_code`, `atributo_referencia_code` para respostas compostas, `valor` como lista de textos) e é validado contra a árvore de atributos oficial do NCM — código fora da árvore devolve 422 nomeando o código, sem criar cadastro de atributo novo. \n\n`operador_estrangeiro_ids` e `pais_fabricante_id` formam um único campo lógico de fabricante: nenhuma das duas chaves presente preserva o fabricante atual; qualquer uma presente substitui o fabricante (ids → fabricante identificado, ids vazios/país → fabricante só-país); as duas com valor ao mesmo tempo devolvem 422. Operador de outra integração devolve 422 nomeando o id, sem vincular. \n\n`descricao` acima de 3700 caracteres devolve 422; `null`/`\"\"` limpa a descrição. `denominacao` vazia devolve 422; acima de 100 caracteres é truncada (mesmo comportamento do model). \n\nProduto de outro projeto ou de outra empresa devolve 404, nunca 403. Toda edição bem-sucedida fica registrada no histórico com o autor identificado — inclusive quando a pessoa da chave de API não é colaboradora do projeto.","parameters":[],"responses":{"200":{"description":"Produto do catálogo atualizado","content":{"application/json":{"schema":{"type":"object","required":["produto"],"properties":{"produto":{"type":"object","required":["id","codigo","descricao","denominacao","ncm","status","produto_estoque","respostas","fabricantes","operadores_estrangeiros"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do produto"},"codigo":{"type":"integer","nullable":true,"description":"Código do produto no catálogo (Portal Único), ou `null` quando não informado"},"descricao":{"type":"string","nullable":true,"description":"Descrição do produto, ou `null` quando não informada"},"denominacao":{"type":"string","description":"Denominação do produto"},"ncm":{"type":"string","nullable":true,"description":"Código do NCM, ou `null` quando o produto ainda não foi classificado"},"status":{"type":"string","enum":["transmitido","inativo","em_preenchimento","nao_iniciado","aguardando_revisao","preenchimento_reprovado","aprovado","informacoes_insuficientes","erro_ao_sincronizar","em_transmissao"],"description":"Status do produto após a edição — sempre em_preenchimento"},"produto_estoque":{"type":"object","nullable":true,"description":"Produto de estoque vinculado (id e código), ou `null` quando o produto veio direto do Portal Único","properties":{"id":{"type":"integer","description":"Identificador do produto de estoque"},"codigo":{"type":"string","description":"Código do produto de estoque"}}},"respostas":{"type":"array","description":"Respostas dos atributos NCM do produto, após a edição","items":{"type":"object"}},"fabricantes":{"type":"array","description":"Fabricantes vinculados ao produto, após a edição","items":{"type":"object"}},"operadores_estrangeiros":{"type":"array","description":"Operadores estrangeiros vinculados ao produto, após a edição","items":{"type":"object"}}}}}}}}},"400":{"description":"Corpo da requisição sem a raiz `produto`","content":{"application/json":{"schema":{"type":"object","required":["error","validation"],"properties":{"error":{"type":"string","description":"Mensagem de erro"},"validation":{"type":"string","description":"Detalhe do parâmetro ausente"}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"403":{"description":"Pessoa sem a permissão que a tela exige para editar produto","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem de autorização negada"}}}}}},"404":{"description":"Produto ou projeto de catálogo não encontrado, ou de outra empresa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"422":{"description":"Campo somente leitura, produto fora do preenchimento, NCM/respostas/fabricante inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"produto":{"type":"object","properties":{"descricao":{"type":"string","nullable":true,"description":"Descrição do produto. Máximo 3700 caracteres; `null`/`\"\"` limpa."},"denominacao":{"type":"string","description":"Denominação do produto. Vazia devolve 422; acima de 100 caracteres é truncada."},"ncm":{"type":"string","description":"Código do NCM. Só pode ser trocado em nao_iniciado/em_preenchimento."},"respostas":{"type":"array","description":"Respostas dos atributos NCM, no mesmo formato do GET.","items":{"type":"object","properties":{"atributo_code":{"type":"string","description":"Código do atributo NCM"},"atributo_referencia_code":{"type":"string","nullable":true,"description":"Código do atributo pai, só para resposta composta"},"valor":{"type":"array","items":{"type":"string"},"description":"Valor da resposta, lista de textos não vazia"}}}},"operador_estrangeiro_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ids dos operadores estrangeiros do fabricante conhecido, escopados à integração do produto."},"pais_fabricante_id":{"type":"integer","nullable":true,"description":"Id do país, quando o fabricante é conhecido só pelo país."}}}}}}},"required":true}}}}}
```

## Listar projetos de catálogo

> Lista os projetos de catálogo da empresa autenticada, com paginação e filtros. Sem o filtro \`status\`, projetos com \`status: "arquivado"\` ficam de fora da lista — para trazê-los, informe \`status=arquivado\` explicitamente. Os filtros são combináveis entre si (ex.: \`texto\` + \`status\` ao mesmo tempo). O formato de cada projeto é o mesmo do \`POST\` acima — mesmo contrato, mesma fonte.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos":{"get":{"summary":"Listar projetos de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Lista os projetos de catálogo da empresa autenticada, com paginação e filtros. Sem o filtro `status`, projetos com `status: \"arquivado\"` ficam de fora da lista — para trazê-los, informe `status=arquivado` explicitamente. Os filtros são combináveis entre si (ex.: `texto` + `status` ao mesmo tempo). O formato de cada projeto é o mesmo do `POST` acima — mesmo contrato, mesma fonte.","parameters":[{"name":"texto","in":"query","required":false,"schema":{"type":"string"},"description":"Busca por nome do projeto ou por código/descrição dos produtos vinculados"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["em_andamento","finalizado","atrasado","arquivado"]},"description":"Filtra por status. Sem este filtro, projetos arquivados não aparecem"},{"name":"criado_data_inicio","in":"query","required":false,"description":"Data de criação, início (inclusiva). Só filtra quando enviado junto com `criado_data_fim` — informado sozinho, é ignorado","schema":{"type":"string","format":"date"}},{"name":"criado_data_fim","in":"query","required":false,"description":"Data de criação, fim (inclusiva). Só filtra quando enviado junto com `criado_data_inicio` — informado sozinho, é ignorado","schema":{"type":"string","format":"date"}},{"name":"finalizado_data_inicio","in":"query","required":false,"description":"Data de finalização, início (inclusiva). Só filtra quando enviado junto com `finalizado_data_fim` — informado sozinho, é ignorado","schema":{"type":"string","format":"date"}},{"name":"finalizado_data_fim","in":"query","required":false,"description":"Data de finalização, fim (inclusiva). Só filtra quando enviado junto com `finalizado_data_inicio` — informado sozinho, é ignorado","schema":{"type":"string","format":"date"}},{"name":"prazo_data_inicio","in":"query","required":false,"description":"Prazo do projeto, início (inclusiva). Só filtra quando enviado junto com `prazo_data_fim` — informado sozinho, é ignorado","schema":{"type":"string","format":"date"}},{"name":"prazo_data_fim","in":"query","required":false,"description":"Prazo do projeto, fim (inclusiva). Só filtra quando enviado junto com `prazo_data_inicio` — informado sozinho, é ignorado","schema":{"type":"string","format":"date"}},{"name":"colaborador_id","in":"query","required":false,"description":"Filtra projetos que têm este colaborador (id da pessoa vinculada)","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"Número da página para paginação (padrão: 1)","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","required":false,"description":"Quantidade de itens por página (padrão: 25; acima de 100 aplica o teto de 100)","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Projetos listados","content":{"application/json":{"schema":{"type":"object","required":["projetos","pagination"],"properties":{"projetos":{"type":"array","items":{"type":"object","required":["id","nome","tipo","tipo_sincronizacao","status","prazo","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do projeto"},"nome":{"type":"string","description":"Nome do projeto"},"tipo":{"type":"string","enum":["importacao","exportacao"],"description":"Natureza do projeto"},"tipo_sincronizacao":{"type":"string","enum":["rascunho","ativo"],"description":"Modo de sincronização do projeto"},"status":{"type":"string","enum":["em_andamento","finalizado","atrasado","arquivado"],"description":"Status do projeto, definido pelo sistema (somente leitura)"},"prazo":{"type":"string","format":"date","nullable":true,"description":"Prazo do projeto, ou `null` quando não informado"},"created_at":{"type":"string","format":"date-time","description":"Data e hora de criação"}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total de projetos que casam os filtros"},"previous_page":{"type":"string","nullable":true,"description":"URL da página anterior, quando existir"},"next_page":{"type":"string","nullable":true,"description":"URL da próxima página, quando existir"}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"422":{"description":"Filtro inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}}}}
```

## Criar projeto de catálogo

> Cria um projeto de catálogo de produtos vinculado à empresa autenticada. O projeto nasce com \`status\` definido pelo sistema — o campo é somente de leitura e não pode ser enviado. Quando \`prazo\` é informado com uma data já vencida, o projeto nasce com \`status: "atrasado"\`; caso contrário nasce como \`em\_andamento\`. O \`prazo\` só é aceito no formato ISO-8601 (\`AAAA-MM-DD\`) — um valor em outro formato é descartado em silêncio e o projeto é criado sem prazo. \`tipo\_sincronizacao\` é opcional e assume \`ativo\` quando omitido, mas \*\*não pode ser alterado depois\*\* da criação. Criar um projeto \*\*não transmite nada ao Portal Único\*\*.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos":{"post":{"summary":"Criar projeto de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Cria um projeto de catálogo de produtos vinculado à empresa autenticada. O projeto nasce com `status` definido pelo sistema — o campo é somente de leitura e não pode ser enviado. Quando `prazo` é informado com uma data já vencida, o projeto nasce com `status: \"atrasado\"`; caso contrário nasce como `em_andamento`. O `prazo` só é aceito no formato ISO-8601 (`AAAA-MM-DD`) — um valor em outro formato é descartado em silêncio e o projeto é criado sem prazo. `tipo_sincronizacao` é opcional e assume `ativo` quando omitido, mas **não pode ser alterado depois** da criação. Criar um projeto **não transmite nada ao Portal Único**.","parameters":[],"responses":{"201":{"description":"Projeto de catálogo criado","content":{"application/json":{"schema":{"type":"object","required":["projeto"],"properties":{"projeto":{"type":"object","required":["id","nome","tipo","tipo_sincronizacao","status","prazo","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do projeto"},"nome":{"type":"string","description":"Nome do projeto"},"tipo":{"type":"string","enum":["importacao","exportacao"],"description":"Natureza do projeto"},"tipo_sincronizacao":{"type":"string","enum":["rascunho","ativo"],"description":"Modo de sincronização do projeto"},"status":{"type":"string","enum":["em_andamento","finalizado","atrasado","arquivado"],"description":"Status do projeto, definido pelo sistema (somente leitura)"},"prazo":{"type":"string","format":"date","nullable":true,"description":"Prazo do projeto, ou `null` quando não informado"},"created_at":{"type":"string","format":"date-time","description":"Data e hora de criação"}}}}}}}},"400":{"description":"Corpo da requisição sem a raiz `projeto`","content":{"application/json":{"schema":{"type":"object","required":["error","validation"],"properties":{"error":{"type":"string","description":"Mensagem de erro"},"validation":{"type":"string","description":"Detalhe do parâmetro ausente"}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"422":{"description":"Projeto inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["projeto"],"properties":{"projeto":{"type":"object","required":["nome","tipo"],"properties":{"nome":{"type":"string","description":"Nome do projeto de catálogo"},"tipo":{"type":"string","enum":["importacao","exportacao"],"description":"Natureza do projeto"},"tipo_sincronizacao":{"type":"string","enum":["rascunho","ativo"],"description":"Modo de sincronização do projeto. Opcional — assume `ativo` quando omitido. Não pode ser alterado depois da criação."},"prazo":{"type":"string","format":"date","nullable":true,"description":"Prazo do projeto em ISO-8601 (`AAAA-MM-DD`). Data já vencida faz o projeto nascer com `status: \"atrasado\"`."}}}}}}},"required":true}}}}}
```

## Detalhar projeto de catálogo

> Busca um projeto de catálogo pelo id, escopado à empresa autenticada. O formato da resposta é o mesmo do \`POST\` e do \`GET\` de listagem acima — mesmo contrato, mesma fonte. Projeto inexistente ou de outra empresa devolve 404 — nunca 403, que confirmaria a existência do id para quem não deveria saber.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos/{id}":{"get":{"summary":"Detalhar projeto de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Busca um projeto de catálogo pelo id, escopado à empresa autenticada. O formato da resposta é o mesmo do `POST` e do `GET` de listagem acima — mesmo contrato, mesma fonte. Projeto inexistente ou de outra empresa devolve 404 — nunca 403, que confirmaria a existência do id para quem não deveria saber.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Identificador do projeto"}],"responses":{"200":{"description":"Projeto encontrado","content":{"application/json":{"schema":{"type":"object","required":["projeto"],"properties":{"projeto":{"type":"object","required":["id","nome","tipo","tipo_sincronizacao","status","prazo","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do projeto"},"nome":{"type":"string","description":"Nome do projeto"},"tipo":{"type":"string","enum":["importacao","exportacao"],"description":"Natureza do projeto"},"tipo_sincronizacao":{"type":"string","enum":["rascunho","ativo"],"description":"Modo de sincronização do projeto"},"status":{"type":"string","enum":["em_andamento","finalizado","atrasado","arquivado"],"description":"Status do projeto, definido pelo sistema (somente leitura)"},"prazo":{"type":"string","format":"date","nullable":true,"description":"Prazo do projeto, ou `null` quando não informado"},"created_at":{"type":"string","format":"date-time","description":"Data e hora de criação"}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"404":{"description":"Projeto não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}}}}
```

## Excluir projeto de catálogo

> Exclui um projeto de catálogo já existente, escopado à empresa autenticada. Exige a permissão de exclusão do submenu de catálogo — sem ela, 403. A exclusão apaga, junto, \*\*todos os produtos e colaboradores\*\* vinculados ao projeto — não é possível excluir só o projeto mantendo os produtos. Travas impedem a exclusão: um projeto com algum produto \`transmitido\` ao Portal Único, com algum produto \`em\_transmissao\` (sincronização em andamento no exato momento da chamada), ou com algum produto \`inativo\` — em todos os casos, 422 e nada é apagado. Projeto de outra empresa devolve 404 para quem tem permissão, nunca 403. A resposta de sucesso traz o corpo do projeto excluído, no mesmo formato do \`GET\`/\`PATCH\`. A exclusão bem-sucedida fica registrada no histórico com o autor identificado.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos/{id}":{"delete":{"summary":"Excluir projeto de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Exclui um projeto de catálogo já existente, escopado à empresa autenticada. Exige a permissão de exclusão do submenu de catálogo — sem ela, 403. A exclusão apaga, junto, **todos os produtos e colaboradores** vinculados ao projeto — não é possível excluir só o projeto mantendo os produtos. Travas impedem a exclusão: um projeto com algum produto `transmitido` ao Portal Único, com algum produto `em_transmissao` (sincronização em andamento no exato momento da chamada), ou com algum produto `inativo` — em todos os casos, 422 e nada é apagado. Projeto de outra empresa devolve 404 para quem tem permissão, nunca 403. A resposta de sucesso traz o corpo do projeto excluído, no mesmo formato do `GET`/`PATCH`. A exclusão bem-sucedida fica registrada no histórico com o autor identificado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Identificador do projeto"}],"responses":{"200":{"description":"Projeto de catálogo excluído","content":{"application/json":{"schema":{"type":"object","required":["projeto"],"properties":{"projeto":{"type":"object","required":["id","nome","tipo","tipo_sincronizacao","status","prazo","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do projeto excluído"},"nome":{"type":"string","description":"Nome do projeto"},"tipo":{"type":"string","enum":["importacao","exportacao"],"description":"Natureza do projeto"},"tipo_sincronizacao":{"type":"string","enum":["rascunho","ativo"],"description":"Modo de sincronização do projeto"},"status":{"type":"string","enum":["em_andamento","finalizado","atrasado","arquivado"],"description":"Status do projeto, definido pelo sistema (somente leitura)"},"prazo":{"type":"string","format":"date","nullable":true,"description":"Prazo do projeto, ou `null` quando não informado"},"created_at":{"type":"string","format":"date-time","description":"Data e hora de criação"}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"403":{"description":"Pessoa sem permissão de exclusão","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem de autorização negada"}}}}}},"404":{"description":"Projeto não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"422":{"description":"Projeto com produto transmitido ou em transmissão ao Portal Único","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}}}}
```

## Editar projeto de catálogo

> Edita \`nome\`, \`tipo\`, \`tipo\_sincronizacao\` ou \`prazo\` de um projeto de catálogo já existente, escopado à empresa autenticada. É atualização parcial — só as chaves enviadas no corpo são alteradas, as demais permanecem como estavam. \`status\` é definido pelo sistema: enviar esta chave no payload, com qualquer valor (inclusive o já vigente), devolve 422 em vez de ser ignorada em silêncio. \`tipo\_sincronizacao\` também não pode ser alterado — tentar mudá-lo devolve 422 nomeando o campo; reenviar o mesmo valor já vigente é aceito (no-op idempotente). Um \`prazo\` que não seja exatamente uma data no formato \`AAAA-MM-DD\` devolve 422, nunca é descartado em silêncio como no \`POST\`. Um \`prazo\` já vencido marca o projeto como \`status: "atrasado"\`; se o projeto já estiver \`atrasado\`, estender o \`prazo\` para o futuro \*\*não\*\* reverte o status — mesmo callback que já roda pela tela e no \`POST\`. Projeto de outra empresa devolve 404, nunca 403. Toda edição bem-sucedida fica registrada no histórico com o autor identificado.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"18. 📦 Catálogo de Produtos","description":"**Catálogo de Produtos do Portal Único**\nGestão dos projetos de catálogo e dos produtos vinculados a eles. Um projeto agrupa os\nprodutos que serão trabalhados para o Catálogo de Produtos do Portal Único Siscomex.\n**Importante:** estes endpoints operam apenas no Mainô. Criar um projeto ou adicionar\nprodutos a ele **não transmite nada ao Portal Único** — a transmissão continua sendo\nfeita pelo fluxo da tela.\n**Funcionalidades:**\n- Criação de projeto de catálogo (importação ou exportação)\n- Adição de produtos ao projeto, a partir do estoque ou de códigos do Portal Único"}],"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":{"SimpleError":{"type":"object","description":"Formato canônico de erro estruturado da API v2, renderizado por `app/views/api/v2/shared/_simple_error.json.jbuilder`. O objeto `fields` é omitido quando o erro não é atribuível a campos específicos (ex.: 404).","properties":{"errors":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem principal do erro, pronta para exibição"},"fields":{"type":"object","description":"Mapa de campo para a lista de motivos. Omitido quando não há campo envolvido.","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"required":["errors"]}}},"paths":{"/comex/catalogo_produto/gestao/projetos/{id}":{"patch":{"summary":"Editar projeto de catálogo","tags":["18. 📦 Catálogo de Produtos"],"description":"Edita `nome`, `tipo`, `tipo_sincronizacao` ou `prazo` de um projeto de catálogo já existente, escopado à empresa autenticada. É atualização parcial — só as chaves enviadas no corpo são alteradas, as demais permanecem como estavam. `status` é definido pelo sistema: enviar esta chave no payload, com qualquer valor (inclusive o já vigente), devolve 422 em vez de ser ignorada em silêncio. `tipo_sincronizacao` também não pode ser alterado — tentar mudá-lo devolve 422 nomeando o campo; reenviar o mesmo valor já vigente é aceito (no-op idempotente). Um `prazo` que não seja exatamente uma data no formato `AAAA-MM-DD` devolve 422, nunca é descartado em silêncio como no `POST`. Um `prazo` já vencido marca o projeto como `status: \"atrasado\"`; se o projeto já estiver `atrasado`, estender o `prazo` para o futuro **não** reverte o status — mesmo callback que já roda pela tela e no `POST`. Projeto de outra empresa devolve 404, nunca 403. Toda edição bem-sucedida fica registrada no histórico com o autor identificado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Identificador do projeto"}],"responses":{"200":{"description":"Projeto de catálogo atualizado","content":{"application/json":{"schema":{"type":"object","required":["projeto"],"properties":{"projeto":{"type":"object","required":["id","nome","tipo","tipo_sincronizacao","status","prazo","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador do projeto"},"nome":{"type":"string","description":"Nome do projeto"},"tipo":{"type":"string","enum":["importacao","exportacao"],"description":"Natureza do projeto"},"tipo_sincronizacao":{"type":"string","enum":["rascunho","ativo"],"description":"Modo de sincronização do projeto"},"status":{"type":"string","enum":["em_andamento","finalizado","atrasado","arquivado"],"description":"Status do projeto, definido pelo sistema (somente leitura)"},"prazo":{"type":"string","format":"date","nullable":true,"description":"Prazo do projeto, ou `null` quando não informado"},"created_at":{"type":"string","format":"date-time","description":"Data e hora de criação"}}}}}}}},"400":{"description":"Corpo da requisição sem a raiz `projeto`","content":{"application/json":{"schema":{"type":"object","required":["error","validation"],"properties":{"error":{"type":"string","description":"Mensagem de erro"},"validation":{"type":"string","description":"Detalhe do parâmetro ausente"}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Erro indicando ausência ou invalidade da chave de API"}}}}}},"404":{"description":"Projeto não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"422":{"description":"status enviado no payload, tipo_sincronizacao alterado, ou tipo/prazo inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["projeto"],"properties":{"projeto":{"type":"object","properties":{"nome":{"type":"string","description":"Nome do projeto de catálogo"},"tipo":{"type":"string","enum":["importacao","exportacao"],"description":"Natureza do projeto"},"tipo_sincronizacao":{"type":"string","enum":["rascunho","ativo"],"description":"Não pode ser alterado — reenviar o valor já vigente é aceito (no-op); qualquer outro valor devolve 422."},"prazo":{"type":"string","format":"date","nullable":true,"description":"Prazo do projeto, exatamente no formato `AAAA-MM-DD`. Data já vencida marca o projeto como atrasado. Valor que não seja exatamente essa forma (ou não seja uma data de calendário válida) devolve 422. `null`/vazio limpa o prazo."},"status":{"type":"string","description":"Somente leitura — enviar esta chave, com qualquer valor, devolve 422."}}}}}}},"required":true}}}}}
```
