> 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"}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://changelog.maino.com.br/api-reference-maino/models.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.