PUT api/v1/pedidoNovo/

Descrição

Cria ou atualiza um pedido (upsert). O sistema busca pedidos existentes com a seguinte prioridade:

1. Busca por numeroPedido + canal da loja autenticada
2. Se não encontrado e pedidoCanal informado, busca por pedidoCanal + canal da loja autenticada
3. Se nenhuma busca retornar resultado, cria um novo pedido

Proteção de campos sensíveis: Os campos chaveNfe, linkRastreio e codigoRastreio não são sobrescritos quando o valor enviado é vazio ou nulo e já existe um valor no documento.

XML da NFe: Quando o campo xmlNfe é informado com um XML válido, o conteúdo é armazenado no S3 no path nfe/{chaveNfe}.xml. O XML não é gravado no MongoDB, apenas a referência. Tamanho máximo aceito: 1 MB.

Obs.: Utilizar tokenAPI (Authorization: Bearer)

Limite de requisições: 60 requisições por minuto.

Códigos de erro:

Código	Descrição
400	Requisição inválida — JSON não informado, campo obrigatório ausente ou valor inválido. A mensagem indica o campo e motivo.
401	Não autorizado — Token ausente, inválido, inativo ou sem permissão para este serviço/método.
429	Limite de requisições ultrapassada — Aguarde o próximo minuto para novas requisições.
500	Erro interno — Falha no armazenamento do XML no S3 ou erro inesperado no servidor.

Body da Requisição

{
  "numeroPedido": "PED-2024-001",
  "pedidoLoja": "",
  "tipoPedido": "envio",
  "canal": "ecommerce",
  "pedidoCanal": "ML-123456",
  "numeroPedidoEnvioPai": "",
  "plataforma": "",
  "statusDescricao": "Faturado",
  "statusDescricaoCanal": "Faturado",
  "valorTotalPedido": 109.80,
  "valorTotalFrete": 10.00,
  "dataPedido": "2024-01-15 10:30:00",
  "enderecoEntrega": {
    "nome": "João da Silva",
    "cpfCnpj": "12345678901",
    "cep": "01310100",
    "cidade": "São Paulo",
    "uf": "SP",
    "endereco": "Av. Paulista",
    "numero": "1000",
    "complemento": "Sala 101",
    "bairro": "Bela Vista",
    "referencia": "Próximo ao metrô",
    "inscricaoEstadual": "",
    "telefone": "11999998888",
    "email": "joao@email.com"
  },
  "envio": [
    {
      "statusDescricao": "Faturado",
      "tipoLogistica": "transportadora",
      "idCotacao": "",
      "codigoRastreio": "",
      "linkRastreio": "",
      "nomeTransportadora": "",
      "nomeMetodoEnvio": "Sedex",
      "prazoDeEntrega": "2024-01-20",
      "dataEntrega": "",
      "produtos": [
        {
          "sku": "SKU-001",
          "titulo": "Camiseta Básica",
          "variacao": "Cor: Azul / Tamanho: M",
          "quantidade": 2,
          "preco": 49.90,
          "imagem": "",
          "linkAnuncio": ""
        }
      ],
      "notaFiscal": {
        "chaveNfe": "35240112345678000195550010000000011000000019",
        "numero": 0,
        "serie": 0,
        "cnpjFaturador": "",
        "data": "2024-01-15",
        "linkXmlNFe": "",
        "linkDanfe": "",
        "xmlNfe": "..."
      },
      "dadosAdicionaisEnvio": {}
    }
  ],
  "pagamentos": [
    {
      "idPagamento": "PAY-123",
      "formaPagamento": "Cartão de crédito",
      "metodo": "credit_card",
      "bandeira": "Visa",
      "parcelas": 3,
      "valor": 109.80,
      "valorParcela": 36.60,
      "status": "aprovado",
      "dataPagamento": "2024-01-15"
    }
  ],
  "dadosAdicionaisPedido": {}
}

Parâmetros de Entrada

Campo	Descrição	Tipo	Tamanho	Obrigatório
numeroPedido	Número do pedido no sistema do lojista (ERP/Hub)	string	100	sim
pedidoLoja	Número do pedido na loja/plataforma de envio (ex: número AllPost)	string	100	não
tipoPedido	Tipo do pedido. Valores aceitos: envio ou reversa	string	7	sim
canal	Canal de origem do pedido (ex: ecommerce, mercadolivre, shopee)	string	50	sim
pedidoCanal	Número do pedido na plataforma de origem (marketplace)	string	100	não
numeroPedidoEnvioPai	Número do pedido de envio pai. Obrigatório quando tipoPedido for "reversa"	string	100	sim se reversa
plataforma	Plataforma/origem técnica do pedido (ex: Bling, Tiny, integração própria). Campo livre.	string	100	não
statusDescricao	Situação do pedido na loja/logística (ex: Pendente, Faturado, Em trânsito, Entregue, Cancelado). Na atualização, este campo é ignorado quando a origem é um canal/marketplace.	string	100	não
statusDescricaoCanal	Situação do pedido no canal/marketplace. Quando não informado, assume o mesmo valor de statusDescricao. Permite que um pedido esteja, por exemplo, "Entregue" na logística e "Cancelado" no canal ao mesmo tempo. Na atualização, este campo é ignorado quando a origem é a logística (AllPost).	string	100	não
valorTotalPedido	Valor total do pedido (itens + frete). Usado também para derivar o valor total dos itens (valorTotalPedido - valorTotalFrete).	float		não
valorTotalFrete	Valor total do frete do pedido	float		não
dataPedido	Data do pedido (ex: "2024-01-15" ou "2024-01-15 10:30:00"). Quando não informada, assume a data/hora atual.	string		não
enderecoEntrega.nome	Nome do destinatário	string	100	sim
enderecoEntrega.cpfCnpj	CPF (11 dígitos) ou CNPJ (14 dígitos) do destinatário	string	14	sim
enderecoEntrega.cep	CEP do endereço de entrega (valor numérico entre 1000000 e 99999999)	string	8	sim
enderecoEntrega.cidade	Cidade do endereço de entrega (mínimo 2 caracteres)	string	100	sim
enderecoEntrega.uf	UF do endereço de entrega (2 caracteres, estado brasileiro válido)	string	2	sim
enderecoEntrega.endereco	Logradouro do endereço de entrega	string	200	sim
enderecoEntrega.numero	Número do endereço de entrega	string	20	sim
enderecoEntrega.complemento	Complemento do endereço de entrega	string	100	não
enderecoEntrega.bairro	Bairro do endereço de entrega	string	100	não
enderecoEntrega.referencia	Ponto de referência do endereço de entrega	string	200	não
enderecoEntrega.inscricaoEstadual	Inscrição estadual do destinatário (quando aplicável, ex: pedido para CNPJ)	string	50	não
enderecoEntrega.telefone	Telefone de contato do destinatário. Aceita também o campo telefones como array de strings.	string	20	não
enderecoEntrega.email	E-mail do destinatário	string	100	não
envio[].statusDescricao	Situação específica deste envio (quando o pedido tem mais de um envio)	string	100	não
envio[].tipoLogistica	Tipo de logística do envio (ex: correios, transportadora, coleta)	string	50	não
envio[].idCotacao	Identificador da cotação de frete associada ao envio	string	100	não
envio[].codigoRastreio	Código de rastreio do envio. Protegido: não é sobrescrito por valor vazio quando já existe.	string	100	não
envio[].linkRastreio	URL de rastreio do envio. Protegido: não é sobrescrito por valor vazio quando já existe.	string	250	não
envio[].nomeTransportadora	Nome da transportadora responsável pelo envio	string	100	não
envio[].nomeMetodoEnvio	Nome do método/serviço de envio (ex: PAC, Sedex, Full)	string	100	não
envio[].prazoDeEntrega	Data prometida de entrega (ex: "2024-01-20")	string		não
envio[].dataEntrega	Data efetiva de entrega (ex: "2024-01-19")	string		não
envio[].produtos[].sku	Código SKU do produto	string	50	sim
envio[].produtos[].titulo	Título do produto (mínimo 3 caracteres)	string	200	sim
envio[].produtos[].variacao	Variação do produto (ex: cor, tamanho, voltagem). Quando aplicável ao item.	string	200	não
envio[].produtos[].quantidade	Quantidade de itens (inteiro maior que zero)	integer		sim
envio[].produtos[].preco	Preço unitário do produto (maior que zero)	float		sim
envio[].produtos[].imagem	URL da imagem do produto	string	250	não
envio[].produtos[].linkAnuncio	URL pública do anúncio do produto (ex: página do item no marketplace)	string	250	não
envio[].notaFiscal.chaveNfe	Chave da Nota Fiscal Eletrônica (44 caracteres numéricos). Quando informada, número, série e CNPJ do faturador são derivados dela.	string	44	não
envio[].notaFiscal.numero	Número da NF. Usado quando a chave não é informada.	integer		não
envio[].notaFiscal.serie	Série da NF. Usado quando a chave não é informada.	integer		não
envio[].notaFiscal.cnpjFaturador	CNPJ do faturador da NF. Usado quando a chave não é informada.	string	14	não
envio[].notaFiscal.data	Data de emissão da NF (ex: "2024-01-15")	string		não
envio[].notaFiscal.linkXmlNFe	URL do XML da NFe	string	250	não
envio[].notaFiscal.linkDanfe	URL do DANFE (PDF) da NFe	string	250	não
envio[].notaFiscal.xmlNfe	Conteúdo XML da NFe (máximo 1 MB). Será armazenado no S3 no path `nfe/{chaveNfe}.xml`.	string	1MB	não
envio[].dadosAdicionaisEnvio	Objeto/array livre com dados adicionais específicos do envio	object		não
pagamentos[].idPagamento	Identificador do pagamento no canal/gateway	string	100	não
pagamentos[].formaPagamento	Forma de pagamento (ex: Cartão de crédito, Pix, Boleto). Quando não informada, é derivada de metodo.	string	50	não
pagamentos[].metodo	Método de pagamento no canal (código/nome original do marketplace)	string	50	não
pagamentos[].bandeira	Bandeira do cartão (ex: Visa, Mastercard)	string	50	não
pagamentos[].parcelas	Quantidade de parcelas	integer		não
pagamentos[].valor	Valor total do pagamento	float		não
pagamentos[].valorParcela	Valor de cada parcela	float		não
pagamentos[].status	Situação do pagamento (o valor original do canal é preservado em statusCanal)	string	50	não
pagamentos[].dataPagamento	Data do pagamento (ex: "2024-01-15")	string		não
dadosAdicionaisPedido	Objeto/array livre com dados adicionais do pedido	object		não

Parâmetros de Retorno

Campo	Descrição	Tipo	Tamanho
mensagem	Mensagem da operação: "sucesso" (criado) ou "Pedido já gerado" (atualizado); em erro, descreve o campo/motivo.	string	255
_id	Identificador único do pedido no MongoDB (criado ou atualizado)	string	24
chavePedido	Mesmo identificador do pedido (_id), mantido por compatibilidade	string	24
numeroPedido	Número do pedido informado na requisição	string	100
alteracoes	Presente apenas na atualização de um pedido existente: lista os campos alterados no documento.	object

Exemplo de Resposta

{
  "mensagem": "sucesso",
  "chavePedido": "fe3008ade1e44c02dbcebe46a454142f",
  "_id": "fe3008ade1e44c02dbcebe46a454142f",
  "numeroPedido": "2368648"
}