PUT api/v1/pedido — API HelpyGo

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": "",
  "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",
    "telefone": "11999998888",
    "email": "joao@email.com"
  },
  "envio": [
    {
      "produtos": [
        {
          "sku": "SKU-001",
          "titulo": "Camiseta Básica",
          "variacao": "Cor: Azul / Tamanho: M",
          "quantidade": 2,
          "preco": 49.90
        }
      ],
      "notaFiscal": {
        "chaveNfe": "35240112345678000195550010000000011000000019",
        "xmlNfe": "..."
      }
    }
  ]
}

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
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.telefone	Telefone de contato do destinatário	string	20	não
enderecoEntrega.email	E-mail do destinatário	string	100	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[].notaFiscal.chaveNfe	Chave da Nota Fiscal Eletrônica (44 caracteres numéricos)	string	44	não
envio[].notaFiscal.xmlNfe	Conteúdo XML da NFe (máximo 1 MB). Será armazenado no S3	string	1MB	não

Parâmetros de Retorno

Campo	Descrição	Tipo	Tamanho
_id	Identificador único do pedido no MongoDB (criado ou atualizado)	string	24
mensagem	Mensagem de sucesso ou erro da operação	string	255

Exemplo de Resposta

{
  "_id": "507f1f77bcf86cd799439011",
  "mensagem": "sucesso"
}