> 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/models.md).

# Models

## The Error object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"Error":{"type":"object","description":"Schema padrão para respostas de erro da API","properties":{"error":{"type":"string","description":"Mensagem de erro amigável para o usuário"},"details":{"type":"string","description":"Detalhes técnicos do erro (opcional)"},"code":{"type":"integer","description":"Código interno de erro para debugging"},"timestamp":{"type":"string","format":"datetime","description":"Timestamp do erro"},"request_id":{"type":"string","description":"ID único da requisição para rastreamento"}},"required":["error","timestamp"]}}}}
```

## The ValidationErrors object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"ValidationErrors":{"type":"object","description":"Schema para erros de validação de formulários e dados","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Lista detalhada de erros de validação encontrados"},"field_errors":{"type":"object","description":"Mapa de erros por campo específico","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["errors"]}}}}
```

## The Pagination object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"Pagination":{"type":"object","description":"Informações de paginação - Schema genérico (não usado diretamente, ver StakeholdersPagination e ProdutosPagination)","properties":{"total":{"type":"integer","description":"Total de páginas ou registros (varia por endpoint)","minimum":0},"count":{"type":"integer","description":"Contagem de registros (apenas em alguns endpoints)","minimum":0},"previous_page":{"type":"string","format":"uri","nullable":true,"description":"URL completa da página anterior (null se for a primeira página)"},"next_page":{"type":"string","format":"uri","nullable":true,"description":"URL completa da próxima página (null se for a última página)"}}}}}}
```

## The StakeholdersPagination object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"StakeholdersPagination":{"type":"object","description":"Paginação específica do endpoint de stakeholders (baseado no index.json.jbuilder real)","properties":{"total":{"type":"integer","description":"Total de páginas disponíveis","minimum":0},"count":{"type":"integer","description":"Quantidade de registros retornados nesta página","minimum":0},"previous_page":{"type":"string","format":"uri","nullable":true,"description":"URL completa da página anterior (null se for a primeira página)"},"next_page":{"type":"string","format":"uri","nullable":true,"description":"URL completa da próxima página (null se for a última página)"}}}}}}
```

## The ProdutosPagination object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"ProdutosPagination":{"type":"object","description":"Paginação específica do endpoint de produtos (baseado no index.json.jbuilder real)","properties":{"total":{"type":"integer","description":"Total de registros encontrados (total_entries)","minimum":0},"previous_page":{"type":"string","format":"uri","nullable":true,"description":"URL completa da página anterior (null se for a primeira página)"},"next_page":{"type":"string","format":"uri","nullable":true,"description":"URL completa da próxima página (null se for a última página)"}}}}}}
```

## The Address object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"Address":{"type":"object","description":"Endereço completo brasileiro com validação de CEP","properties":{"logradouro":{"type":"string","description":"Nome da rua, avenida, etc.","maxLength":255},"numero":{"type":"string","description":"Número do endereço","maxLength":10},"complemento":{"type":"string","description":"Complemento (apartamento, sala, etc.)","maxLength":100},"bairro":{"type":"string","description":"Nome do bairro","maxLength":100},"cidade":{"type":"string","description":"Nome da cidade","maxLength":100},"uf":{"type":"string","description":"Sigla do estado (2 caracteres)","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$"},"cep":{"type":"string","description":"CEP no formato 12345-678","pattern":"^\\d{5}-\\d{3}$"},"ibge_codigo":{"type":"string","description":"Código IBGE da cidade"}},"required":["logradouro","cidade","uf","cep"]}}}}
```

## The Token object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"Token":{"type":"object","description":"Token JWT de autenticação","properties":{"token":{"type":"string","description":"Token JWT de acesso"},"refresh_token":{"type":"string","description":"Token para renovação"},"expires_in":{"type":"integer","description":"Tempo de expiração em segundos (24h)"},"token_type":{"type":"string","description":"Tipo do token"}},"required":["token","expires_in"]}}}}
```

## The Stakeholder object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"Stakeholder":{"type":"object","description":"Stakeholder - Cliente, fornecedor ou transportadora (baseado na view JBuilder real)","properties":{"id":{"type":"string","description":"UUID do stakeholder (retornado como id na API)"},"razao_social":{"type":"string","description":"Razão social ou nome completo","maxLength":255},"nome_fantasia":{"type":"string","description":"Nome fantasia da empresa","maxLength":255},"cnpj":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do stakeholder - apenas números, sem formatação. Nota: Na entrada (POST) usar o campo \"numero_do_documento\", na resposta retorna como \"cnpj\"","pattern":"^\\d{11}(\\d{3})?$"},"inscricao_estadual":{"type":"string","description":"Inscrição estadual"},"tipos":{"type":"array","items":{"type":"string"},"description":"Array com tipos de stakeholder","enum":[["cliente"],["fornecedor"],["transportadora"],["cliente","fornecedor"]]},"indicador_ie":{"type":"integer","description":"Código do indicador de IE"},"inscricao_suframa":{"type":"string","description":"Inscrição SUFRAMA"},"cep":{"type":"string","description":"CEP do stakeholder"},"endereco":{"type":"string","description":"Logradouro/endereço"},"numero":{"type":"string","description":"Número do endereço"},"complemento":{"type":"string","description":"Complemento do endereço"},"bairro":{"type":"string","description":"Bairro"},"municipio":{"type":"string","description":"Nome do município"},"uf":{"type":"string","description":"Nome da UF"},"contatos":{"type":"array","description":"Array de contatos do stakeholder (apenas se existirem)","items":{"type":"object","properties":{"id":{"type":"integer"},"nome":{"type":"string"},"email":{"type":"string"},"cargo":{"type":"string"},"ddi":{"type":"string"},"ddd":{"type":"string"},"telefone":{"type":"string"},"principal":{"type":"boolean"}}}}},"required":["id","razao_social","cnpj","tipos"]}}}}
```

## The Produto object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"Produto":{"type":"object","description":"Produto completo (baseado na view JBuilder real)","properties":{"id":{"type":"integer","description":"ID único do produto"},"codigo":{"type":"string","description":"Código interno do produto"},"descricao":{"type":"string","description":"Descrição do produto"},"informacoes_complementares":{"type":"string","description":"Informações complementares"},"principal_modelo_ecommerce":{"type":"boolean","description":"Se é o modelo principal para e-commerce"},"codigo_ecommerce":{"type":"string","description":"Código específico para e-commerce"},"titulo_ecommerce":{"type":"string","description":"Título para e-commerce"},"descricao_ecommerce":{"type":"string","description":"Descrição específica para e-commerce"},"marca":{"type":"string","description":"Marca do produto"},"modelo":{"type":"string","description":"Modelo do produto"},"nome_fabricante":{"type":"string","description":"Nome do fabricante"},"observacao_interna":{"type":"string","description":"Observação interna"},"peso_liquido":{"type":"number","format":"decimal","description":"Peso líquido total"},"peso_liquido_unitario":{"type":"number","format":"decimal","description":"Peso líquido unitário"},"peso_bruto":{"type":"number","format":"decimal","description":"Peso bruto total"},"peso_bruto_unitario":{"type":"number","format":"decimal","description":"Peso bruto unitário"},"pu":{"type":"number","format":"decimal","description":"Preço unitário de entrada (arredondado para 4 casas)"},"pu_saida":{"type":"number","format":"decimal","description":"Preço unitário de saída/venda"},"pu_saida_com_ipi":{"type":"number","format":"decimal","description":"Preço de saída com IPI incluído"},"valor_ipi":{"type":"number","format":"decimal","description":"Valor do IPI"},"aliquota_ipi":{"type":"number","format":"decimal","description":"Alíquota de IPI (percentual arredondado para 2 casas)"},"composicao_de_preco_de_venda":{"type":"boolean","description":"Composição de preço de venda"},"qtde":{"type":"number","format":"decimal","description":"Quantidade atual em estoque"},"qtde_comprometida":{"type":"number","format":"decimal","description":"Quantidade comprometida"},"qtde_armazenada":{"type":"number","format":"decimal","description":"Quantidade armazenada"},"gtin":{"type":"string","description":"Código de barras GTIN"},"codigo_de_barras_interno":{"type":"string","description":"Código de barras interno"},"ncm":{"type":"string","description":"Código NCM (classificacao_fiscal.classificacao)"},"unidade_de_medida":{"type":"string","description":"Código da unidade de medida"},"ativo":{"type":"boolean","description":"Se o produto está ativo (método ativo?)"},"ultima_modificacao":{"type":"string","format":"datetime","description":"Data da última modificação"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags customizadas do produto"},"altura":{"type":"number","format":"decimal","description":"Altura do produto"},"comprimento":{"type":"number","format":"decimal","description":"Comprimento do produto"},"largura":{"type":"number","format":"decimal","description":"Largura do produto"},"imagem_principal":{"type":"string","format":"uri","description":"URL da imagem principal"},"imagens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string","format":"uri"},"principal":{"type":"boolean"}}}},"categoria":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"nome":{"type":"string"}}},"subcategoria":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"nome":{"type":"string"},"nome_com_categoria":{"type":"string"}}},"propriedades":{"type":"array","items":{"type":"object","properties":{"propriedade":{"type":"string"},"valor":{"type":"string"}}}},"tabelas_de_vendas":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"descricao":{"type":"string"},"pu_calculado":{"type":"number","format":"decimal"}}}}},"required":["id","codigo","descricao","ativo"]}}}}
```

## The Recebimento object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"Recebimento":{"type":"object","description":"Conta a receber completa com relacionamentos","properties":{"id":{"type":"integer","description":"ID único da conta a receber"},"numero":{"type":"string","description":"Número identificador da conta","maxLength":50},"stakeholder":{"$ref":"#/components/schemas/Stakeholder"},"valor_original":{"type":"number","format":"decimal","description":"Valor original da conta","minimum":0},"valor_pago":{"type":"number","format":"decimal","description":"Valor já pago da conta","minimum":0},"valor_em_aberto":{"type":"number","format":"decimal","description":"Valor ainda em aberto","minimum":0},"data_vencimento":{"type":"string","format":"date","description":"Data de vencimento"},"data_emissao":{"type":"string","format":"date","description":"Data de emissão"},"status":{"type":"string","enum":["em_aberto","pago_parcial","pago_total","vencido","cancelado"],"description":"Status atual da conta"},"dias_atraso":{"type":"integer","description":"Dias em atraso (se vencido)","minimum":0},"plano_conta":{"type":"string","description":"Código do plano de contas","maxLength":20},"centro_custo":{"type":"string","description":"Centro de custo vinculado","maxLength":50},"observacoes":{"type":"string","description":"Observações sobre a conta","maxLength":1000},"tags":{"type":"array","items":{"type":"string"},"description":"Tags para categorização"}},"required":["numero","valor_original","data_vencimento","status"]},"Stakeholder":{"type":"object","description":"Stakeholder - Cliente, fornecedor ou transportadora (baseado na view JBuilder real)","properties":{"id":{"type":"string","description":"UUID do stakeholder (retornado como id na API)"},"razao_social":{"type":"string","description":"Razão social ou nome completo","maxLength":255},"nome_fantasia":{"type":"string","description":"Nome fantasia da empresa","maxLength":255},"cnpj":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do stakeholder - apenas números, sem formatação. Nota: Na entrada (POST) usar o campo \"numero_do_documento\", na resposta retorna como \"cnpj\"","pattern":"^\\d{11}(\\d{3})?$"},"inscricao_estadual":{"type":"string","description":"Inscrição estadual"},"tipos":{"type":"array","items":{"type":"string"},"description":"Array com tipos de stakeholder","enum":[["cliente"],["fornecedor"],["transportadora"],["cliente","fornecedor"]]},"indicador_ie":{"type":"integer","description":"Código do indicador de IE"},"inscricao_suframa":{"type":"string","description":"Inscrição SUFRAMA"},"cep":{"type":"string","description":"CEP do stakeholder"},"endereco":{"type":"string","description":"Logradouro/endereço"},"numero":{"type":"string","description":"Número do endereço"},"complemento":{"type":"string","description":"Complemento do endereço"},"bairro":{"type":"string","description":"Bairro"},"municipio":{"type":"string","description":"Nome do município"},"uf":{"type":"string","description":"Nome da UF"},"contatos":{"type":"array","description":"Array de contatos do stakeholder (apenas se existirem)","items":{"type":"object","properties":{"id":{"type":"integer"},"nome":{"type":"string"},"email":{"type":"string"},"cargo":{"type":"string"},"ddi":{"type":"string"},"ddd":{"type":"string"},"telefone":{"type":"string"},"principal":{"type":"boolean"}}}}},"required":["id","razao_social","cnpj","tipos"]}}}}
```

## The Pagamento object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"Pagamento":{"type":"object","description":"Conta a pagar completa com relacionamentos","properties":{"id":{"type":"integer","description":"ID único da conta a pagar"},"numero":{"type":"string","description":"Número identificador da conta","maxLength":50},"fornecedor":{"$ref":"#/components/schemas/Stakeholder"},"valor_original":{"type":"number","format":"decimal","description":"Valor original da conta","minimum":0},"valor_pago":{"type":"number","format":"decimal","description":"Valor já pago da conta","minimum":0},"valor_em_aberto":{"type":"number","format":"decimal","description":"Valor ainda em aberto","minimum":0},"data_vencimento":{"type":"string","format":"date","description":"Data de vencimento"},"data_emissao":{"type":"string","format":"date","description":"Data de emissão"},"status":{"type":"string","enum":["pendente","aprovado","pago_parcial","pago_total","vencido","cancelado"],"description":"Status atual da conta"},"forma_pagamento":{"$ref":"#/components/schemas/FormaPagamento"},"conta_bancaria":{"$ref":"#/components/schemas/ContaBancaria"},"centro_custo":{"type":"string","description":"Centro de custo vinculado","maxLength":50},"categoria":{"type":"string","description":"Categoria da despesa","maxLength":100}},"required":["numero","fornecedor","valor_original","data_vencimento","status"]},"Stakeholder":{"type":"object","description":"Stakeholder - Cliente, fornecedor ou transportadora (baseado na view JBuilder real)","properties":{"id":{"type":"string","description":"UUID do stakeholder (retornado como id na API)"},"razao_social":{"type":"string","description":"Razão social ou nome completo","maxLength":255},"nome_fantasia":{"type":"string","description":"Nome fantasia da empresa","maxLength":255},"cnpj":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do stakeholder - apenas números, sem formatação. Nota: Na entrada (POST) usar o campo \"numero_do_documento\", na resposta retorna como \"cnpj\"","pattern":"^\\d{11}(\\d{3})?$"},"inscricao_estadual":{"type":"string","description":"Inscrição estadual"},"tipos":{"type":"array","items":{"type":"string"},"description":"Array com tipos de stakeholder","enum":[["cliente"],["fornecedor"],["transportadora"],["cliente","fornecedor"]]},"indicador_ie":{"type":"integer","description":"Código do indicador de IE"},"inscricao_suframa":{"type":"string","description":"Inscrição SUFRAMA"},"cep":{"type":"string","description":"CEP do stakeholder"},"endereco":{"type":"string","description":"Logradouro/endereço"},"numero":{"type":"string","description":"Número do endereço"},"complemento":{"type":"string","description":"Complemento do endereço"},"bairro":{"type":"string","description":"Bairro"},"municipio":{"type":"string","description":"Nome do município"},"uf":{"type":"string","description":"Nome da UF"},"contatos":{"type":"array","description":"Array de contatos do stakeholder (apenas se existirem)","items":{"type":"object","properties":{"id":{"type":"integer"},"nome":{"type":"string"},"email":{"type":"string"},"cargo":{"type":"string"},"ddi":{"type":"string"},"ddd":{"type":"string"},"telefone":{"type":"string"},"principal":{"type":"boolean"}}}}},"required":["id","razao_social","cnpj","tipos"]},"FormaPagamento":{"type":"integer","description":"Códigos reais de formas de pagamento (baseado no model Documento)","enum":[1,2,3,4,5,6,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,99]},"ContaBancaria":{"type":"object","description":"Dados reais da conta corrente (baseado na view JBuilder real)","properties":{"codigo_conta_corrente":{"type":"string","description":"UUID da conta corrente (campo real retornado)"},"numero_banco":{"type":"string","description":"Código do banco (3 dígitos)"},"nome_banco":{"type":"string","description":"Nome do banco"},"descricao":{"type":"string","description":"Descrição da conta corrente"},"agencia":{"type":"string","description":"Agência com dígito verificador (método agencia_com_digito)"},"conta_corrente":{"type":"string","description":"Conta corrente com dígito verificador (método conta_corrente_com_digito)"},"emite_boleto_pjbank":{"type":"boolean","description":"Se a conta pode emitir boletos via PJBank (campo real retornado)"},"ativa":{"type":"boolean","description":"Se a conta está ativa para movimentação"}},"required":["codigo_conta_corrente","numero_banco","nome_banco","ativa"]}}}}
```

## The ContaBancaria object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"ContaBancaria":{"type":"object","description":"Dados reais da conta corrente (baseado na view JBuilder real)","properties":{"codigo_conta_corrente":{"type":"string","description":"UUID da conta corrente (campo real retornado)"},"numero_banco":{"type":"string","description":"Código do banco (3 dígitos)"},"nome_banco":{"type":"string","description":"Nome do banco"},"descricao":{"type":"string","description":"Descrição da conta corrente"},"agencia":{"type":"string","description":"Agência com dígito verificador (método agencia_com_digito)"},"conta_corrente":{"type":"string","description":"Conta corrente com dígito verificador (método conta_corrente_com_digito)"},"emite_boleto_pjbank":{"type":"boolean","description":"Se a conta pode emitir boletos via PJBank (campo real retornado)"},"ativa":{"type":"boolean","description":"Se a conta está ativa para movimentação"}},"required":["codigo_conta_corrente","numero_banco","nome_banco","ativa"]}}}}
```

## The ModalidadeEmpresa object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"ModalidadeEmpresa":{"type":"integer","description":"Modalidade fiscal da empresa","enum":[1,2,3,4]}}}}
```

## The TipoEstabelecimento object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"TipoEstabelecimento":{"type":"integer","description":"Tipo de estabelecimento comercial","enum":[1,2,3]}}}}
```

## The CSOSN object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"CSOSN":{"type":"string","description":"Código de Situação da Operação - Simples Nacional","enum":["103","300","400","900"]}}}}
```

## The ModalidadeFrete object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"ModalidadeFrete":{"type":"integer","description":"Modalidade de frete para transporte de mercadorias","enum":[0,1,2,3,4,9]}}}}
```

## The FormaPagamento object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"FormaPagamento":{"type":"integer","description":"Códigos reais de formas de pagamento (baseado no model Documento)","enum":[1,2,3,4,5,6,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,99]}}}}
```

## The OrigemProduto object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"OrigemProduto":{"type":"integer","description":"Origem do produto para fins fiscais","enum":[0,1,2,3,4,5,6,7,8]}}}}
```

## The StatusNotaFiscal object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"StatusNotaFiscal":{"type":"string","description":"Status reais de uma NF-e (códigos de 1 letra do model NotaFiscalConstantes)","enum":["A","C","D","CF","P","F","N","T","R","DC"]}}}}
```

## The NotaFiscalCompleta object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"NotaFiscalCompleta":{"type":"object","description":"Nota fiscal eletrônica completa","properties":{"id":{"type":"integer","description":"ID único da NF-e"},"numero":{"type":"string","description":"Número da nota fiscal"},"serie":{"type":"string","description":"Série da nota fiscal"},"chave_acesso":{"type":"string","description":"Chave de acesso da NF-e (44 dígitos)","pattern":"^\\d{44}$"},"status":{"$ref":"#/components/schemas/StatusNotaFiscal"},"tipo_operacao":{"type":"string","enum":["entrada","saida"],"description":"Tipo da operação"},"data_emissao":{"type":"string","format":"datetime","description":"Data e hora de emissão"},"destinatario":{"$ref":"#/components/schemas/Stakeholder"},"valores":{"type":"object","properties":{"valor_produtos":{"type":"number","format":"decimal","description":"Valor total dos produtos"},"valor_frete":{"type":"number","format":"decimal","description":"Valor do frete"},"valor_seguro":{"type":"number","format":"decimal","description":"Valor do seguro"},"valor_desconto":{"type":"number","format":"decimal","description":"Valor do desconto"},"valor_total":{"type":"number","format":"decimal","description":"Valor total da nota"},"valor_icms":{"type":"number","format":"decimal","description":"Valor do ICMS"},"valor_ipi":{"type":"number","format":"decimal","description":"Valor do IPI"}}},"items":{"type":"array","items":{"type":"object","properties":{"numero_item":{"type":"integer","description":"Número sequencial do item"},"produto":{"$ref":"#/components/schemas/ProdutoCompleto"},"quantidade":{"type":"number","format":"decimal","description":"Quantidade do item"},"valor_unitario":{"type":"number","format":"decimal","description":"Valor unitário"},"valor_total":{"type":"number","format":"decimal","description":"Valor total do item"},"cfop":{"type":"string","description":"CFOP da operação","pattern":"^\\d{4}$"}}}}},"required":["numero","serie","status","tipo_operacao","data_emissao","destinatario","valores"]},"StatusNotaFiscal":{"type":"string","description":"Status reais de uma NF-e (códigos de 1 letra do model NotaFiscalConstantes)","enum":["A","C","D","CF","P","F","N","T","R","DC"]},"Stakeholder":{"type":"object","description":"Stakeholder - Cliente, fornecedor ou transportadora (baseado na view JBuilder real)","properties":{"id":{"type":"string","description":"UUID do stakeholder (retornado como id na API)"},"razao_social":{"type":"string","description":"Razão social ou nome completo","maxLength":255},"nome_fantasia":{"type":"string","description":"Nome fantasia da empresa","maxLength":255},"cnpj":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do stakeholder - apenas números, sem formatação. Nota: Na entrada (POST) usar o campo \"numero_do_documento\", na resposta retorna como \"cnpj\"","pattern":"^\\d{11}(\\d{3})?$"},"inscricao_estadual":{"type":"string","description":"Inscrição estadual"},"tipos":{"type":"array","items":{"type":"string"},"description":"Array com tipos de stakeholder","enum":[["cliente"],["fornecedor"],["transportadora"],["cliente","fornecedor"]]},"indicador_ie":{"type":"integer","description":"Código do indicador de IE"},"inscricao_suframa":{"type":"string","description":"Inscrição SUFRAMA"},"cep":{"type":"string","description":"CEP do stakeholder"},"endereco":{"type":"string","description":"Logradouro/endereço"},"numero":{"type":"string","description":"Número do endereço"},"complemento":{"type":"string","description":"Complemento do endereço"},"bairro":{"type":"string","description":"Bairro"},"municipio":{"type":"string","description":"Nome do município"},"uf":{"type":"string","description":"Nome da UF"},"contatos":{"type":"array","description":"Array de contatos do stakeholder (apenas se existirem)","items":{"type":"object","properties":{"id":{"type":"integer"},"nome":{"type":"string"},"email":{"type":"string"},"cargo":{"type":"string"},"ddi":{"type":"string"},"ddd":{"type":"string"},"telefone":{"type":"string"},"principal":{"type":"boolean"}}}}},"required":["id","razao_social","cnpj","tipos"]},"ProdutoCompleto":{"type":"object","description":"Produto completo com informações fiscais e de estoque","allOf":[{"$ref":"#/components/schemas/Produto"},{"type":"object","properties":{"ncm":{"type":"string","description":"Código NCM (8 dígitos)","pattern":"^\\d{8}$"},"cest":{"type":"string","description":"Código CEST (7 dígitos)","pattern":"^\\d{7}$"},"origem":{"$ref":"#/components/schemas/OrigemProduto"},"tributacao":{"type":"object","properties":{"cst_icms":{"type":"string","description":"CST do ICMS"},"cst_pis":{"type":"string","description":"CST do PIS"},"cst_cofins":{"type":"string","description":"CST da COFINS"},"aliquota_icms":{"type":"number","format":"decimal","description":"Alíquota do ICMS (%)"}}},"estoque":{"type":"object","properties":{"quantidade_atual":{"type":"number","format":"decimal","description":"Quantidade atual em estoque"},"quantidade_minima":{"type":"number","format":"decimal","description":"Estoque mínimo"},"localizacao":{"type":"string","description":"Localização no estoque"},"custo_medio":{"type":"number","format":"decimal","description":"Custo médio do produto"}}},"fornecedor_padrao":{"$ref":"#/components/schemas/Stakeholder"}}}]},"Produto":{"type":"object","description":"Produto completo (baseado na view JBuilder real)","properties":{"id":{"type":"integer","description":"ID único do produto"},"codigo":{"type":"string","description":"Código interno do produto"},"descricao":{"type":"string","description":"Descrição do produto"},"informacoes_complementares":{"type":"string","description":"Informações complementares"},"principal_modelo_ecommerce":{"type":"boolean","description":"Se é o modelo principal para e-commerce"},"codigo_ecommerce":{"type":"string","description":"Código específico para e-commerce"},"titulo_ecommerce":{"type":"string","description":"Título para e-commerce"},"descricao_ecommerce":{"type":"string","description":"Descrição específica para e-commerce"},"marca":{"type":"string","description":"Marca do produto"},"modelo":{"type":"string","description":"Modelo do produto"},"nome_fabricante":{"type":"string","description":"Nome do fabricante"},"observacao_interna":{"type":"string","description":"Observação interna"},"peso_liquido":{"type":"number","format":"decimal","description":"Peso líquido total"},"peso_liquido_unitario":{"type":"number","format":"decimal","description":"Peso líquido unitário"},"peso_bruto":{"type":"number","format":"decimal","description":"Peso bruto total"},"peso_bruto_unitario":{"type":"number","format":"decimal","description":"Peso bruto unitário"},"pu":{"type":"number","format":"decimal","description":"Preço unitário de entrada (arredondado para 4 casas)"},"pu_saida":{"type":"number","format":"decimal","description":"Preço unitário de saída/venda"},"pu_saida_com_ipi":{"type":"number","format":"decimal","description":"Preço de saída com IPI incluído"},"valor_ipi":{"type":"number","format":"decimal","description":"Valor do IPI"},"aliquota_ipi":{"type":"number","format":"decimal","description":"Alíquota de IPI (percentual arredondado para 2 casas)"},"composicao_de_preco_de_venda":{"type":"boolean","description":"Composição de preço de venda"},"qtde":{"type":"number","format":"decimal","description":"Quantidade atual em estoque"},"qtde_comprometida":{"type":"number","format":"decimal","description":"Quantidade comprometida"},"qtde_armazenada":{"type":"number","format":"decimal","description":"Quantidade armazenada"},"gtin":{"type":"string","description":"Código de barras GTIN"},"codigo_de_barras_interno":{"type":"string","description":"Código de barras interno"},"ncm":{"type":"string","description":"Código NCM (classificacao_fiscal.classificacao)"},"unidade_de_medida":{"type":"string","description":"Código da unidade de medida"},"ativo":{"type":"boolean","description":"Se o produto está ativo (método ativo?)"},"ultima_modificacao":{"type":"string","format":"datetime","description":"Data da última modificação"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags customizadas do produto"},"altura":{"type":"number","format":"decimal","description":"Altura do produto"},"comprimento":{"type":"number","format":"decimal","description":"Comprimento do produto"},"largura":{"type":"number","format":"decimal","description":"Largura do produto"},"imagem_principal":{"type":"string","format":"uri","description":"URL da imagem principal"},"imagens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string","format":"uri"},"principal":{"type":"boolean"}}}},"categoria":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"nome":{"type":"string"}}},"subcategoria":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"nome":{"type":"string"},"nome_com_categoria":{"type":"string"}}},"propriedades":{"type":"array","items":{"type":"object","properties":{"propriedade":{"type":"string"},"valor":{"type":"string"}}}},"tabelas_de_vendas":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"descricao":{"type":"string"},"pu_calculado":{"type":"number","format":"decimal"}}}}},"required":["id","codigo","descricao","ativo"]},"OrigemProduto":{"type":"integer","description":"Origem do produto para fins fiscais","enum":[0,1,2,3,4,5,6,7,8]}}}}
```

## The ProdutoCompleto object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"ProdutoCompleto":{"type":"object","description":"Produto completo com informações fiscais e de estoque","allOf":[{"$ref":"#/components/schemas/Produto"},{"type":"object","properties":{"ncm":{"type":"string","description":"Código NCM (8 dígitos)","pattern":"^\\d{8}$"},"cest":{"type":"string","description":"Código CEST (7 dígitos)","pattern":"^\\d{7}$"},"origem":{"$ref":"#/components/schemas/OrigemProduto"},"tributacao":{"type":"object","properties":{"cst_icms":{"type":"string","description":"CST do ICMS"},"cst_pis":{"type":"string","description":"CST do PIS"},"cst_cofins":{"type":"string","description":"CST da COFINS"},"aliquota_icms":{"type":"number","format":"decimal","description":"Alíquota do ICMS (%)"}}},"estoque":{"type":"object","properties":{"quantidade_atual":{"type":"number","format":"decimal","description":"Quantidade atual em estoque"},"quantidade_minima":{"type":"number","format":"decimal","description":"Estoque mínimo"},"localizacao":{"type":"string","description":"Localização no estoque"},"custo_medio":{"type":"number","format":"decimal","description":"Custo médio do produto"}}},"fornecedor_padrao":{"$ref":"#/components/schemas/Stakeholder"}}}]},"Produto":{"type":"object","description":"Produto completo (baseado na view JBuilder real)","properties":{"id":{"type":"integer","description":"ID único do produto"},"codigo":{"type":"string","description":"Código interno do produto"},"descricao":{"type":"string","description":"Descrição do produto"},"informacoes_complementares":{"type":"string","description":"Informações complementares"},"principal_modelo_ecommerce":{"type":"boolean","description":"Se é o modelo principal para e-commerce"},"codigo_ecommerce":{"type":"string","description":"Código específico para e-commerce"},"titulo_ecommerce":{"type":"string","description":"Título para e-commerce"},"descricao_ecommerce":{"type":"string","description":"Descrição específica para e-commerce"},"marca":{"type":"string","description":"Marca do produto"},"modelo":{"type":"string","description":"Modelo do produto"},"nome_fabricante":{"type":"string","description":"Nome do fabricante"},"observacao_interna":{"type":"string","description":"Observação interna"},"peso_liquido":{"type":"number","format":"decimal","description":"Peso líquido total"},"peso_liquido_unitario":{"type":"number","format":"decimal","description":"Peso líquido unitário"},"peso_bruto":{"type":"number","format":"decimal","description":"Peso bruto total"},"peso_bruto_unitario":{"type":"number","format":"decimal","description":"Peso bruto unitário"},"pu":{"type":"number","format":"decimal","description":"Preço unitário de entrada (arredondado para 4 casas)"},"pu_saida":{"type":"number","format":"decimal","description":"Preço unitário de saída/venda"},"pu_saida_com_ipi":{"type":"number","format":"decimal","description":"Preço de saída com IPI incluído"},"valor_ipi":{"type":"number","format":"decimal","description":"Valor do IPI"},"aliquota_ipi":{"type":"number","format":"decimal","description":"Alíquota de IPI (percentual arredondado para 2 casas)"},"composicao_de_preco_de_venda":{"type":"boolean","description":"Composição de preço de venda"},"qtde":{"type":"number","format":"decimal","description":"Quantidade atual em estoque"},"qtde_comprometida":{"type":"number","format":"decimal","description":"Quantidade comprometida"},"qtde_armazenada":{"type":"number","format":"decimal","description":"Quantidade armazenada"},"gtin":{"type":"string","description":"Código de barras GTIN"},"codigo_de_barras_interno":{"type":"string","description":"Código de barras interno"},"ncm":{"type":"string","description":"Código NCM (classificacao_fiscal.classificacao)"},"unidade_de_medida":{"type":"string","description":"Código da unidade de medida"},"ativo":{"type":"boolean","description":"Se o produto está ativo (método ativo?)"},"ultima_modificacao":{"type":"string","format":"datetime","description":"Data da última modificação"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags customizadas do produto"},"altura":{"type":"number","format":"decimal","description":"Altura do produto"},"comprimento":{"type":"number","format":"decimal","description":"Comprimento do produto"},"largura":{"type":"number","format":"decimal","description":"Largura do produto"},"imagem_principal":{"type":"string","format":"uri","description":"URL da imagem principal"},"imagens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string","format":"uri"},"principal":{"type":"boolean"}}}},"categoria":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"nome":{"type":"string"}}},"subcategoria":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"nome":{"type":"string"},"nome_com_categoria":{"type":"string"}}},"propriedades":{"type":"array","items":{"type":"object","properties":{"propriedade":{"type":"string"},"valor":{"type":"string"}}}},"tabelas_de_vendas":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"descricao":{"type":"string"},"pu_calculado":{"type":"number","format":"decimal"}}}}},"required":["id","codigo","descricao","ativo"]},"OrigemProduto":{"type":"integer","description":"Origem do produto para fins fiscais","enum":[0,1,2,3,4,5,6,7,8]},"Stakeholder":{"type":"object","description":"Stakeholder - Cliente, fornecedor ou transportadora (baseado na view JBuilder real)","properties":{"id":{"type":"string","description":"UUID do stakeholder (retornado como id na API)"},"razao_social":{"type":"string","description":"Razão social ou nome completo","maxLength":255},"nome_fantasia":{"type":"string","description":"Nome fantasia da empresa","maxLength":255},"cnpj":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do stakeholder - apenas números, sem formatação. Nota: Na entrada (POST) usar o campo \"numero_do_documento\", na resposta retorna como \"cnpj\"","pattern":"^\\d{11}(\\d{3})?$"},"inscricao_estadual":{"type":"string","description":"Inscrição estadual"},"tipos":{"type":"array","items":{"type":"string"},"description":"Array com tipos de stakeholder","enum":[["cliente"],["fornecedor"],["transportadora"],["cliente","fornecedor"]]},"indicador_ie":{"type":"integer","description":"Código do indicador de IE"},"inscricao_suframa":{"type":"string","description":"Inscrição SUFRAMA"},"cep":{"type":"string","description":"CEP do stakeholder"},"endereco":{"type":"string","description":"Logradouro/endereço"},"numero":{"type":"string","description":"Número do endereço"},"complemento":{"type":"string","description":"Complemento do endereço"},"bairro":{"type":"string","description":"Bairro"},"municipio":{"type":"string","description":"Nome do município"},"uf":{"type":"string","description":"Nome da UF"},"contatos":{"type":"array","description":"Array de contatos do stakeholder (apenas se existirem)","items":{"type":"object","properties":{"id":{"type":"integer"},"nome":{"type":"string"},"email":{"type":"string"},"cargo":{"type":"string"},"ddi":{"type":"string"},"ddd":{"type":"string"},"telefone":{"type":"string"},"principal":{"type":"boolean"}}}}},"required":["id","razao_social","cnpj","tipos"]}}}}
```

## The DeclaracaoImportacao object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"DeclaracaoImportacao":{"type":"object","description":"Declaração de Importação (DI)","properties":{"id":{"type":"integer","description":"ID único da DI"},"numero_di":{"type":"string","description":"Número da Declaração de Importação","maxLength":15},"data_registro":{"type":"string","format":"date","description":"Data de registro da DI"},"numero_processo":{"type":"string","description":"Número do processo no sistema","maxLength":50},"importador":{"$ref":"#/components/schemas/Stakeholder"},"pais_origem":{"type":"object","properties":{"codigo":{"type":"string","description":"Código do país (3 letras)","pattern":"^[A-Z]{3}$"},"nome":{"type":"string","description":"Nome do país"}}},"via_transporte":{"type":"string","enum":["maritima","aerea","rodoviaria","ferroviaria"],"description":"Via de transporte utilizada"},"valor_total_usd":{"type":"number","format":"decimal","description":"Valor total em USD"},"impostos":{"type":"object","properties":{"imposto_importacao":{"type":"number","format":"decimal","description":"Valor do Imposto de Importação"},"ipi":{"type":"number","format":"decimal","description":"Valor do IPI"},"pis":{"type":"number","format":"decimal","description":"Valor do PIS"},"cofins":{"type":"number","format":"decimal","description":"Valor da COFINS"}}},"status":{"type":"string","enum":["registrada","desembaracada","entregue","cancelada"],"description":"Status da DI"}},"required":["numero_di","data_registro","importador","pais_origem","valor_total_usd","status"]},"Stakeholder":{"type":"object","description":"Stakeholder - Cliente, fornecedor ou transportadora (baseado na view JBuilder real)","properties":{"id":{"type":"string","description":"UUID do stakeholder (retornado como id na API)"},"razao_social":{"type":"string","description":"Razão social ou nome completo","maxLength":255},"nome_fantasia":{"type":"string","description":"Nome fantasia da empresa","maxLength":255},"cnpj":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do stakeholder - apenas números, sem formatação. Nota: Na entrada (POST) usar o campo \"numero_do_documento\", na resposta retorna como \"cnpj\"","pattern":"^\\d{11}(\\d{3})?$"},"inscricao_estadual":{"type":"string","description":"Inscrição estadual"},"tipos":{"type":"array","items":{"type":"string"},"description":"Array com tipos de stakeholder","enum":[["cliente"],["fornecedor"],["transportadora"],["cliente","fornecedor"]]},"indicador_ie":{"type":"integer","description":"Código do indicador de IE"},"inscricao_suframa":{"type":"string","description":"Inscrição SUFRAMA"},"cep":{"type":"string","description":"CEP do stakeholder"},"endereco":{"type":"string","description":"Logradouro/endereço"},"numero":{"type":"string","description":"Número do endereço"},"complemento":{"type":"string","description":"Complemento do endereço"},"bairro":{"type":"string","description":"Bairro"},"municipio":{"type":"string","description":"Nome do município"},"uf":{"type":"string","description":"Nome da UF"},"contatos":{"type":"array","description":"Array de contatos do stakeholder (apenas se existirem)","items":{"type":"object","properties":{"id":{"type":"integer"},"nome":{"type":"string"},"email":{"type":"string"},"cargo":{"type":"string"},"ddi":{"type":"string"},"ddd":{"type":"string"},"telefone":{"type":"string"},"principal":{"type":"boolean"}}}}},"required":["id","razao_social","cnpj","tipos"]}}}}
```

## The WebhookEvent object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"WebhookEvent":{"type":"object","description":"Estrutura padrão de eventos de webhook","properties":{"id":{"type":"string","format":"uuid","description":"ID único do evento"},"event_type":{"type":"string","description":"Tipo do evento","enum":["nfe.status_changed","payment.received","stock.low_inventory","user.created"]},"timestamp":{"type":"string","format":"datetime","description":"Data e hora do evento"},"data":{"type":"object","description":"Dados específicos do evento","additionalProperties":true},"metadata":{"type":"object","properties":{"source":{"type":"string","description":"Origem do evento"},"version":{"type":"string","description":"Versão da API"},"correlation_id":{"type":"string","description":"ID de correlação para rastreamento"}}}},"required":["id","event_type","timestamp","data"]}}}}
```

## The IntegracaoSAP object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"IntegracaoSAP":{"type":"object","description":"Dados de integração com SAP ERP","properties":{"sap_id":{"type":"string","description":"ID do registro no SAP","maxLength":20},"tipo_objeto":{"type":"string","enum":["material","cliente","fornecedor","pedido","nota_fiscal"],"description":"Tipo de objeto SAP"},"ultima_sincronizacao":{"type":"string","format":"datetime","description":"Data da última sincronização"},"status_sync":{"type":"string","enum":["sincronizado","pendente","erro","conflito"],"description":"Status da sincronização"},"detalhes_erro":{"type":"string","description":"Detalhes do erro (se houver)"},"dados_mapeamento":{"type":"object","description":"Mapeamento de campos entre sistemas","additionalProperties":true}},"required":["sap_id","tipo_objeto","status_sync"]}}}}
```

## The PaginationInfo object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"PaginationInfo":{"type":"object","description":"Informações completas de paginação com navegação","allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"first_page":{"type":"string","format":"uri","description":"URL da primeira página"},"last_page":{"type":"string","format":"uri","description":"URL da última página"},"next_page":{"type":"string","format":"uri","nullable":true,"description":"URL da próxima página"},"previous_page":{"type":"string","format":"uri","nullable":true,"description":"URL da página anterior"}}}]},"Pagination":{"type":"object","description":"Informações de paginação - Schema genérico (não usado diretamente, ver StakeholdersPagination e ProdutosPagination)","properties":{"total":{"type":"integer","description":"Total de páginas ou registros (varia por endpoint)","minimum":0},"count":{"type":"integer","description":"Contagem de registros (apenas em alguns endpoints)","minimum":0},"previous_page":{"type":"string","format":"uri","nullable":true,"description":"URL completa da página anterior (null se for a primeira página)"},"next_page":{"type":"string","format":"uri","nullable":true,"description":"URL completa da próxima página (null se for a última página)"}}}}}}
```

## The FiltroAvancado object

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"components":{"schemas":{"FiltroAvancado":{"type":"object","description":"Sistema avançado de filtros para consultas","properties":{"data_inicio":{"type":"string","format":"date","description":"Data inicial do filtro"},"data_fim":{"type":"string","format":"date","description":"Data final do filtro"},"status":{"type":"array","items":{"type":"string"},"description":"Lista de status para filtrar"},"valor_minimo":{"type":"number","format":"decimal","description":"Valor mínimo para filtro"},"valor_maximo":{"type":"number","format":"decimal","description":"Valor máximo para filtro"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags para filtrar"},"busca_textual":{"type":"string","description":"Busca textual em campos relevantes"},"ordenacao":{"type":"object","properties":{"campo":{"type":"string","description":"Campo para ordenação"},"direcao":{"type":"string","enum":["asc","desc"],"description":"Direção da ordenação"}}}}}}}}
```