Manual de integração via WebService Manda Bem

1. Pré – Requisitos

Para consumir o webservice do Manda Bem o usuário deve possuir credenciais de acesso, que combinadas vão permitir o acesso aos métodos da Plataforma:

plataforma_id – Código de acesso da plataforma
plataforma_chave – Senha de acesso da plataforma

As credenciais serão fornecidas pela Plataforma Manda Bem.

2. Métodos

2.1. Consulta aos valores de Frete

Descrição:
Método responsável obtenção dos valores de Frete na Plataforma Manda Bem

Método de HTTP:
POST

Endpoint:
https://mandabem.com.br/ws/valor_envio

Parametros:

plataforma_id (ID de conexão enviada pelo Manda Bem)

plataforma_chave (Chave de conexão enviada pelo Manda Bem)

cep_origem (8 caracteres, apenas números)

cep_destino (8 caracteres, apenas números)

valor_seguro (Opcional, formato 0.00)

servico (Tipo de serviço PAC, SEDEX ou PACMINI)

peso (formato em kg)

altura (formato em cm)

largura (formato em cm)

comprimento (formato em cm)

EX: var=abc&var=abc&var…

* Observação: Os parâmetros aceitos para PACMINI são:

• Peso máximo: 300g.
• Dimensões mínimas: 1cm (A) x 11cm (L) x 16cm (C).
• Dimensões máximas: 4cm (A) x 16cm (L) x 24cm (C).

2.2. Geração do Envio

Descrição:
Método responsável pela geração do envio na plataforma Manda Bem

Método de HTTP:
POST

Endpoint:
https://mandabem.com.br/ws/gerar_envio

Parametros:

plataforma_id (ID de conexão enviada pelo Manda Bem)

plataforma_chave (Chave de conexão enviada pelo Manda Bem)

forma_envio (PAC, SEDEX ou PACMINI)

destinatario (Nome do Destinatário, máx 40 caracters)

cep (Somente números, 8 caracters)

logradouro (Logradouro do endereço, máx 60 caracters)

numero (Número do endereço, máx 6 caracters)

complemento (Opcional, Complemento do endereço, máx 30 caracters)

cidade (Cidade do endereço, máx 40 caracters)

bairro (Bairro do endereço, máx 60 caracters)

estado (UF do estado, 2 caracters)

peso (Peso em Kilos)

altura (formato em cm)

largura (formato em cm)

comprimento (formato em cm)

cpf_destinatario (Opcional, Apenas números, 11 caracters)

valor_seguro (Opcional, formato 0.00)

ref_id (Opcional, número de refencia da loja)

integration (Refere-se ao nome da integração que será associada ao envio, máx 20 caracteres)

email (Opcional, email do destinatário)

cep_origem (Opcional, caso não informado será usado o CEP de cadastro da loja)

produtos (nome,quantidade,preco )
(Opcional, Lista de Produtos a serem adicionados à Declaração de Conteúdo .)
Exemplo:
produtos[0] = [

‘nome’ => ‘Produto teste 1’,
‘quantidade’ => 2,
‘preco’ => 20.00

]
produtos[1] = [

‘nome’ => ‘Produto teste 2’,
‘quantidade’ => 3,
‘preco’ => 60.00

]

Retorno:
{

“resultado”: {

“sucesso”: “true”,
“mensagem”: “Envio numero 123456 gerado com sucesso”,
“envio_id”: 123456

}

}

2.3. Geração do Reversa

Descrição:
Método responsável pela geração de reversa na plataforma Manda Bem

Método de HTTP:
POST

Endpoint:
https://mandabem.com.br/ws/gerar_reversa

Parametros:

plataforma_id (ID de conexão enviada pelo Manda Bem)

plataforma_chave (Chave de conexão enviada pelo Manda Bem)

forma_envio (PAC, SEDEX ou PACMINI)

remetente (Nome do Remetente, máx 40 caracters)

cep (Somente números, 8 caracters)

logradouro (Logradouro do endereço, máx 60 caracters)

numero (Número do endereço, máx 6 caracters)

complemento (Opcional, Complemento do endereço, máx 20 caracters)

cidade (Cidade do endereço, máx 40 caracters)

bairro (Bairro do endereço, máx 60 caracters)

estado (UF do estado, 2 caracters)

peso (Peso em Kilos)

altura (formato em cm)

largura (formato em cm)

comprimento (formato em cm)

valor_seguro (Opcional, formato 0.00)

email (Opcional, email do destinatário)

Retorno:
{

“status”: 1,
“auth_postagem”: 123456789,
“envio_id”: 123456,
“msg”: “Reversa Gerada com Sucesso.”

}

3. Busca de informações do envio (Postagem)

Descrição:
Método responsável pela busca de informações da postagem, incluindo o código de rastreio e o status da postagem.

Método de HTTP:
POST

Endpoint:
https://mandabem.com.br/ws/envio

Parametros:

plataforma_id (ID de conexão enviada pelo Manda Bem)

plataforma_chave (Chave de conexão enviada pelo Manda Bem)

id (ID do envio gerado anteriormente, Opcional quando “ref_id” for informado)

ref_id (ID de referência do pedido informado na geração do envio, Opcional quando “id” for informado)

Retorno {

“resultado”: {

“sucesso”: “true”,
“dados”: {

“envio_id”: “123456”,
“etiqueta”: “OK000000000BR”,
“status”: “Objeto postado”,
“destinatario”: “Maria Silva”,
“logradouro”: “Rua Das Flores”,
“numero”: “100”,
“complemento”: “casa”,
“bairro”: “Centro”,
“cep”: “12345678”,
“cidade”: “São Paulo”,
“estado”: “SP”

}

}

}

3.1 Busca Etiquetas

Descrição:
Método responsável pela busca de multiplas etiquetas na plataforma Manda Bem

Método de HTTP:
POST

Endpoint:
https://mandabem.com.br/ws/envios

Parametros:

plataforma_id (ID de conexão enviada pelo Manda Bem)

plataforma_chave (Chave de conexão enviada pelo Manda Bem)

start_date (A data de inicio deve seguir o seguinte padrão ‘2023-01-01’)

end_date (A data final deve seguir o seguinte padrão ‘2023-01-01’)

Retorno {

“resultado”: {

“sucesso”: “true”,
“dados”: { {

“envio_id”: “123456”,
“etiqueta”: “OK000000000BR”,
“status”: “Objeto postado”,
“destinatario”: “Maria Silva”,
“logradouro”: “Rua Das Flores”,
“numero”: “100”,
“complemento”: “casa”,
“bairro”: “Centro”,
“cep”: “12345678”,
“cidade”: “São Paulo”,
“estado”: “SP”

}, {

“envio_id”: “789101112”,
“etiqueta”: “OK000000001BR”,
“status”: “Objeto postado”,
“destinatario”: “Maria Silva”,
“logradouro”: “Rua Das Flores”,
“numero”: “100”,
“complemento”: “casa”,
“bairro”: “Centro”,
“cep”: “12345678”,
“cidade”: “São Paulo”,
“estado”: “SP”

}

}

}

3.2. Consulta CEP

Descrição:
Método responsável obtenção de endereço atraves do CEP na Plataforma Manda Bem

Método de HTTP:
POST

Endpoint:
https://mandabem.com.br/ws/consulta_cep

Parametros:

plataforma_id (ID de conexão enviada pelo Manda Bem)

plataforma_chave (Chave de conexão enviada pelo Manda Bem)

cep (8 caracteres, apenas números)

Retorno:

{

“id”: 1,
“logradouro”: “Rua teste”,
“bairro”: “Bairro teste”,
“cidade”: “Cidade teste”,
“uf”: “RJ”,
“cep”: “12345678”,
“ibge”: “3303500”,
“date_insert”: “2020-04-28 10:41:58”

}

4. Retorno de Dados

A resposta sempre será retornada no formato JSON. Existem 3 casos possíveis de retorno de dados.

SUCESSO – Em caso de sucesso ela devolvera uma tag de nome SUCESSSO com valor de true, uma mensagem complementar e mais alguns valores que se julgue necessário.


{
	"resultado": {
		"sucesso": "true",
		"mensagem": "Consulta realizada com sucesso.",
		"PAC": {
		  "valor": "16,32",
		  "prazo": "14"
		},
		"SEDEX": {
		  "valor": "27,80",
		  "prazo": "9"
		}
	}
}

SUCESSO Parcial – Em caso de sucesso parcial ela devolvera uma tag de nome SUCESSSO com valor de TRUE, uma tag de ERRO, uma mensagem complementar e mais alguns valores que se julgue necessário.

{
	"resultado": {
		"sucesso": "true",
		"erro": "Não foi encontrada precificação. ERP-007: CEP de origem não pode postar para o CEP de destino informado(-1).",
		"mensagem": "Consulta realizada com sucesso.",
		"SEDEX": {
		  "valor": "10,30",
		  "prazo": "1"
		}
	}
}

ERRO — Em caso de ERRO ela devolvera uma tag de nome SUCESSO com valor FALSE e uma tag de ERRO.
```
{
	"resultado": {
		"sucesso": "false",
		"erro": "ERRO OCORRIDO"
	}
}
```

5. Tratamento de Erros

Os erros abaixo são os mais comuns e são bem simples de tratá-los.

#Id	Erro	Tratamento
1	“plataforma_id ou plataforma_chave não especificados.”	Você não enviou os parâmetros de plataforma_id ou da plataforma_chave. Envie os parâmetro e seus valores.
2	“plataforma_id ou plataforma_chave incorretas.”;	Suas credenciais não batem com as registradas para você em nosso sistema. Verifique suas credenciais.
3	“tipoTransacao não definido.”;	Você não enviou o parâmetro do tipoTransacao com valor “consultaValorFrete”. Envie o parâmetro
4	“erro”: “Cep de destino/envio: XXXXXX inválido”	Verifique os Ceps enviados.
5	Outros tipo de erro	Verifique a mensagem. Podem ser erros de formatação de parâmetros ou de indisponibilidade de envio em Sedex ou Pac.