Bem-vindo nossa Documentação da API para os serviços do Boxit Brasil. Toda a informação contida neste documento está dirigida para a gestão da entrega de pacotes nossos armários inteligentes. Nesta, fornecemos os principais endpoints para que você possa integrar da maneira mais fácil, rápida e eficiente possível. Se você tiver alguma dúvida ou precisar de informações adicionais, entre em contato conosco através dos canais listados abaixo.
v1.0.1
Copyright Myboxit S.A. 2022 All rights reserved.
Toda a comunicação da API do Boxit é através do formato JSON.
{
"Content-Type": "Application/json",
"Accept": "Application/json"
}
Aqui estão alguns códigos de resposta gerais que você pode obter ao testar com nossa API.
[
{
"code": 400,
"message": "Usuário é requerido"
}
]
[
{
"code": 400,
"message": "Senha é requerida"
}
]
[
{
"code": 400,
"message": "Auth header é requerido"
}
]
[
{
"code": 401,
"message": "Não tem acesso"
}
]
[
{
"code": 500,
"message": "Erro interno no servidor"
}
]
Nestas rotas encontrará toda a informação necessária para gerir a criação de um pacote e efetuar a respetiva autenticação junto do nosso sistema.
A API Boxit usa BasicAuth.
Todas as requisições realizadas ao Boxit devem incluir o usuário e senha para validação do método.
Caso haja algum erro com a autenticação, será retornado o messagem do Ex. 2
Cada empresa tem apenas um único Usuário e senha. Caso não possua seu credencial de integração, entre em contato conosco pelo canal sistema@myboxit.com.br e solicite o seu.
É preciso ter cadastro na plataforma Boxit previamente, a fim de permitir a integração da sua empresa.
Destacamos que a sua integração será considerada apta para funcionamento, após passar pelo processo de Testes e Homologação do Boxit.
{
"code": 401,
"message": "Não tem acesso"
}
Para que você possa realizar os testes necessários em nossas rotas, desenvolvemos um ambiente de testes para você baseado no Swagger, que você encontra no link a seguir. É importante lembrar novamente que você deve ter as credenciais adequadas para fazer esses testes.
Além disso, para tornar o trabalho muito mais fácil, deixamos uma coleção de Postman.
Development: https://staging.api.myboxit.com.br
Esta rota foi criada para que você possa fazer login e validar se suas credenciais estão corretas.
Não é necessário enviar nenhuma informação adicional, nada mais que suas credenciais, através do método BasicAuth.
const resp = await fetch(`https://staging.api.myboxit.com.br/api/v1/standard/verificacao/credenciais`,
{
method: 'GET',
headers: {
Authorization: 'Basic ' + btoa('<username>:<password>')
}
}
);
const data = await resp.text();
console.log(data);
[
{
"code": 200,
"message": "Autenticação bem sucedida"
}
]
[
{
"code": 401,
"message": "Usuário ou senha inválida"
}
]
Permite fazer um pedido para entregar no armário. O Cliente/Empresa irá disparar o conjunto de dados abaixo.
Formato de requisição
Propriedade | Descrição | Formato |
---|---|---|
remetente |
Objeto com dados de endereço do remetente / origem da carga | JSON |
cnpj |
CNPJ do remetente da carga | String de 14 caracteres sem formatação |
cep |
CEP do remetente / origem da carga | String de 8 caracteres sem formatação |
destinatario |
Objeto com dados de endereço do destinatário da carga | JSON |
cnpj_cpf |
CNPJ do destinatário da carga (se Pessoa Jurídica). Caso esteja vazio, considerar o destinatário como Pessoa Física. | String de 11 ou 14 caracteres sem formatação |
cep |
CEP do destinatário / destino da carga | String de 8 caracteres sem formatação |
carga |
Objeto com dados gerais da carga (somatório dos volumes) | JSON |
valor_total |
Valor total da carga (todos os volumes) | Numérico (float) |
cubagem |
Cubagem total calculada pelas dimensões de todos os volumes que compõe a carga. Fator de cubagem: 300 Kg / M³ | Numérico (float) |
peso_real |
Peso real da carga (todos volumes) | Numérico (float) |
total_volumes |
Quantidade total dos volumes informados | Numérico (inteiro) |
volumes |
Array com um ou mais objetos dos volumes informados | Array [JSON] |
altura |
Altura do volume unitário em metros | Numérico (float) |
largura |
Largura do volume unitário em metros | Numérico (float) |
comprimento |
Comprimento do volume unitário em metros | Numérico (float) |
quantidade |
Quantidade de volumes iguais e do mesmo tipo | Numérico (inteiro) |
peso_real |
Peso total (em Kg) dos volumes informados. Exemplo: 6 volumes com 0.5 Kg cada, o valor informado será de 3 Kg | Numérico (float) |
valor |
Valor total do volumen | Numérico (float) |
Formato de resposta
Propriedade | Descrição | Formato |
---|---|---|
codcotacao |
Código de cotação | Numérico (inteiro) |
preco |
Preço do frete | Numérico (float) |
prazo_entrega |
Prazo em dias úteis para a realização da entrega | Numérico (inteiro) |
servico |
Tipo de serviço para a realização da entrega | String |
armario_nome |
Nome do armário | String |
armario_endereco |
Endereço do armário | String |
armario_cep |
CEP do armário | String |
validade_cotacao |
Validade da proposta da cotação | Date ("YYYY/MM/DD") |
const resp = await fetch(
`https://staging.api.myboxit.com.br/v1/standard/cotacao_locker`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Basic ' + btoa('<username>:<password>')
},
body: JSON.stringify({
remetente: {
cnpj: "",
cep: ""
},
destinatario: {
cnpj_cpf: "",
cep: ""
},
carga: {
valor_total: 0,
cubagem: 0,
peso_real: 0,
total_volumes: 2
},
volumes: [{
altura: 0,
largura: 0,
comprimento: 0,
quantidade: 1,
peso_real: 0,
valor: 0
}]
})
}
);
const data = await resp.json();
console.log(data);
[
{
"code": 200,
"message": "Sucesso",
"cotacao": [
{
"codcotacao": 104,
"preco": 17.7,
"prazo_entrega": 4,
"servico": "Entrega em locker",
"armario_nome": "Boxit Teste 001",
"armario_endereco": "Rua Benjamin Constant, 02 - Assis - SP - 19806130",
"armario_cep": "19806130",
"validade_cotacao": "2022/01/01"
}
]
}
]
[
{
"code": 203,
"message": " O pedido excede o limite de peso"
}
]
[
{
"code": 203,
"message": "O pedido é muito grande para o armário"
}
]
[
{
"code": 203,
"message": "Não há armários perto desta localização"
}
]
Permite o cadastro de um pacote para entrega no armário. O Cliente/Empresa irá disparar o conjunto de dados abaixo.
Formato de requisição
Propriedade | Descrição | Formato |
---|---|---|
codcotacao |
Identificador único de cada cotação/frete no Boxt. Através deste é possível obter e relacionar todos os outros dados | String de 13 caracteres |
numero_pedido |
Número do pedido na loja/Número que identificará o pacote | String |
tipo_pedido |
2= Pacote Novo, 3= Pacote Reverso | int |
data_pedido |
Data de criação do pedido na loja | Datetime (YYYY-MM-DD HH:mm:ss) |
data_coleta |
Data de coleta informada pelo Embarcador | Date ("YYYY/MM/DD") |
remetente |
Objeto com dados de endereço do remetente / origem da carga | JSON |
cnpj |
CNPJ do remetente da carga | String de 14 caracteres sem formatação |
razao_social |
Razão Social do remetente da carga | String |
endereco |
Objeto | JSON |
cep |
CEP do remetente | String |
rua |
Logradouro do remetente | String |
numero |
Número do local do remetente | String |
bairro |
Bairro do remetente | String |
complemento |
Complemento do endereço (se houver) | String |
cidade |
Cidade do remetente | String |
estado |
Estado do remetente (exemplo: SP) | String |
destinatario |
Objeto com dados de endereço do destinatário da carga | JSON |
cnpj_cpf |
CNPJ ou CPF do destinatário da carga. Você pode validar se é Pessoa Física ou Jurídica pela quantidade de caracteres. | String de 11 ou 14 caracteres sem formatação |
nome |
Nome ou Razão Social do destinatário da carga | String |
email |
E-mail do destinatário da carga | String |
telefone |
Telefone do destinatário da carga | String |
const resp = await fetch(
`https://staging.api.myboxit.com.br/api/v1/standard/registrar_pacote_locker`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Basic ' + btoa('<username>:<password>')
},
body: JSON.stringify({
codcotacao: "100",
numero_pedido: "1234",
tipo_pedido: 2,
data_pedido: "",
data_coleta: "",
remetente: {
cnpj: "",
razao_social: "",
endereco: {
cep: "",
rua: "",
numero: "",
bairro: "",
complemento: "",
cidade: "",
estado: ""
}
},
destinatario: {
cnpj_cpf: "",
nome: "",
email: "",
telefone: ""
}
})
}
);
const data = await resp.json();
console.log(data);
[
{
"code": 200,
"message": "Pacote 1234 criado com sucesso",
"id_pedido": "100"
}
]
[
{
"code": 203,
"message": "Nenhuma cotação encontrada com esse código"
}
]
[
{
"code": 203,
"message": "Já existe um pacote criado com esse código de cotação"
}
]
Permite cancelar um pacote que já foi criado anteriormente. O Cliente/Empresa irá disparar o conjunto de dados abaixo.
Formato de requisição
Propriedade | Descrição | Formato |
---|---|---|
numero_pacote |
Número de identificação do pacote | String |
const resp = await fetch(
`https://staging.api.myboxit.com.br/api/v1/standard/cancelamento`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Basic ' + btoa('<username>:<password>')
},
body: JSON.stringify({
numero_pacote: '2020101412483700200000'
})
}
);
const data = await resp.json();
console.log(data);
[
{
"code": 200,
"message": "Cancelamento do pacote: 2020101412483700200000 foi feito com sucesso"
}
]
[
{
"code": 400,
"message": "Não foi possível cancelar o pacote"
}
]
[
{
"code": 400,
"message": "Não foi possível cancelar o numero do pacote: 2020101412483700200000 não está cadastrado no sistema"
}
]
Com esta rota pode consultar todos os pacotes que tenha registado no nosso sistema, independentemente do seu estado.
const resp = await fetch(`https://staging.api.myboxit.com.br/api/v1/standard/consultar/pacotes`,
{
method: 'GET',
headers: {
Authorization: 'Basic ' + btoa('<username>:<password>')
}
}
);
const data = await resp.text();
console.log(data);
[
{
"code": 200,
"message": "Autenticação bem sucedida"
}
]
[
{
"code": 401,
"message": "Usuário ou senha inválida"
}
]
Integração básica para o uso do armário, permite criar um pacote e fazer uma reserva de porta.
A API Boxit usa JWT Authentication .
Todas as requisições feitas ao Boxit devem incluir o token para validação do método.
Para obter o token, precisa realizar uma Autenticação Básica, com um nome de usuário e senha fornecidos pela Boxit.
Cada empresa tem apenas um único Usuário e senha. Caso não possua seu credencial de integração, entre em contato conosco pelo canal sistema@myboxit.com.br e solicite o seu.
É preciso ter cadastro na plataforma Boxit previamente, a fim de permitir a integração da sua empresa.
Destacamos que a sua integração será considerada apta para funcionamento, após passar pelo processo de Testes e Homologação do Boxit.
Caso haja algum erro com a autenticação, será retornado o messagem do Ex. 2
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/companies/signin",
"method": "POST",
"timeout": 0,
"headers": {
"Authorization": "Basic <username>:<password>"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "SIGNIN_SUCCESS",
"payload": {
"clientId": 123,
"companyId": 10,
"companyName": "MYBOXIT"
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
}
]
[
{
"code": 400,
"message": "USER_OR_PASSWORD_INVALID"
}
]
[
{
"code": 404,
"message": "USER_NOT_FOUND"
}
]
Permite o cadastro de um pacote para entrega no armário. O Cliente/Empresa irá disparar o conjunto de dados abaixo.
Formato de requisição
Propriedade | Descrição | Formato |
---|---|---|
trackingNumber |
Número do pedido do cliente/ loja/Número que identificará o pacote | String |
description |
Descrição do pacote | String |
locationId |
ID do armário | Int |
weight |
Peso do pacote em Kg | Numeric (18,2) |
size |
S=Pequeno, M=Médio, L=Grande | String |
email |
E-mail do destinatário da carga | String |
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/packages/basic",
"method": "POST",
"timeout": 0,
"headers": {
"Authorization": "Bearer <TOKEN> ",
"Content-Type": "application/json"
},
"data": JSON.stringify({
"trackingNumber": "package-ml-0006",
"description": "test package basic integration brazil",
"locationId": 15,
"weight": 1,
"size": "S",
"email": "exemplo@gmail.com"
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "PACKAGE_CREATED",
"boxitReservationId": "001540717"
}
]
[
{
"code": 400,
"Mensaje": "PACKAGE_CANT_BE_CREATED",
}
]
Permite atribuir uma porta para um pacote previamente criado.
Formato de requisição
Propriedade | Descrição | Formato |
---|---|---|
boxitReservationId |
Número do pacote gerado pelo Boxit, retornado no momento da criação. | String |
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/packages/reservation/{:boxitReservationId}",
"method": "POST",
"timeout": 0,
"headers": {
"Authorization": "Bearer <TOKEN>"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "DOOR_ASSIGNED",
"doorNumber": "7"
}
]
[
{
"code": 404,
"message": "PACKAGE_NOT_FOUND"
}
]
Permite verificar as informações de um pacote criado no Boxit.
Formato de requisição
Propriedade | Descrição | Formato |
---|---|---|
boxitReservationId |
Número do pacote gerado pelo Boxit, retornado no momento da criação. | String |
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/packages/{:boxitReservationId}",
"method": "POST",
"timeout": 0,
"headers": {
"Authorization": "Bearer <TOKEN>"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "RESERVATION_FOUND",
"payload": [
{
"locationId": 15,
"lockerName": "Boxit Entrega Já - Showroom",
"doorNumber": null,
"trackingNumber": "boxit-ml-000",
"boxitReservationId": "00154071800",
"email": "email@myboxit.com",
"size": "S",
"password": "123456",
"createdAt": "2023-01-31T16:24:39.290Z",
"packageType": 2,
"status": "NEW"
}
]
}
]
[
{
"code": 404,
"message": "NO_RESERVATIONS_FOUND"
}
]
Uma vez criado o pacote, apenas seu tamanho e o e-mail do cliente podem ser atualizados.
Formato de requisição
Propriedade | Descrição | Formato |
---|---|---|
size |
S=Pequeno, M=Médio, L=Grande | String |
email |
E-mail do destinatário da carga | String |
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/packages/{:boxitReservationId}",
"method": "PATCH",
"timeout": 0,
"headers": {
"Authorization": "Bearer <TOKEN>",
"Content-Type": "application/json"
},
"data": JSON.stringify({
"size": "S",
"email": "email@myboxit.com"
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "RESERVATION_FOUND",
"payload": [
{
"locationId": 15,
"lockerName": "Boxit Entrega Já - Showroom",
"doorNumber": null,
"trackingNumber": "boxit-ml-000",
"boxitReservationId": "00154071800",
"email": "email@myboxit.com",
"size": "S",
"password": "123456",
"createdAt": "2023-01-31T16:24:39.290Z",
"packageType": 2,
"status": "NEW"
}
]
}
]
[
{
"code": 404,
"message": "NO_RESERVATIONS_FOUND"
}
]
Este processo permite o cancelamento de um pacote
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/packages/{:boxitReservationId}",
"method": "DELETE",
"timeout": 0,
"headers": {
"Authorization": "Bearer TOKEN"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "RESERVATION_CANCELED"
}
]
[
{
"code": 404,
"message": "PACKAGE_NOT_FOUND"
}
]
Retorna todos os armários ativos para a empresa. O método é chamado, nenhum dado de entrada é enviado, apenas a autenticação. O Cliente/Empresa irá disparar o conjunto de dados abaixo.
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/platforms",
"method": "GET",
"timeout": 0,
"headers": {
"Authorization": "Bearer <TOKEN>"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "LOCKERS_FOUND",
"payload": [
{
"locationId": 1,
"locationName": "Boxit A01",
"locationStatus": "ONLINE",
"address": "Rua Votuporanga Brasil",
"cep": "00000-000",
"coordinates": "-23.663300,-46.53100",
"link": "https://www.google.com/maps",
"doors": [
{
"size": "L",
"availability": 8,
"width": 48,
"height": 50,
"deep": 50
},
{
"size": "M",
"availability": 10,
"width": 48,
"height": 33,
"deep": 50
},
{
"size": "S",
"availability": 9,
"width": 48,
"height": 16,
"deep": 50
}
]
},
{
"locationId": 2,
"locationName": "Boxit A02",
"locationStatus": "ONLINE",
"address": "CL SANCA ITAPEVI, Itapevi",
"cep": "00000-000",
"coordinates": "-23.64145902,-46.7244494",
"link": "https://www.google.com",
"doors": [
{
"size": "L",
"availability": 2,
"width": 48,
"height": 50,
"deep": 50
},
{
"size": "M",
"availability": 2,
"width": 48,
"height": 33,
"deep": 50
},
{
"size": "S",
"availability": 3,
"width": 48,
"height": 16,
"deep": 50
}
]
}
]
}
]
[
{
"code": 404,
"message": "Nenhuma plataforma emcontrada"
}
]
Permite a configuração e cadastro de endpoints para envio das informações do Boxit Webhook. Os eventos são os seguintes
**notificationType: 1 , quando um armário muda de status ONLINE-OFFLINE.
Retorna o seguinte Json:
LockerStatus {
locationId: string;
status: boolean;
date: date;
}
status: 1 ONLINE, 0 OFFLINE
**notificationType: 3, quando um pacote muda de status, de acordo com uma transação realizada.
PackageMovement {
boxitReservationId: number;
reservationId: string;
trackingNumber: string;
movementType: number;
boxID: number;
signature: string;
locationId: string;
deliveryAgentId: number;
customerId: number;
date: Date;
photo: string;
}
movementType: 1. O pacote foi entregue no armário
2. O pacote foi retirado do armário
8. O pacote foi removido do armário porque seu tempo expirou
Formato de requisição
Propriedade | Descrição | Formato |
---|---|---|
notificationType |
1 , quando um armário muda de status ONLINE-OFFLINE. 3, quando um pacote muda de status, de acordo com uma transação realizada. | INT |
url |
URL da empresa | String |
apiKey |
Key para consumir o endpoint registrado | String |
method |
tipo de método=POST | String |
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/companies/webhook",
"method": "POST",
"timeout": 0,
"headers": {
"Authorization": "Bearer <TOKEN>",
"Content-Type": "application/json"
},
"data": JSON.stringify({
"notificationType": 1,
"url": "https://example.com/platforms/status",
"apiKey": "123",
"method": "POST"
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "NOTIFICATION_CREATED"
}
]
[
{
"code": 400,
"message": "MISSING_URL_FIELD"
}
]
Consulte as informações cadastradas do Webhook
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/companies/webhook",
"method": "GET",
"timeout": 0,
"headers": {
"Authorization": "Bearer <TOKEN>"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
{
"code": 200,
"message": "COMPANY_FOUND",
"payload": [
{
"url": "https://dev.myboxit.com:2053/gl/platforms/status",
"method": "POST",
"apiKey": "123",
"notificationType": 1
}
]
}
Atualizar as informações cadastradas do Webhook
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/companies/webhook/1",
"method": "PATCH",
"timeout": 0,
"headers": {
"Authorization": "Bearer <TOKEN>",
"Content-Type": "application/json"
},
"data": JSON.stringify({
"notificationType": 1,
"url": "https://dev.myboxit.com:2053/gl/platforms/status2",
"method": "",
"apiKey": "1232"
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "NOTIFICATION_UPDATED"
}
]
Cancelar as informações cadastradas do Webhook
var settings = {
"url": "https://dev.api.myboxit.com.br/v2/companies/webhook/1",
"method": "DELETE",
"timeout": 0,
"headers": {
"Authorization": "Bearer <TOKEN>"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
[
{
"code": 200,
"message": "NOTIFICATION_DELETED"
}
]