Pedidos

A entidade Pedidos V2 contempla tanto os pedidos gerados quanto os orçamentos pendentes realizados no sistema Mercos. A principal distinção entre eles está no campo status, conforme descrito abaixo.

Diferença entre Orçamento e Pedido

status = 1: Orçamento
status = 2: Pedido gerados
status = 0: Cancelado

Exemplo de requisição para listar apenas pedidos gerados:

GET https://app.mercos.com/api/v2/pedidos/?status=2&alterado_apos=2024-04-01T00:00:00

Filtros disponíveis

Você pode aplicar os seguintes filtros na consulta GET:

status_faturamento:
- 0 = Não faturado
- 1 = Parcialmente faturado
- 2 = Faturado
Exemplo: ?status=2&status_faturamento=1
status_custom:
- Permite filtrar por status de pedido customizados.
- Para consultar pedidos sem status customizado, utilize o valor 0.
- É possível enviar múltiplos valores: ?status=2&status_custom=0&status_custom=4&status_custom=10
registros_por_pagina:
- Define a quantidade de registros por página.
- Sugestão: Utilize no máximo 20 por requisição.
Exemplo: ?status=2&registros_por_pagina=15

Estrutura da Resposta do Pedido (GET)

Campo	Tipo	Descrição
id	Integer	Identificador único do pedido
numero	Integer	Número sequencial (auto-incremental).
status	String: 1	Status do pedido: `0 = Cancelado`, `1 = Orçamento`, `2 = Pedido`
status_faturamento	Integer	`0 = Não faturado`, `1 = Parcial`, `2 = Faturado`
status_custom_id	Integer	ID do status customizado.
status_b2b	Integer	`null = Não utiliza B2B`, `1 = Em aberto`, `2 = Concluído`
criador_id	Integer	ID do vendedor responsável.
valor_frete	Double	Valor do frete.
total	Double	Valor total do pedido.
rastreamento	String: 200	Código ou link para rastreamento.
observacoes	String: 500	Observações do pedido.
data_emissao	Date	Data de emissão do pedido. Pode ser `null`.
data_criacao	DateTime	Data em que o pedido foi criado. Preenchida apenas se fornecida. Pode diferir de `data_emissao` (ex.: pedido criado ontem e emitido hoje)
prazo_entrega	String: 100	Previsão de entrega
modalidade_entrega_nome	String: 255	Modalidade de entrega (ex: Sedex)
possui_informacao_pagamento	Boolean	Indica se há link de pagamento
cliente_id	Integer	ID do cliente no Mercos
cliente_razao_social	String: 100	Razão social do cliente
cliente_nome_fantasia	String: 100	Nome fantasia do cliente
cliente_cnpj	String: 14	CNPJ do cliente
cliente_inscricao_estadual	String: 30	Inscrição estadual do cliente
cliente_rua	String: 100	Rua do cliente
cliente_numero	String: 100	Número do endereço.
cliente_complemento	String: 50	Complemento do endereço.
cliente_cep	String: 8	CEP
cliente_bairro	String: 30	Bairro
cliente_cidade	String: 50	Cidade
cliente_estado	String: 2	Estado (UF)
cliente_suframa	String: 20	SUFRAMA (se aplicável)
cliente_telefone	List	Lista de telefones
cliente_email	List	Lista de emails
nome_contato	String: 50	Nome do contato principal.
representada_id	Integer	ID da Representada
representada_nome_fantasia	String: 50	Nome fantasia da Representada
representada_razao_social	String: 50	Razão Social da Representada
transportadora_id	Integer	ID da transportadora. Será `null` se houver integração com a Frenet, só existindo o campo `transportadora_nome`e `valor_frete`.
transportadora_nome	String: 50	Nome da transportadora.
condicao_pagamento	String: 100	Condição de pagamento em formato texto livre.
condicao_pagamento_id	Integer	ID da condição de pagamento (se integrado)
forma_pagamento_id	Integer	ID da forma de pagamento (se integrado)
tipo_pedido_id	Integer	Se integrado, é retornado o ID do tipo de pedido. Caso contrário, assume o tipo “venda” (padrão), retornado como `null`. Outros tipos cadastrados retornam seus respectivos IDs, mas não geram métricas de faturamento.
cupom_de_desconto	String: 50	Cupom de desconto aplicado no pedido.
percentual_total_comissao_pedido	Double	Percentual total de comissão do pedido.
comissoes_vendedores	List	Lista de comissões por vendedor `{"vendedor_id": Integer, "percentual": Double}`.
extras	List	Lista com os campos extras do pedido.
endereco_entrega	List	Lista com os endereços de entrega do pedido.

Estrutura da Resposta do Item do pedido (GET)

Campo	Tipo	Descrição
id	Integer	Identificador único do item do pedido.
produto_id	Integer	ID do produto na Mercos.
produto_codigo	String: 50	Código do Produto.
produto_nome	String: 100	Nome do Produto na.
tabela_preco_id	Integer	ID da tabela de preço utilizada. Será `null` se o preço aplicado for o padrão do produto.
preco_tabela	Double	Preço padrão do produto no momento da venda. Corresponde ao valor padrão (`preco_tabela` do produto) ou ao da tabela de preço, caso uma tenha sido aplicada.
preco_liquido	Double	Preço de venda do produto.
quantidade	Double	Quantidade vendida.
cotacao_moeda	Double	Cotação da moeda (caso estrangeira)
tipo_ipi	Char	Indica se o IPI é percentual `P` ou valor fixo `V`
ipi	Double	Valor do IPI do produto
st	Double	Percentual aplicado de ICMS-ST (Substituição Tributária) sobre o item.
~~quantidade_grades~~(depreciado)	List	Lista com as grades de cores e tamanhos usadas, e suas respectivas quantidades. Caso o produto possua somente Cor, o Tamanho será null, e vice-versa. A soma das quantidades nesta lista será igual ao campo quantidade do item.cor String: 15tamanho String: 15quantidade Double
descontos_do_vendedor	List	Lista de descontos ou acréscimos (os acréscimos são negativos) do vendedor, aplicadas ao item.
descontos_de_promocoes	List	Lista de descontos de promoções aplicadas ao item: `{"regra_id": Integer, "desconto": Double}`
descontos_de_politicas	List	Lista de descontos ou acréscimos (os acréscimos são negativos) de políticas comerciais aplicadas ao item: `{"slug": String(36), regra_id": Integer, "desconto": Double}`
desconto_de_cupom	Double	Desconto de cupom aplicado ao item.
observacoes	String: 500	Observações do item
subtotal	Double	Subtotal do item
grupo_grades	UUID	Identificador do grupo de produtos com variações (grades) dentro de um mesmo pedido.
produto_agregador_id	Integer	ID do produto agregador no Mercos, quando item é do tipo grade
excluido	Boolean	Indica se o item foi excluído.

Campos extras do pedido (campo `extras`)

Campo	Tipo	Descrição
campo_extra_id	Integer	Identificador único do campo extra.
nome	String: 50	Nome do campo extra.
tipo	String	`("0") Texto livre`, `("1") data`, `("2") numérico`, `("3") hora`, `("4") Lista` e `("5") Somente leitura`.
valor_texto	String: 50	Texto ou valor se tipo = 0 ou 5
valor_data	String	Data se tipo = 1
valor_decimal	Double	Número se tipo = 2
valor_hora	String	Hora se tipo = 3
valor_lista	List	Lista de valores se tipo = 4. Exemplo: `[[1, "sp"], [2, "sc"]]`
valor		O tipo deste atributo depende do tipo do campo extra como descrito na tabela abaixo.

Tipo do campos extras

Tipo do campo extra	Tipo	Formato
Texto simples("0")	String: 50
Data("1")	String	"yyyy-dd-mm", ex: "2018-21-02".
Numérico("2")	Double	Valor máximo: 99999999.99999.
Hora("3")	String	"HH:mm", ex: "21:56".
Lista("4")	List	Retorna uma lista de IDs e valores dos itens da lista, ex: `[[1, "sp"], [2, "sc"]].`
Somente leitura("5")	String: 50

Endereço de entrega (campo `endereco_entrega`)

Campo	Tipo	Descrição
id	Integer	Identificador único do endereço (mesmo do endereço adicional do cliente).
cep	String: 8	CEP do endereço
endereco	String: 200	Nome da rua ou logradouro.
numero	String: 100	Número do endereço.
complemento	String: 200	Complemento do endereço (ex: bloco, apartamento).
bairro	String: 200	Bairro do endereço.
cidade	String: 200	Cidade do endereço.
estado	String: 2	Sigla do estado (UF).

Parâmetros de Envio de Pedidos (POST / PUT)

Requisição PUT: envie apenas os campos que deseja alterar. Requisição POST: campos obrigatórios devem ser informados.

Campo	Tipo	Descrição
cliente_id (POST: obrigatório)	Integer	Identificador único do cliente.
data_emissao (POST: obrigatório)	Date	Data de emissão do pedido.
contato_id	Integer	ID do contato criado no Mercos.
transportadora_id	Integer	ID da transportadora.
condicao_pagamento_id (POST: obrigatório)	Integer	ID da condição de pagamento. Deve ser informado somente se houver integração com a entidade Condições de Pagamento. Não deve ser utilizado junto com o campo condicao_pagamento
condicao_pagamento (POST: obrigatório)	String: 100	Descrição da condição de pagamento em texto livre. Deve ser informado somente se não houver integração com a entidade `Condições de Pagamento`. Não deve ser utilizado junto com o campo `condicao_pagamento_id`.
tipo_pedido_id	Integer	ID do tipo de pedido. Deve ser informado somente se houver integração com a entidade `Tipo de Pedido`.
forma_pagamento_id	Integer	ID da forma de pagamento. Deve ser informado somente se houver integração com a entidade `Formas de Pagamento`.
endereco_entrega_id	Integer	ID do endereço de entrega.
observacoes	String: 500	Informações adicionais registradas no pedido.
extras	List	Lista de campos extras associados ao pedido. A estrutura esperada pode ser consultada na seção Estrutura de Retorno de Campos Extras do Pedido.
itens	List	Lista de itens do pedido, conforme estrutura JSON definida na seção Parâmetros do JSON de envio do Item do Pedido. `Se informado, deve conter pelo menos um item`
data_criacao	DateTime	Data de criação do pedido. Pode ser diferente da `data_emissao`, já que um pedido pode ter sido criado em uma data e emitido em outra. Este campo somente será preenchido se for enviado no POST, pois representa a data em que o pedido foi criado (não confundir com a data de inserção no banco de dados).
rastreamento	String: 200	Código ou link de rastreamento do envio do pedido.
valor_frete	Double	Valor do frete aplicado ao pedido.
criador_id	Integer	ID do vendedor que responsável pelo pedido.

Parâmetros de Envio do Item do pedido (POST / PUT)

Requisição PUT: envie apenas os campos que deseja alterar. Requisição POST: campos obrigatórios devem ser informados.

💡
Apenas produtos simples ou itens de grade devem ser enviados como item no pedido.

⚠️
Observações sobre a Grade v3: Ao realizar um POST com produtos do tipo grade, é obrigatório enviar o campo grupo_grades. Para isso, gere um UUID único para cada conjunto de grades do mesmo produto incluído no pedido. Todos os itens de grade desse conjunto devem compartilhar o mesmo grupo_grades. Por exemplo, se um produto possui variações de tamanho ou cor, todas essas variações devem ter o mesmo UUID.

Campo	Tipo	Descrição
id	Integer	ID do item do pedido. Deve ser informado somente em requisições PUT, para fins de atualização do item existente.
produto_id (POST: obrigatório)	Integer	ID do produto na Mercos. Campo obrigatório na criação de um novo item do pedido.
preco_tabela (POST: obrigatório)	Double	Preço padrão do produto no momento da venda. Corresponde ao campo `preco_tabela` da entidade `Produto` ou, se houver uma tabela de preço aplicada (`tabela_preco_id` diferente de `null`), representa o valor definido por essa tabela.
quantidade (POST: obrigatório)	Double	Quantidade vendida do item. Se este campo for informado, o campo quantidade_grades não deve ser utilizado no mesmo item.
~~quantidade_grades~~(depreciado)	List	Lista com as grades de cores e tamanhos usadas, e suas respectivas quantidades. Caso o produto possua somente Cor, o Tamanho será null, e vice-versa. A soma das quantidades nesta lista será igual ao campo quantidade do item.cor String: 15 tamanho String: 15 quantidade Double
tabela_preco_id	Integer	ID da tabela de preço utilizada no item. Caso o preço aplicado seja o padrão do produto (`preco_tabela` da entidade Produto), este campo será `null`.
preco_liquido	Double	Preço de venda final do produto. Este campo não pode ser informado caso sejam utilizados os campos `descontos_do_vendedor`, `descontos_de_promocoes` ou `descontos_de_politicas`, pois o preço líquido será calculado automaticamente com base nos descontos aplicados e no `preco_tabela`.
moeda	String	Tipo de moeda utilizada. Utilize os seguintes valores: `Real = '0'` (preenchimento automático, não precisa ser enviado) `Dólar = '1'` `Euro = '2'` `Outro = '3’`
cotacao_moeda	Double	Cotação da moeda estrangeira. Deve ser informado apenas quando a moeda for diferente de Real.
descontos_do_vendedor	List	Lista de descontos aplicados pelo vendedor ao item.
descontos_de_promocoes	List	Lista de descontos promocionais aplicados ao item. Cada item deve seguir o formato:`{"regra_id": Integer, "desconto": Double}`
descontos_de_politicas	List	Lista de acréscimos ou descontos decorrentes de políticas comerciais. Cada item deve seguir o formato: `{ "regra_id": Integer, "desconto": Double }` Acréscimos são representados por valores negativos de desconto.
observacoes	String: 500	Informações adicionais registradas sobre o item.
tipo_ipi	Char	Indica o tipo de IPI aplicado. Utilize: `'P'` para percentual e `'V'` para valor fixo Deve ser preenchido somente se o campo `ipi` for informado.
ipi	Double	Valor ou percentual do IPI, conforme indicado no campo `tipo_ipi`.
st	Double	Percentual da alíquota de ICMS-ST (Substituição Tributária). Não deve ser preenchido se o campo `valor_unitario_st` for informado.
valor_unitario_st	Double	Valor unitário, em reais, do ICMS-ST. Não deve ser preenchido se o campo `st` for informado.
excluido	Boolean	Se definido como `true`, o item será excluído durante a alteração.
grupo_grades (obrigatório em produtos do tipo grade)	UUID	Identificador do conjunto de produtos relacionados por grade. Itens com o mesmo `grupo_grades` são agrupados e exibidos como um único item no pedido. Todos os produtos do grupo devem compartilhar o mesmo produto agregador. Produtos simples não devem preencher este campo.

Parâmetros de Envio do Campos extras do pedido (POST / PUT)

💡
Observação: Campos extras previamente cadastrados que não forem enviados serão salvos como vazios.

Campo	Tipo	Descrição
id	Integer	Identificador único do campo extra.
valor		Valor do campo extra. O tipo depende do tipo de campo, conforme especificado na tabela abaixo.

Tipos Campos extras do pedido

Tipo do campo extra	Tipo	Formato
Texto simples("0")	String: 50
Data("1")	String	"yyyy-dd-mm", ex: "2018-21-02".
Numérico("2")	Double	Valor máximo: 99999999.99999.
Hora("3")	String	"HH:mm", ex: "21:56".
Lista("4")	List	Retorna uma lista de IDs e valores dos itens da lista, ex: `[[1, "sp"], [2, "sc"]].`
Somente leitura("5")	String: 50

Estrutura da resposta (POST / PUT)

Sucesso

Quando a requisição for bem-sucedida, a resposta retornará:

O id do pedido criado ou alterado
O numero do pedido
A lista de ids dos itens do pedido, na mesma ordem em que foram enviados

⚠️
No método PUT, o campo produto_id também será retornado em cada item, junto com seu respectivo id.

Exemplo de resposta (POST ou PUT):

  {
      "id": 10,
      "numero": 20,
      "itens": [
          {
              "id": 5,
              "produto_id": 9 // Retornado somente em PUT
          },
          {
              "id": 6
          }
      ]
  }

Recomendação: Armazene os ids retornados para poder utilizá-los em alterações futuras.

Erro

Em caso de falha, a resposta conterá uma lista dos erros encontrados, informando:

O campo com problema
O tipo ou descrição do erro

Exemplo de resposta de erro:

  {
    "mensagem": "Ocorreram erros de validação",
    "erros": [
      [
        "cliente_id",
        "Atributo obrigatório não informado"
      ]
    ]
  }

Diferença entre Orçamento e Pedido

Filtros disponíveis

Estrutura da Resposta do Pedido (GET)

Estrutura da Resposta do Item do pedido (GET)

Campos extras do pedido (campo extras)

Tipo do campos extras

Endereço de entrega (campo endereco_entrega)

Parâmetros de Envio de Pedidos (POST / PUT)

Parâmetros de Envio do Item do pedido (POST / PUT)

Apenas produtos simples ou itens de grade devem ser enviados como item no pedido.

Parâmetros de Envio do Campos extras do pedido (POST / PUT)

Observação: Campos extras previamente cadastrados que não forem enviados serão salvos como vazios.

Tipos Campos extras do pedido

Estrutura da resposta (POST / PUT)

Sucesso

Erro

Campos extras do pedido (campo `extras`)

Endereço de entrega (campo `endereco_entrega`)