Construindo sua API
A sua API deve receber os dados da vistoria e retornar os dados que você deseja preencher nos campos da vistoria segundo as especificacões abaixo.
Comportamento da API
- Sua API receberá a placa na URL no lugar do termo '{placa}', seja no caminho ou na query string.
- Sua API sempre deve retornar 200 como status code, mesmo se a placa não foi encontrada.
- A mensagem retornada deve ser um JSON válido (
Content-Type: application/json). - Veja um exemplo no link.
Retorno de erros
- A sua API deve responder com o status code 200 mesmo se a placa não foi encontrada.
- Só retorne um status code diferente de 200 se a sua API não estiver operando normalmente, como no caso de um erro desconhecido.
- Se quiser retornar um erro, você deve enviar um JSON como corpo da resposta em um dos seguintes formatos:
{
"result": "ERRO",
"msg": "<sua mensagem de erro aqui>"
}{
"erro": "<sua mensagem de erro aqui>"
}
Disponibilidade
- Caso sua API esteja indisponível no momento em que o vistoriador iniciar a vistoria, uma mensagem será apresentada e nenhum dado será preenchido automaticamente.
- Fazemos diariamente uma validação de funcionamento da sua API.
- Caso sua API utilize autenticação, você precisará criar uma API intermediária para contornar esta exigência.
- Caso queira acrescentar uma camada extra de segurança, adicione uma regra para que sua API aceite somente requisições do servidor do VEXSOFT.
Request
Com o início da vistoria pelo vistoriador no nosso aplicativo, o nosso sistema enviará a requisição iniciadora para a sua API. Essa requisição será um GET e conterá os seguintes
dados:
Query parameters
| nome | descricao |
|---|---|
| placa | A placa inserida pelo vistoriador no APP |
Headers
| nome | descricao |
|---|---|
| tipo-consulta | Tipo da consulta iniciada ('placa' ou 'chassi') |
| placa | A placa inserida pelo vistoriador no APP |
| chassi | O chassi utilizado para iniciar a vistoria (se utilizado) |
| id-tipo-operacao | ID do tipo de operação selecionado no início da vistoria |
| x-vex-nome-usuario | Nome do usuário iniciando a vistoria |
| id-usuario | ID do usuário iniciando a vistoria |
| cnpj-usuario | CNPJ do usuário iniciando a vistoria |
| versao-app | Versão do app (VEX) que o vistoria está utilizando |
| id-questionario | ID do questionário selecionado no início da vistoria |
| tipo-vistoria-base | Tipo base da vistoria sendo iniciada (1: Entrega, 2: Coleta, 3: Coleta com entrega, 4: Pré-vistoria, 5: Cautelar, 6: Auto inspeção) |
dica
Além desses headers enviados pelo aplicativo, também serão enviados os headers estáticos configurados na tela de integragração do painel.
Clique aqui para mais informações sobre como configurar headers fixos adicionais.
Exemplo (cURL)
curl -X GET 'https://<url da sua api>?placa=Cannot find module './prism-sh'' \
-H 'placa: ABC1D091' \
-H 'id-tipo-operacao: 43' \
-H 'x-vex-nome-usuario: Davi Sobrenome' \
-H 'versao-app: 2.9.18.5' \
-H 'id-questionario: 37973' \
-H 'tipo-consulta: placa' \
-H 'tipo-vistoria-base: 1' \
-H 'id-usuario: 24681' \
-H 'cnpj-usuario: 23134979000196'
Response
O corpo da sua resposta deve ser um JSON, que pode conter os campos abaixo:
| Campo | tipo | Descrição |
|---|---|---|
| idExterno | integer | ID da vistoria no sistema de integração da sua empresa |
| idUsuario | string | Não utilizado * |
| vistoriador | string | Não utilizado * |
| bateria | string | Não utilizado * |
| cidade | string | Será preenchido no campo "Cidade" na aba inicial |
| cliente.nome | string | Será preenchido no campo "Nome do cliente" na aba inicial |
| cliente.email | string | Será preenchido no campo "Digite o email do cliente" na aba inicial |
| cliente.fone | string | Será preenchido no campo "Telefone do cliente" na aba inicial |
| cliente.cpf | string | Não utilizado * |
| cliente.rg | string | Não utilizado * |
| AssinaturaCliente.Nome | string | Será preenchido no campo "Nome" na aba de assinatura do cliente |
| AssinaturaCliente.Telefone | string | Será preenchido no campo "Telefone" na aba de assinatura do cliente |
| AssinaturaCliente.Rg | string | Será preenchido no campo "RG" na de assinatura do cliente |
| contrato | string | Será preenchido no campo "Número do contrato" na aba inicial |
| localVistoria | string | Será preenchido no campo "Local Atendimento" na aba inicial |
| marcaBateria | string | Não utilizado * |
| motorista | string | Será preenchido no campo "Motorista" na aba inicial |
| data | string | Não utilizado * |
| hora | string | Não utilizado * |
| emailCliente | string | Não utilizado * |
| tipoVistoria | string | Não utilizado * |
| termosAceiteVistoria | string | Será preenchido no campo "Termos" na aba cliente |
| observacao | string | Será preenchindo no campo "Observação" na aba inicial |
| fotos | objeto | Links das fotos da vistoria, será visualizada na aba fotos |
| veiculo.ano | string | Será preenchido no campo "Ano" na aba inicial |
| veiculo.nivelCombustivel | string | Será visualizado no campo "Nível combustível" na aba inicial OBS: Os números aceitos são somente de 0 a 8 |
| veiculo.placa | string | Será preenchido no campo "Placa" na aba inicial |
| veiculo.nome | string | Será preenchido no campo "Veículo" na aba inicial |
| veiculo.pneus.esquerdoDianteiro.marca | string | Será preenchido na marca do campo "Pneu dianteiro esquerdo" |
| veiculo.pneus.esquerdoDianteiro.situacao | string | Não utilizado * |
| veiculo.pneus.esquerdoTraseiro.marca | string | Será preenchido na marca do campo "Pneu traseiro esquerdo" |
| veiculo.pneus.esquerdoTraseiro.situacao | string | Não utilizado * |
| veiculo.pneus.direitoDianteiro.marca | string | Será preenchido na marca do campo "Pneu dianteiro direito" |
| veiculo.pneus.direitoDianteiro.situacao | string | Não utilizado * |
| veiculo.pneus.direitoTraseiro.marca | string | Será preenchido na marca do campo "Pneu traseiro direito" |
| veiculo.pneus.direitoTraseiro.situacao | string | Não utilizado * |
| veiculo.pneus.estepe.marca | string | Será preenchido na marca do campo "Estepe" |
| veiculo.pneus.estepe.situacao | string | Não utilizado * |
| veiculo.pneus.qtde | string | Não utilizado * |
| veiculo.odometro | string | Preencherá o campo "KM" na aba inicial |
| veiculo.chassi | string | Preencherá o campo "Chassi" na aba inicial |
| veiculo.tipoVeiculo | string | Id do questionário que será iniciado a vistoria OBS: Caso esse campo esteja vazio e o parâmetro "Esta opção fará com que sempre seja perguntado o questionário após encontrar uma placa" esteja desmarcado, ao iniciar a vistoria será selecionado automaticamente o primeiro questionário da lista de questionário |
| veiculo.qtdePneus | string | Não utilizado * |
| veiculo.cor | string | Preencherá o campo "Cor" na aba inicial |