Envios
Códigos de tipos de serviços, utilizado na listagem de serviços e cotação:
| Type | Nome | Descrição |
|---|---|---|
| 1 | Normal | Serviço de envio normal. |
| 2 | Expresso | Serviço de envio expresso. |
Códigos referente a abrangência dos serviços, utilizado na listagem de serviços e cotação:
| Level | Nome | Descrição |
|---|---|---|
| 1 | Municipal | Serviço abrange somente envios municipais. |
| 2 | Intermunicipal | Serviço abrange envios intermunicipais. |
| 3 | Interestadual | Serviço abrange envios interestaduais. |
| 4 | Global | Serviço abrange envios entre países. |
Códigos de status, utilizado na cotação:
| Status | Nome | Descrição |
|---|---|---|
| 0 | Indisponível | Serviço de frete indisponível. |
| 1 | Disponível | Serviço de frete disponível. |
Códigos de estados de envios, utilizado na listagem de informações do envio e na resposta do cancelamento:
| State | Nome | Descrição |
|---|---|---|
| 1 | Pendente | Existe alguma pendência de pagamento, ou o mesmo ainda não foi processado. |
| 2 | Liberado | Envio liberado para postagem. |
| 3 | Postado | Envio postado ou coletado. |
| 4 | Entregue | Envio entregue ao destinatário. |
| 0 | Cancelado | Envio cancelado pelo usuário ou por não pagamento. |
| -1 | Não entregue | Envio não entregue devido a imprevistos. |
Listar serviços de envios:
Serviços de envios podem ser listados utilizando o seguinte endpoint:
Endpoint GET /shipping/services
Exemplo com CURL:
curl \
-X GET \
-u 'API_KEY:SECRET_TOKEN' \
'https://api.melhorenvio.com.br/v1/shipping/services'
Resposta:
[
{
"name": "Correios", // nome da transportadora
"icon": "http://www.melhorenvio.com.br/shipping-companies/images/Correios.png", // ícone da transportadora
"services": [ // serviços da transportadora
{
"id": 1, // identificador do serviço de envio
"name": "Expresso", // nome do serviço de envio
"type": 2, // tipo de envio, 1 = normal, 2 = expresso
"level": 3, // abrangência do serviço, 3 = interestadual
"non-commercial": 1, // aceita envio de pessoa física para pessoa física 0 = não, 1 = sim (essa informação pode depender do cep de destino, havendo alteração no momento da cotação)
"requirements": [ // campos adicionais e obrigatórios para compra deste serviço de envio
// invoice pode ser obrigatório para compra de frete dependendo da transportadora ou se não for um envio de pessoa física para pessoa física
],
"optionals": [ // informações requiridas para opcionais do serviço da transportadora (pode aumentar o valor do envio)
"invoice" // invoice = nota fiscal
"declared_value", // valor declarado (pode ser obrigatório para algumas transportadoras como Jadlog)
"own_hand", // mão própria (opcional), 0 = não, 1 = sim
"receipt" // Aviso de recebimento (opcional) 0 = não, 1 = sim (utilizado nos correios)
]
},
{
"id": 2, // identificador do serviço de envio
"name": "PAC", // nome do serviço de envio
"type": 1, // tipo de envio, 1 = normal, 2 = expresso
"level": 3, // abrangência do serviço, 3 = interestadual
"non-commercial": 1, // aceita envio de pessoa física para pessoa física 0 = não, 1 = sim (essa informação pode depender do cep de destino, havendo alteração no momento da cotação)
"requirements": [ // campos adicionais e obrigatórios para compra deste serviço de envio
// invoice pode ser obrigatório para compra de frete dependendo da transportadora ou se não for um envio de pessoa física para pessoa física
],
"optionals": [ // informações requiridas para opcionais do serviço da transportadora (pode aumentar o valor do envio)
"invoice" // invoice = nota fiscal
"declared_value", // valor declarado (pode ser obrigatório para algumas transportadoras como Jadlog)
"own_hand", // mão própria (opcional), 0 = não, 1 = sim
"receipt" // Aviso de recebimento (opcional) 0 = não, 1 = sim (utilizado nos correios)
]
}
]
},
... // outras transportadoras
]
Cotação:
Envios podem ser cotados utilizando o seguinte endpoint e payload:
Endpoint POST /shipping/calculate
Payload:
{
"from": { // remetente
"postal_code": "04320040", // CEP (somente números)
"address": "Rua 1", // (obrigatório somente para listar serviços de envios municipais)
"number": "100" // (obrigatório somente para listar serviços de envios municipais)
},
"to": { // destinatário
"postal_code": "01505010", // CEP (somente números)
"address": "Rua 2", // (obrigatório somente para listar serviços de envios municipais)
"number": "200" //(obrigatório somente para listar serviços de envios municipais)
},
"package": { // informações do objeto de envio
"width": 5, // largura (centímetros)
"height": 5, // altura (centímetros)
"length": 5, // comprimento (centímetros)
"weight": 0.2 // peso (kilogramas)
},
"options": { // informações requiridas para opcionais do serviço da transportadora (pode aumentar o valor do envio)
"declared_value": 0, // valor declarado (pode ser obrigatório para algumas transportadoras como Jadlog)
"own_hand": 0, // mão própria (opcional), 0 = não, 1 = sim
"receipt": 0 // Aviso de recebimento (opcional) 0 = não, 1 = sim (utilizado nos correios)
},
"filters": { // opções de filtro de serviços (opcional)
"id": [1, 2], // filtra pelo serviço 1 (Correios: Expresso) e 2 (Correios: PAC) (opcional)
"type": [1, 2], // filtra por serviços de envio normal e expresso (opcional)
"level": 3, // filtra por serviços com abrangência interestaduais ou superiores
"status": 1, // lista somente serviços disponíveis para compra
"non-commercial": 1, // filtra por serviços de envio que aceitam o envio de pessoa física para pessoa física
"optionals": [
"own_hand" // filtra por serviços que disponham da opção mão própria
],
"mode": 1 // 1 = filtro como white list (padrão), 2 = filtro como black list (lista todos os serviços com exção dos que são filtrados)
}
}
Resposta:
[
{
"name": "Correios", // nome da transportadora
"icon": "http://www.melhorenvio.com.br/shipping-companies/images/Correios.png", // ícone da transportadora
"services": [ // serviços da transportadora
{
"id": 1, // identificador do serviço
"name": "Expresso", // nome do serviço
"type": 2, // tipo do serviço 1 = normal, 2 = expresso
"level": 3, // abrangência do serviço, 3 = interestadual
"non-commercial": 1, // aceita envio de pessoa física para pessoa física 0 = não, 1 = sim
"requirements": [ // campos adicionais e obrigatórios para compra deste serviço de envio
"invoice" // invoice = nota fiscal
],
"optionals": [ // informações requiridas para opcionais do serviço da transportadora (pode aumentar o valor do envio)
"declared_value", // valor declarado (pode ser obrigatório para algumas transportadoras como Jadlog)
"own_hand", // mão própria (opcional), 0 = não, 1 = sim
"receipt" // Aviso de recebimento (opcional) 0 = não, 1 = sim (utilizado nos correios)
],
"status": 1, // status do serviço para compra 0 = indisponível, 1 = disponível
// informações da cotação (se status = 0, então essas informações não estarão disponíveis)
"price": 50.3, // preço do envio em R$
"delivery_time": 3, // tempo de entrega estimado em dias úteis
"discount": 1.5 // desconto em R$ ao comprar com o Melhor Envio
},
{
"id": 2, // identificador do serviço
"name": "PAC", // nome do serviço
"type": 1, // tipo do serviço 1 = normal, 2 = expresso
"level": 3, // abrangência do serviço, 3 = interestadual
"non-commercial": 0, // aceita envio de pessoa física para pessoa física 0 = não, 1 = sim
"requirements": [ // campos adicionais e obrigatórios para compra deste serviço de envio
"invoice" // invoice = nota fiscal
],
"optionals": [ // informações requiridas para opcionais do serviço da transportadora (pode aumentar o valor do envio)
"declared_value", // valor declarado (pode ser obrigatório para algumas transportadoras como Jadlog)
"own_hand", // mão própria (opcional), 0 = não, 1 = sim
"receipt" // Aviso de recebimento (opcional) 0 = não, 1 = sim (utilizado nos correios)
],
"status": 1, // status do serviço para compra 0 = indisponível, 1 = disponível
// informações da cotação (se status = 0, então essas informações não estarão disponíveis)
"price": 10.3, // preço do envio em R$
"delivery_time": 7, // tempo de entrega estimado em dias úteis
"discount": 0.8 // desconto em R$ ao comprar com o Melhor Envio
}
]
},
... // outras transportadoras
]
Compra:
Envios podem ser comprados utilizando o seguinte endpoint e payload:
Endpoint POST /shipping/cart
Payload:
{
"email": "[email protected]", //email de quem irá comprar os envios (fretes)
"cart": [ // lista de envios
// dados para compra de um envio
{
"ref": "a8098c1a-f86e-11da-bd1a-00112444be1e", // referência do pedido dentro da sua plataforma ou loja (pode ser um id, uuid ou outro valor único referente ao pedido)
"from": { // remetente
"name": "Fulano", // nome
"phone": "53984000000", // telefone com ddd
"postal_code": "04320040", // CEP
"address": "Rua 1", // logradouro (rua)
"number": "100", // número da casa,
"district": "Sé", // bairro
"city": "São Paulo", // cidade
"uf": "SP", // estado (uf)
"complement": "BL 4 AP 501", // (opcional)
"note": "Casa Azul", // observação (opcional)
"cnpj": "", // (opcional) (somente números - 14 digítos) pode ser requerido para algumas transportadoras se for logística normal
"cpf": "", // (opcional) (somente números - 11 digítos) pode ser requerido para algumas transportadoras se for logística normal com envio pessoa física ou então se for logística reversa
"ie": "" // inscrição estadual (opcional) (somente números) pode ser requerido para algumas transportadoras se for logística normal
},
"to": { // destinatário
"name": "Fulano", // nome
"phone": "53984000000", // telefone com ddd
"postal_code": "01505010", // CEP
"address": "Rua 2", // logradouro (rua)
"number": "200", // número da casa
"district": "Sé", // bairro
"city": "São Paulo", // cidade
"uf": "SP", // estado (uf)
"complement": "BL 2 AP 404", // (opcional)
"note": "Próximo a praça", // observação (opcional)
"cnpj": "", // (opcional) (somente números - 14 digítos) pode ser requerido para algumas transportadoras se for logística reversa
"cpf": "", // (opcional) (somente números - 11 digítos) pode ser requerido para algumas transportadoras se for logística reversa com envio pessoa física ou então se for logística normal
"ie": "" // inscrição estadual (opcional) (somente números) pode ser requerido para algumas transportadoras se for logística reversa
},
"package": { // informações do objeto de envio
"width": 5, // largura (centímetros)
"height": 5, // altura (centímetros)
"length": 5, // comprimento (centímetros)
"weight": 0.2 // peso (kilogramas)
},
"service": 1, // identificador do serviço de envio a ser comprado (Correios: Expresso)
// no caso de logística reversa, o objeto é postado ou recolhido no "cliente" e enviado para o "vendedor" (ex: devoluções)
// from será o local do remetente e to destinatário mesmo com a logística reversa
"reverse": 0, // (opcional) 0 = normal (padrão), 1 = logística reversa,
"non-commercial": 0, // envio de pessoa física para pessoa física 0 = não, 1 = sim (algumas transportadoras podem não aceitar esse modo de envio, neste caso a compra não será realizada)
"invoice": "número da nota fiscal (somente números)", // número da nota fiscal (9 digítos)
"invoice-key": "chave da nota fiscal", // (opcional) porém agiliza o envio com transportadoras como a jadlog
"agency": 0, // (opcional) id da agência de postagem para transportadoras que requerem a seleção da mesma como a jadlog, caso não seja fornecida a mesma pode ser selecionada posteriormente na confirmação anterior ao pagamento
"optionals": { // informações requiridas para opcionais do serviço da transportadora (pode aumentar o valor do envio)
"declared_value": 0, // valor declarado (pode ser obrigatório para algumas transportadoras como Jadlog)
"own_hand": 0, // mão própria (opcional), 0 = não, 1 = sim
"receipt": 0 // Aviso de recebimento (opcional) 0 = não, 1 = sim (utilizado nos correios)
},
"reminder": "pendrive, cod: 123" // lembrete (opcional)
},
... // dados de outros envios a serem comprados
]
}
Resposta:
{
"url": "http://www.melhorenvio.com.br/carrinho?client=2e6f9b0d5885b6010f9167787445617f553a735f"
}
É retornado a url para qual o usuário deva ser direcionado para que conclua a compra.
No momento que a loja submete uma lista de envios a serem comprados à um email de usuário e direciona o mesmo ao link retornado, o usuário irá realizar o login no Melhor Envio para este email ou então caso não exista um usuário com este email, o mesmo poderá fazer o cadastro. Logo após, o usuário irá confirmar a compra dos envios submetidos ao seu carrinho pela loja e realizará o pagamento e impressão das etiquetas para os envios.
Listar estados dos envios:
O estato dos envios de um usuário submetidos pela sua loja podem ser listados utilizando o seguinte endpoint e payload:
Endpoint POST /shipping
{
"email": "[email protected]", //email do usuário que comprou os envios (fretes)
"filter": [ // filtra pela referência dos pedidos da sua loja
"a8098c1a-f86e-11da-bd1a-00112444be1e"
]
}
Exemplo com CURL:
curl \
-X POST \
-u 'API_KEY:SECRET_TOKEN' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"email":"[email protected]","filter":["a8098c1a-f86e-11da-bd1a-00112444be1e"]}' \
'https://api.melhorenvio.com.br/v1/shipping'
Resposta:
[
{
"ref": "a8098c1a-f86e-11da-bd1a-00112444be1e", // referência do pedido na sua loja
"state": 3, // estato do envio (3 = postados)
"tracking": null, // url para rastreio se estiver disponível
"price": 50.3, // preço pago
"created_at": "2017-01-01T12:00:00Z", // datetime de compra do envio
"updated_at": "2017-01-01T13:00:00Z" // datetime de atualização da compra do envio
},
... // outros envios
]