API de Estoque – Usadosbr/Moto.com.br

API de Estoque – Usadosbr/Moto.com.br

Tempo estimado: 10 minutos de leitura


Objetivo


A API de Integração tem como objetivo permitir a inserção, atualização, remoção e consulta de veículos. A integração é dividida em duas partes: autenticação e integração propriamente dita.


Autenticação


A autenticação é realizada via token JWT, um método padrão da indústria para autenticação entre duas partes por meio de um token assinado que autentica uma requisição web.


Requisição de Autenticação

Para autenticar, é necessário enviar uma requisição HTTP ao endpoint de autenticação da API com os seguintes dados:


POST – /login

{
"user" : "user", 
"password" : "password"
}


Resposta de Autenticação

Após a autenticação bem-sucedida, a API retornará um token que será utilizado para a integração:

{
"status": 200,
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0L2FwaS9sb2
dpbiIsImlhdCI6MTYwNzQzNDUyNSwiZXhwIjoxNjM4NTM4NTI1LCJuYmYiOjE2MDc0MzQ1MjUsImp0aS
I6Imw3d05pU1ZkOXdIUTFBbGYiLCJzdWIiOjQ5MywicHJ2IjoiNzBjOGZlODM0YWVhYzAwNzc5ODEwNW
YyMDUzOGEwZTBjNTJkMmE4YyJ9.KSktdsdtRG8IEzCGbtXjoC8PtzUhtSjn9GGB8yDISr8"
}


Integração de Carros


POST – /carros

DESCRIÇÃOEndpoint para integração de carros
HTTP METHOD POST
EndPoint HOM.https://api.usadosbr.dev/api/carros
EndPoint PROD.https://api.usadosbr.com/carros
Authorization Bearer «token gerado pela autenticação»


Operação: Atualizar ou Adicionar

ChaveDescriçãoTipo
Operacao* Adicionar ou AtualizarString
Codigo_consultaid (id Usadosbr); ou code (código referência integrador)Integer
Tipo_codigoDefine se fará a consulta por: id ou codeString
Status“Ativo” o carro estará ativo;
“Inativo” o carro estará inativo;
Nulo ou outro valor, será considerado inativo.		String
Placa*Placa do veículoString
Valor*Valor do veículoString
Codigo*ID de referência do veículoString
Marca**Marca do veículoString
Modelo**Modelo do veículoString
Versao**Versão do veículo
“1” veículo blindado
“0” Sem blindagem		String
Blindagem***Vazio, outro valor ou não enviar campo será considerado “Sem blindagem”String
Estilo**Estilo do veículoString
Cor**Cor do VeículoString
Combustivel**Tipo do CombustívelString
Cambio**Tipo do CâmbioString
Porta**Porta do VeículoString
AnoFabricacao*Ano de Fabricação do Veículo (>-1950)String
AnoModelo*Ano de Modelo do Veículo (>-1950)

Igual ou +1 em relação ao AnoFabricacao		String
UnicoDono*** “1” sim (veículo só teve um único dono)
“0” não (já teve mais de um dono)
Se não enviar será considerado “0”		String
VeiculoTipo*“1” Veículo 0 km
“0” Veículo usado		String
Kilometragem(*?)Quilometragem do Veículo
Obrigatório em VeiculoTipo = “0”		Integer
VideoUrl do vídeo no youtubeString
DestaqueValor se refere ao peso do destaque. “1” (destaque de peso 1) – Segunda Prioridade “2” (destaque de peso 2) – Primeira Prioridade “0” ou não enviado – Sem destaqueInteger
OpcionaisOpcionais do VeículoArray
ObservacoesComentários (max: 2000 caracteres) Não é permitido envio de htmlString
FotosArray de images, onde cada posição é um link para uma imagem. (max: 20)Array

* – Obrigatório

* – Obrigatório e conforme catálogo Usadosbr, endpoints de consulta listados
abaixo.

*** – Campo não obrigatório, sendo possível concluir a requisição mesmo sem o
envio do mesmo.


Exemplo de um json válido enviado para adicionar um veículo.

{
"Operacao" : "Adicionar", 
"Codigo_consulta" : 778899,
"Tipo_codigo" : "code", 
"Status" : "Ativo",
"Placa" : "XXX-9999",
"Valor" : "40000",
"Codigo": "23", 
"Marca" : "CHEVROLET",
"Modelo" : "PRISMA",
"Versao" : "1.4 LT 8V",
"Estilo" : "Seda",
“UnicoDono” : “1”,
“Blindagem” : “1”,
"Cor" : "Prata", 
"Combustivel" : "Á/G", 
"Cambio" : "Automático",
"Porta" : "2",
"AnoFabricacao" : "2010",
"AnoModelo" : "2012",
"VeiculoTipo": "20",
"Kilometragem" : 450,
“Video” : “https://youtu.be/mWdyuoYCgi0”
“Destaque” : 1
"Opcionais" : "Alarme",
"Fotos" : [
"https://images.usadosbr.com/manipulatedImages/media/gallery/8c/6c/24/renault_lo
gan_1-0_authentique_2010_goiânia_e3034010-cL-image-760x570-crop.jpg",
"https://images.usadosbr.com/manipulatedImages/media/gallery/8c/6c/24/rena
ult_logan_1-0_authentique_2010_goiânia_e3034010-cL-image-760x570-crop.jpg"
]
}


Possíveis Erros e Avisos


Status: 401 Unauthorized Caso, nenhum token seja enviado, ou o token enviado tenha expirado, ou seja inválido, a resposta trará o status = 401 (Unauthorized), e o acesso a API será bloqueada.

Exemplo de resposta:

{
  "status": "Token is Invalid"
}


Status: 422 Unprocessable Entity Este erro ocorre quando a request está bem formada, porém não é possível prosseguir devido à erros semânticos (Ex: Campos Obrigatórios não preenchidos, opcional não existente, marca inválida…). Nesse caso, a API retorna o(s) campo(s) que deram erro, e qual o motivo do erro.


Exemplo de resposta:

{
  "Modelo": [
    "O valor selecionado para o campo modelo não corresponde a marca selecionada."
  ],
  "Combustivel": [
    "O campo combustivel é obrigatório."
  ],
  "AnoFabricacao": [
    "O campo Ano Fabricação deve conter um valor maior que 1950"
  ],
  "Kilometragem": [
    "O campo kilometragem é obrigatório."
  ]
}


Se a quantidade de imagens enviadas ultrapassar o limite de 20 unidades, por veículo, será adicionado ou atualizado apenas as 20 primeiras imagens passadas na requisição.

Exemplo de resposta:

{
  "status": 200,
  "link": "http://usadosbr.com/carros-e-utilitarios/chevrolet/prisma/1-4-lt-8v-3/2012-prata-aracu-goias-4",
  "message": "Veículo atualizado com sucesso",
  "warning": {
    "message": {
      "image": "Quantidade de imagens enviadas ultrapassou o limite permitido. Foram inseridas no anúncio apenas as 20 primeiras imagens!."
    }
  }
}


Se o valor de destaque passado não esteja liberado para o advertiser ou a quantidade de anúncios cadastrados com esse peso já tenham excedido a cota de veículos no mesmo, o veículo será cadastrado ou atualizado “sem destaque”.


Exemplo de resposta:

{
  "status": 200,
  "link": "http://usadosbr.com/carros-e-utilitarios/chevrolet/prisma/1-4-lt-8v-3/2012-prata-aracu-goias-4",
  "message": "Veículo atualizado com sucesso",
  "warning": {
    "message": {
      "featured": "O destaque selecionado já atingiu a cota de veículos. O veículo foi adicionado sem destaque!."
    }
  }
}


Se o texto enviado no campo Observacoes ultrapassar o limite de 2000 caracteres, será adicionado no anúncio apenas os 2000 caracteres iniciais do texto.


Exemplo de resposta:

{
  "status": 200,
  "link": "http://usadosbr.com/carros-e-utilitarios/chevrolet/prisma/1-4-lt-8v-3/2012-prata-aracu-goias-4",
  "message": "Veículo atualizado com sucesso",
  "warning": {
    "message": {
      "comments": "Quantidade de caracteres do campo Observacoes ultrapassou o limite permitido. Foi inserido nas Observações do anúncio apenas os 2000 caracteres iniciais do texto enviado!."
    }
  }
}


Remoção de Veículo


Operação: Apagar

KEYDESCRIPTIONTYPE
Operação*ApagarString
Tipo_codigo*Define se fará a consulta por: id ou codeString
Codigo_consulta*Código de Consulta do veículo: id (id Usadosbr); ou code (código referência integrador)Integer


Exemplo de JSON para apagar um veículo:

{
  "Operacao": "Apagar",
  "Tipo_codigo": "code",
  "Codigo": "23"
}


ou

{
  "Operacao": "Apagar",
  "Tipo_codigo": "id",
  "Codigo": "78928828"
}


Exemplo de resposta para sucesso:

{
  "status": 200,
  "message": "Veículo removido com sucesso"
}


Possíveis Erros:

Veículo não encontrado (Status = 400)

{
  "status": 400,
  "message": "Veículo não encontrado para remoção"
}


Erro não esperado (Status = 500)

{
  "status": 500,
  "message": "Erro ao deletar o veículo"
}


Integração de motos

Post – /motos

DescriçãoEndpoint para integração de carros
HTTP METHODPOST
EndPoint HOM.https://api.usadosbr.dev/api/motos
EndPoint PROD.https://api.usadosbr.com/motos
AuthorizationBearer «token gerado pela autenticação»


Operação: Atualizar ou Adicionar

ChaveDescriçãoTipo
Operacao* Adicionar ou AtualizarString
Codigo_consultaid (id Usadosbr); ou
code (código referência integrador)		Integer
Tipo_codigoDefine se fará a consulta por: id ou codeString
Status“Ativo” o carro estará ativo;
“Inativo” o carro estará inativo;
Nulo ou outro valor, será considerado inativo.		String
Placa*Placa do veículoString
Valor*Valor do veículoString
Codigo*ID de referência do veículoString
Marca**Marca do veículoString
Modelo**Modelo do veículoString
Versao**Versão do veículo
“1” veículo blindado “0” Sem blindagem		String
Cilindrada**Cilindrada do VeículoString
Estilo**Estilo do veículoString
Cor**Cor do VeículoString
Combustivel**Tipo do CombustívelString
Cambio**Tipo do CâmbioString
AnoFabricacao*Ano de Fabricação do Veículo (>-1950)String
AnoModelo*Ano de Modelo do Veículo (>-1950)

Igual ou +1 em relação ao AnoFabricacao 		String
UnicoDono***“1” sim (veículo só teve um único dono) “0” não (já teve mais de um dono) Se não enviar será considerado “0”String
VeiculoTipo*“1” Veículo 0 km
“0” Veículo usado		String
Kilometragem(*?)Quilometragem do Veículo
Obrigatório em VeiculoTipo = “0”		Integer
VideoUrl do vídeo no youtubeString
DestaqueValor se refere ao peso do destaque. “1” (destaque de peso 1) – Segunda Prioridade
“2” (destaque de peso 2) – Primeira Prioridade
“0” ou não enviado – Sem destaque		Integer
OpcionaisOpcionais do VeículoArray
ObservacoesComentários (max: 2000 caracteres) Não é permitido envio de htmlString
FotosArray de images, onde cada posição é um link para uma imagem. (max: 20)Array

* – Obrigatório

* – Obrigatório e conforme catálogo Usadosbr, endpoints de consulta listados
abaixo.

*** – Campo não obrigatório, sendo possível concluir a requisição mesmo sem o
envio do mesmo.


Exemplo de um json válido enviado para adicionar uma moto.

{
"Operacao" : "Adicionar", 
"Codigo_consulta" : 778899,
"Tipo_codigo" : "code", 
"Status" : "Ativo",
"Placa" : "PPP-3034",
"Valor" : "40000",
"Codigo": "7998",
"Marca" : "Honda", 
"Modelo" : "CG 150 Titan",
"Versao" : " 150cc KS",
"Estilo" : " Street",
“UnicoDono” : “0”,
"Cor" : "Prata", 
"Combustivel" : "Á/G", 
"Cambio" : "Mecânico", 
"AnoFabricacao" : "2010",
"AnoModelo" : "2011",
"VeiculoTipo": "0",
"Kilometragem" : 4500,
“Video” : “https://youtu.be/mWdyuoYCgi0”
"Opcionais" : "Alarme",
"Fotos" : [
"https://rihappy.vteximg.com.br/arquivos/ids/383652-768-768/mini-motowelly-escala-1-10-honda-cb500f-california-toysWEL62800W_Frente.jpg?v=636936214699470000",
"https://rihappy.vteximg.com.br/arquivos/ids/383652-768-768/mini-motowelly-escala-1-10-honda-cb500f-california-toys- WEL62800W_Frente.jpg?
v=636936214699470000"
]
}


Possíveis Erros e Avisos

Status: 401 Unauthorized

Caso, nenhum token seja enviado, ou o token enviado tenha expirado, ou seja
inválido, a resposta trará o status = 401 (Unauthorized), e o acesso a API será
bloqueada. Conforme já mostrado na Integração de Carros.

Status: 422 Unprocessable Entity

Este erro ocorre quando a request está bem formada, porém não é possível
prosseguir devido à erros semânticos (Ex: Campos Obrigatórios não preenchidos, opcional não
existente, marca inválida…). Nesse caso, a API retorna o(s) campo(s) que deram
erro, e qual o motivo do erro.

Status 200 com Aviso

Caso o veículo passado tenha imagens, e algumas delas tenham resolução menor a
permitida (760 de largura de 570 de altura), ou não exista (link quebrado, por
exemplo), o veículo será cadastrado, porém a API retornará quais imagens deram
problema. As demais que são maiores que o estabelecido serão vinculadas ao
carro.

Se a quantidade de imagens enviadas ultrapassar o limite de 20 unidades, por
veículo, será adicionado ou atualizado apenas as 20 primeiras imagens passadas
na requisição.

Caso o valor de destaque passado não esteja liberado para o advertiser ou a
quantidade de anúncios cadastrados com esse peso já tenham excedido a cota de
veículos no mesmo, o veículo será cadastrado ou atualizado “sem destaque”.

Se o texto enviado no campo Observacoes ultrapassar o limite de 2000 caracteres,
será adicionado no anúncio apenas os 2000 caracteres iniciais do texto.


Operação: Apagar

ChaveDescriçãoTipo
Operacao*Apagar String
Tipo_codigoPermite diferenciar se fará a consulta com base no id do veículo ou se fará a consulta pelo code do veículo.String
Código*ID de referência do veículoString
* – Obrigatório


Exemplo de JSON para apagar um veículo

{
"Operacao" : "Apagar", 
"Tipo_codigo" : "code",
"Codigo": "23"
}


Ou

{
"Operacao" : "Apagar",
"Tipo_codigo" : "id", 
"Codigo": "78928828"
}


Exemplo de resposta para sucesso

{
"status": 200,
"message": "Veículo removido com sucesso"
}


Possíveis Erros

Veículo não encontrado (Status = 400)

{
"status": 400,
"message": "Veículo não encontrado para remoção"
}


Erro não esperado (Status = 500)

{
"status": 500,
"message": "Erro ao deletar o veículo"
}


Endpoints de Consulta


Para os endpoints de consulta, o type deve ser substituído conforme as opções existentes: carros ou motos.

GET /{type}/consultar

Endpoint que retorna todos os veículos cadastrados do advertiser com a paginação.

Exemplo: /carros/consultar

{
"current_page": 1,
"data": [
{
"id": 997184,
"status": "active", 
"code": null, 
"contact_name": "teste",
"contact_phone": "(64) 99300-1277",
"star": 0, 
"manual_star": null,
"used_star": 0,
"advertiser_id": 69539,
"version_id": 1,
"style_id": 1,
"color_id": 4,
"fuel_id": 1,
"shifter_id": 1,
"door_id": 5,
"shield": 0,
….
}


A paginação dos resultados por padrão está fixada em 15 veículos, mas essa quantidade pode ser alterada, basta que o parâmetro “per_page” seja incluso na requisição juntamente com o valor desejado.

{
"first_page_url": "/carros/consultar?page=1",
"from": 1,
"last_page": 4,
"last_page_url": "/carros/consultar?page=4",
"next_page_url": "/carros/consultar?page=2",
"path": "/carros/consultar",
"per_page": 15, 
"prev_page_url": null,
"to": 15,
"total": 52
}


A navegação pelas páginas apenas requer o parâmetro “page” com o valor da página desejada, como mostrado abaixo no exemplo:

/carros/consultar?page=2

Exemplo de consulta com a quantidade por página modificada, o retorno será de 2 veículos por página:

/carros/consultar?per_page=2


Consulta de Planos/Destaques

GET /consultar/planos

Endpoint para consultar a disponibilidade e situação de destaque do advertiser. Para efetuá-la é necessário fazer a autenticação e retornar o token repassado na autenticação.

{
 "status": 200,
 "message": {
   "planos": {
    "total": 10,
    "ativo": 0
},
"destaques": {
 "1": {
  "nome": "SEGUNDA PRIORIDADE",
  "ativo": 0,
  "limite": 5
}, 
"2": {
 "nome": "PRIMEIRA PRIORIDADE",
 "ativo": 0,
 "limite": 5
     }
   }
 }
}


Consulta de Status do anúncio

GET /{type}/consultar/status/{code}

Endpoint para consultar status de veículos cadastrados. Para realizar a consulta é necessário passar pela autenticação e retornar o token repassado. O parâmetro “code” é o Código passado no cadastro ou atualização do veículo como ID de referência do mesmo.


Exemplo: /carros/consultar/status/7998

{
"status": 200, 
"anuncio": "Ativo"
}


Consulta de Marcas


GET /{type}/consultar/marcas

Endpoint para consultar marcas. Para o valor passado em Marca ser considerado válido, ele deve constar nessa lista.

Exemplo: /carros/consultar/marcas/

{
"status": 200,
"marcas": [
      "ACURA",
      "ADAMO",
      "AGRALE", 
      "ALFA ROMEO",
      "AMAZONAS", 
      "AMERICAR", 
      "ASIA",
      "ASTON MARTIN",
      "AUDI",
      "AUSTIN-HEALEY",
...
]
}


Consulta de Modelos


GET / {type}/consultar/modelos/{marca}

Endpoint para consultar modelos. Para o valor passado em Modelo ser considerado válido, ele deve constar na lista da Marca selecionada.


Exemplo: /carros/consultar/modelos/CHEVROLET

{
"status": 200, 
"marca": "CHEVROLET",
"modelos": [
    "A10",
    "A20",
    "ADVANCED DESIGN",
    "AGILE", 
    "AMAZONA", 
    "ASTRA", 
    "ASTROVAN", 
    "AVALANCHE",
...
]
}


Consulta de versões


GET /{type}/consultar/versoes/{marca}/{modelo}

Endpoint para consultar versões. Para o valor passado em Versao ser considerado válido, ele deve constar na lista do Modelo selecionado.

Exemplo: /carros/consultar/versoes/CHEVROLET/PRISMA

{
"status": 200, 
"marca": "CHEVROLET",
"modelo": "PRISMA",
"versoes": [
    "1.0 ADVANTAGE 8V",
    "1.0 JOY 8V",
    "1.0 LT 8V",
    "1.0 MAXX 8V",
    "1.0 VHCE 8V",
    "1.4 ADVANTAGE 8V",
    "1.4 JOY 8V",
    "1.4 LT 8V",
    "1.4 LTZ 8V",
    "1.4 MAXX 8V"
  ]
}


Consulta de Estilos


GET /{type}/consultar/estilos/{marca}/{modelo}

Endpoint para consultar estilos. Para o valor passado em Estilo ser considerado válido, ele deve constar na lista do Modelo selecionado.

Exemplo: /carros/consultar/estilos/CHEVROLET/PRISMA

{
"status": 200,
"marca": "CHEVROLET",
"modelo": "PRISMA",
"estilos": [
     "Sedã"
  ]
}


Consulta de Cores

GET /{type}/consultar/cores

Endpoint para consultar cores. Para o valor passado em Cor ser considerado válido, ele deve constar nesta lista.

{
"status": 200,
"cores": [
   "Amarelo",
   "Azul",
   "Bege",
   "Branco",
   "Cinza", 
   "Diversas Cores",
...
]
}


Consulta de Combustíveis


GET /{type}/consultar/combustiveis

Endpoint para consultar combustíveis. Para o valor passado em Combustível ser considerado válido, ele deve constar nesta lista.

{
"status": 200, 
"combustiveis": [
   "Á/G",
   "Álcool",
   "Diesel", 
   "Elétrico",
   "Gasolina",
   "GNV",
   "Híbrido"
]
}


Consulta de Câmbios

GET /{type}/consultar/cambios

Endpoint para consultar câmbios. Para o valor passado em Cambio ser considerado válido, ele deve constar nesta lista.

{
"status": 200,
"cambios": [
   "Automático",
   "Manual",
   "Semi-automático"
...
]
}


Consulta pelo Número de Portas

* Disponível apenas para carros

GET /{type}/consultar/portas

Endpoint para consultar número de portas. Para o valor passado em Portas ser considerado válido, ele deve constar nesta lista.

{
"status": 200,
"portas": [
   "1",
   "2",
   "3",
   "4",
   "5"
 ]
}


Consulta de Cilindradas

*Disponível apenas para motos

GET /motos/consultar/cilindradas

Endpoint para consultar cilindradas. Para o valor passado em Cilindradas ser considerado válido, ele deve constar nesta lista.

{
"status": 200, 
"cilindradas": [
  "100",
  "1000",
  "1050",
  "110",
  "1100",
  "1130",
...
 ]
}


Consulta de Opcionais

GET /{type}/consultar/opcionais

Endpoint para consultar os opcionais para determinado tipo de veículo. Para os valores passados em Opcionais serem considerados válidos, eles devem constar nesta lista, e devem ser passados por array. Caso algum opcional não exista, o veículo será criado com os demais opcionais válidos.

Exemplo: /carros/consultar/opcionais

{
"status": 200,
"opcionais": [
  "Abertura elétrica do porta malas", 
  "Acendimento automático dos faróis",
  "Air-Bag",
  "Air-Bag lateral",
  "Alarme",
...
  "Teto solar panorâmico",
  "Trava Elétrica",
  "Vidro Elétrico"
 ]
}


api_integracao_veiculos__v8Baixar
Avalie este artigo