Campos de retorno e envio da ApiMp

Neste artigo, vamos falar sobre a estrutura de campos da ApiMp, organizados por tabela e método utilizado.

Você aprenderá quais campos são exigidos em cada operação, quais dados são retornados em cada resposta e quais regras ou validações aplicar em cada um deles.

Vendedores

Vendedores seriam os usuários que vão acessar o Demander mobile e Web, sendo vendedores ou gerentes, dependendo do nível de permissão e funcionalidades liberadas no sistema.

Endpoint

api-mp/v1/usuarios

Corpo de retorno do GET

Campo	Tipo	Descrição
id	Integer	Identificador único de controle do Demander.
nome	String:100	Nome do vendedor/gerente/usuário.
email	String:75	E-mail único.
telefone	String:15	Telefone do vendedor/gerente/usuário.
administrador	Integer:1	Indica se é gerente ou vendedor.
acesso_bloqueado	Integer:1	Indica se o vendedor/gerente/usuário está bloqueado.
excluido	Integer:1	Indica se o vendedor/gerente/usuário está inativo.
ultima_alteracao	DateTime	Data e hora da última modificação.

Grupos de produtos

Grupos de Produto representam categorias ou classificações utilizadas para organizar os produtos. Servem para facilitar a navegação, aplicação de filtros, regras comerciais ou segmentações nos módulos Web e Mobile do Demander.

Endpoint

api-mp/v1/categorias

Corpo de envio

Campo	Tipo	Descrição
nome*	String:50	Nome do grupo de produto.
categoria_pai_id	Integer	Identificador único do grupo de produto pai.
excluido	Integer:1	Indica se o grupo de produto está inativo.

Listas de preço

Listas de Preço definem os valores praticados para grupos específicos de clientes ou regiões. Cada produto pode ter diferentes preços conforme a lista associada, permitindo flexibilidade comercial.

Endpoint

api-mp/v1/tabelas_preco

Corpo de envio

Campo	Tipo	Descrição
nome*	String:100	Nome da lista de preço.
tipo*	String:2	Valores possíveis: P - preço livre. A - acréscimo. D - desconto.
acrescimo	Float	Valor de acréscimo a ser aplicado nas listas de tipo "A".
desconto	Float	Valor de desconto a ser aplicado nas listas de tipo "D"
excluido	Integer:1	Indica se a lista de preço está inativa.

Status do pedido

Status do Pedido representam as etapas do ciclo de um pedido, como “Em análise”, “Aprovado” ou “Faturado”. São essenciais para o acompanhamento e controle de processos dentro do sistema.

Endpoint

api-mp/v1/pedidos/status

Corpo de envio

Campo	Tipo	Descrição
nome*	String:50	Nome do status do pedido.
excluido	Integer	Indica se o status está inativo.

Preços do produto

Preços do produto contempla a relação entre o produto, lista de preço e o valor. Permite o controle de preços diferenciados conforme o contexto comercial.

Endpoint

api-mp/v1/produtos_tabela_preco

Corpo de envio

Campo	Tipo	Descrição
preco*	Float	Preço do produto para a tabela em questão.
tabela_id*	Integer	Identificador único da tabela do preço.
produto_id*	Integer	Identificador único do produto do preço.

Produtos

Produtos são os itens disponíveis para venda. Esta tabela contém as principais informações como código, descrição, grupo, estoque, preço base, entre outros dados necessários para o processo de vendas.

Endpoint

api-mp/v1/produtos

Corpo de envio

Campo	Tipo	Descrição
codigo*	String:30	Código do produto.
nome*	String:300	Nome do produto.
unidade	String:5	Informa se o produto é vendido em CX, FD, UN, entre outros.
saldo_estoque	Decimal(15,4)	Saldo de estoque do produto.
observacoes	String:5000	Substitua as quebras de linha por "\n".
categoria_id	Integer	Identificador único do grupo de produto.
codigo_ncm	String:50	Código do NCM do produto.
ativo*	Integer:1	Indica se o produto está ativo ou inativo.
excluido	Integer:1	Indica se o produto está ativo ou inativo.

Pedidos

Pedidos são os registros de vendas realizados pelos vendedores, contendo dados do cliente, itens vendidos, forma de pagamento, transportadora, status e demais informações associadas à transação.

Endpoint

api-mp/v2/pedidos

Corpo de retorno do GET

Campo	Tipo	Descrição
id	Integer	Identificador único de controle do Demander.
pedido_origem_id	Integer	Não utilizado.
transportadora_id	Integer	Identificador único da transportadora do pedido.
transportadora_nome	String:500	Nome da transportadora do pedido.
tipo_pedido_id	Integer	Identificador único do tipo de pedido do pedido.
criador_id	Integer	Identificador único do vendedor do pedido.
nome_contato	String:50	Contato do cliente do pedido.
status	Integer:1	Varia conforme o campo "consideraPedido" do cadastro de Tipos de Pedido. 1 - Orçamento. 2 - Pedido.
numero	Integer:10	Número do pedido.
rastreamento	String:200	Não utilizado.
valor_frete	Decimal(15,2)	Valor do frete digitado ou calculado no pedido.
total	Decimal(15,2)	Valor total do pedido (valor dos produtos + valor frete + valor IPI + valor ST + juros/desconto pela forma de pagamento).
condicao_pagamento	String:255	Nome da condição de pagamento escolhida no pedido.
condicao_pagamento_id	Integer	Identificador único da condição de pagamento escolhida no pedido.
forma_pagamento_id	Integer	Identificador único da forma de pagamento escolhida no pedido.
data_emissao	DateTime	Data de emissão do pedido. Data e horário em que o vendedor iniciou a digitação do pedido.
observacoes	String:1000	Observação interna digitada no pedido.
filialDemander	String:15	Código da filial digitada no pedido.
itens	Lista	Especificado no corpo de retorno da listagem de itens.
extras	Lista	Não utilizado.
cliente_id	Integer	Identificador único do cliente escolhido no pedido.
cliente_razao_social	String:100	Razão social do cliente escolhido no pedido.
cliente_nome_fantasia	String:100	Nome Fantasia do cliente escolhido no pedido.
cliente_cnpj	String:18	CNPJ ou CPF do cliente escolhido no pedido. Com máscara.
cliente_inscricao_estadual	String:20	RG ou Inscrição estadual do cliente escolhido no pedido.
cliente_rua	String:100	Endereço do cliente escolhido no pedido.
cliente_numero	Integer:10	Número do endereço do cliente escolhido no pedido.
cliente_complemento	String:200	Complemento do endereço do cliente escolhido no pedido.
cliente_cep	String:10	CEP do cliente escolhido no pedido. Com máscara.
cliente_bairro	String:50	Bairro do cliente escolhido no pedido.
cliente_cidade	String:100	Nome da cidade do cliente escolhido no pedido.
cliente_estado	String:2	Sigla de UF do cliente escolhido no pedido.
cliente_suframa	String:20	Não utilizado.
cliente_telefone	Lista	Lista com o campo de número de telefone do cliente. No Demander trabalhamos somente com dois telefones.
cliente_email	Lista	Lista com o campo de e-mail do cliente. No Demander trabalhamos somente com três e-mails.
contato_nome	String:50	Não utilizado.
representada_id	Integer	Identificador único do vendedor do pedido.
representada_nome_fantasia	String:100	Nome do vendedor que emitiu o pedido.
representada_razao_social	String:100	Nome do vendedor que emitiu o pedido.
status_faturamento	Integer	0 = Não faturado. 1 = Parcialmente faturado. 2 = Faturado.
status_custom_id	Integer	Código do status do pedido.
status_b2b	Integer	Não utilizado.
endereco_entrega	Lista	Não utilizado.
data_criacao	DateTime	Data de sincronização do pedido no Demander Web.
ultima_alteracao	DateTime	Data da última alteração do pedido.
cupom_de_desconto	String:50	Não utilizado.
percentual_total_comissao_pedido	Double	Não utilizado.
comissoes_vendedores	Lista	Não utilizado.
possui_informacao_pagamento	Boolean	Não utilizado.
prazo_entrega	String:100	Previsão de entrega digitada pelo vendedor no pedido.

Corpo de retorno da listagem de itens

Campo	Tipo	Descrição
id	Integer	Identificador único de controle do Demander.
produto_id	Integer	Identificador único do produto no item do pedido.
produto_codigo	String:30	Código do produto do item de pedido.
produto_nome	String:300	Nome do produto do item de pedido.
tabela_preco_id	Integer	Identificador único da lista de preço no item do pedido.
quantidade	Decimal	Quantidade do item do pedido.
preco_tabela	Decimal	Valor unitário do produto sem desconto.
preco_liquido	Decimal	Valor unitário do produto com desconto.
cotacao_moeda	Decimal	Não utilizado.
descontos_do_vendedor	Lista	Lista que contém os acréscimos e descontos aplicados no item. Acréscimos são valores negativos.
descontos_de_promocao	Lista	Não utilizado.
descontos_de_politicas	Lista	Não utilizado.
quantidade_grades	Lista	Não utilizado.
desconto_de_cupom	Double	Não utilizado.
observacoes	String	Observação do item do pedido.
excluido	Boolean	Fixo 'false'.
ipi	Float	Valor do IPI do item do pedido.
tipo_ipi	Char	Fixo 'V' (valor).
st	Float	Valor do ST do item do pedido.
subtotal	Float	Valor total do item com impostos.
grupo_grades	Integer	Não utilizado.
produto_agregador_id	Integer	Não utilizado.

Clientes

Clientes são as empresas ou pessoas que compram produtos através do Demander. A tabela reúne informações cadastrais, como CNPJ, razão social, endereço, contatos e regras comerciais.

Endpoint

api-mp/v1/clientes

Corpo de retorno do GET

Campo	Tipo	Descrição
id	Integer	Identificador único de controle do Demander.
razao_social	String:100	Razão social do cliente.
nome_fantasia	String:100	Nome fantasia do cliente.
cnpj	String:18	CNPJ ou CPF do cliente. Com máscara.
tipo	String:1	F = pessoa física. J = pessoa jurídica.
inscricao_estadual	String:20	RG ou inscrição estadual do cliente.
suframa	String:20	Não utilizado.
rua	String:100	Endereço do cliente.
numero	Integer:10	Número do endereço do cliente.
complemento	String:200	Complemento do endereço do cliente.
cep	String:10	CEP do cliente.
bairro	String:50	Bairro do endereço do cliente.
cidade	String:100	Nome da cidade do cliente.
estado	String:2	Sigla do estado do cliente.
observacao	String:2000	Observação do cliente.
excluido	Integer	Indica se o cliente está inativo.
bloqueado_b2b	Boolean	Fixo 'false'.
bloqueado	Integer	Indica se o cliente está bloqueado.
telefones	Lista	Lista com o campo de número de telefone do cliente. No Demander trabalhamos somente com dois telefones.
limite_credito	Lista	Não utilizado.
enderecos_adicionais	Lista	Não utilizado.
extras	Lista	Não utilizado.
emails	Lista	Lista com o campo de e-mail do cliente. No Demander trabalhamos somente com três e-mails.
contatos	Lista	Não utilizado.
ultima_alteracao	DateTime	Data e hora da última alteração no cliente.

Corpo de envio

Campo	Tipo	Descrição
razao_social*	String:100	Razão social do cliente.
nome_fantasia*	String:100	Nome fantasia do cliente.
tipo*	String:1	F = pessoa física. J = pessoa jurídica.
cnpj*	String:18	CNPJ ou CPF do cliente. Com máscara.
inscricao_estadual	String:20	RG ou inscrição estadual do cliente.
rua	String:100	Endereço do cliente.
numero	Integer:10	Número do endereço do cliente.
complemento	String:200	Complemento do endereço do cliente.
cep	String:10	CEP do cliente.
bairro	String:50	Bairro do endereço do cliente.
cidade	String:100	Nome da cidade do cliente.
estado	String:2	Sigla do estado do cliente.
observacao	String:2000	Observação do cliente.
telefones	Lista	Lista com o campo de número de telefone do cliente. No Demander trabalhamos somente com dois telefones.
excluido	Integer	Indica se o cliente está inativo.

Títulos financeiros

Títulos Financeiros representam os débitos abertos de um cliente, como boletos e faturas a vencer ou vencidos. São usados para controle de crédito e visibilidade financeira durante a venda.

Endpoint

api-mp/v1/titulos_vencidos

Corpo de envio

Campo	Tipo	Descrição
numero_documento*	String:18	Pode ser utilizado para enviar o Número do Documento que gerou o título.
valor*	Decimal	Valor em aberto do título.
numero_parcela	String:20	Número da parcela do título.
data_vencimento*	DateTime	Data de vencimento do título.
data_pagamento	DateTime	Data de pagamento do título.
cliente_id	Integer	Identificador único do cliente do título.
excluido	Integer:1	Indica se o título está inativo.

Atualização de status do pedido

Esta tabela permite que o ERP atualize os status dos pedidos criados no Demander, sincronizando o andamento da operação comercial com o vendedor, além de auxiliar na performance do Demander para listar os pedidos.

Endpoint

api-mp/v1/pedidos/{id}/status

Corpo de envio

Campo	Tipo	Descrição
status_id	Integer	Identificador único do status.
anotacao	String	Não utilizado.

Transportadoras

Transportadoras ficam disponíveis na emissão do pedido, podendo vir padrão do cliente ou no campo de escolha do vendedor.

Endpoint

api-mp/v1/transportadoras

Corpo de envio

Campo	Tipo	Descrição
nome*	String:100	Nome da transportadora.
cidade	String:50	Nome da cidade da transportadora.
estado	String:2	Sigla do estado da transportadora.
informacoes_adicionais	String:500	Campo de observações, somente informativo.
telefones	List	Atualmente só é lido o primeiro telefone enviado.
excluido	Boolean	Indica se a transportadora está inativa.