Agora no Bluesoft ERP, é possível realizar a manutenção do cadastro de motoristas utilizados na roteirização do TMS por meio de API pública.

Objetivo

A funcionalidade tem como objetivo permitir a sincronização automática dos motoristas entre sistemas externos e o Bluesoft ERP, reduzindo a dependência de intervenção manual no cadastro de pessoas, diminuindo riscos de inconsistências cadastrais e mantendo os motoristas disponíveis para os processos de roteirização do TMS.

Como irá funcionar?

Consulta de Motoristas

Endpoint: GET /api/tms/motoristas

Permite consultar motoristas vinculados ao tipo MOTORISTA.

Filtros disponíveis:

  1. motoristaKey
  2. cpfCnpj
  3. nome
  4. currentPage
  5. pageSize

Regras da consulta:

  • O filtro nome utiliza correspondência parcial.
  • A consulta retorna motoristas que possuem vínculo MOTORISTA.
  • O retorno contém os dados cadastrais e os dados de motorista compatíveis com o contrato público da API.

Campos retornados:

  • motoristaKey
  • nome
  • cpfCnpj
  • cnh
  • registroCnh
  • categoriaCnh
  • dataVencimentoCnh
  • tipoValorFrete
  • valorFrete

Cadastro de Motorista

Endpoint: POST /api/tms/motoristas

Permite cadastrar uma nova pessoa e associá-la como motorista do TMS.

Regras do cadastro:

  1. O POST deve ser utilizado somente para criação de nova pessoa e novo motorista.
  2. O campo motoristaKey não deve ser informado na criação, pois será gerado pelo ERP.
  3. Os campos obrigatórios são:
    • nome
    • cpfCnpj
    • cnh
    • registroCnh
    • categoriaCnh
    • dataVencimentoCnh
    • tipoValorFrete
    • valorFrete
    • ao menos um endereço com tipoDeEndereco igual a FATURAMENTO
  4. Os campos nomeAbreviado, sexo, estadoCivil e dataNascimento são opcionais.
  5. Quando não houver endereço de COBRANCA, o endereço de FATURAMENTO será copiado para cobrança.
  6. Quando o endereço de COBRANCA for informado, ele será preservado.
  7. Ao final da operação, o ERP retorna o motoristaKey gerado.
  8. O status esperado para cadastro com sucesso é 201 Created.

Exemplo de JSON válido para cadastro:

{
  "cpfCnpj": "12345678901",
  "nome": "Joao da Silva",
  "nomeAbreviado": "Joao Silva",
  "sexo": "M",
  "estadoCivil": "SOLTEIRO",
  "dataNascimento": "13/10/1996",
  "enderecos": [
    {
      "tipoDeEndereco": "FATURAMENTO",
      "rua": "Rua das Flores",
      "numero": "100",
      "cep": "01001000",
      "cidade": "Sao Paulo",
      "uf": "SP",
      "bairro": "Centro",
      "complemento": "Sala 1",
      "codigoIbgeCidade": "3550308"
    }
  ],
  "cnh": 123456789,
  "registroCnh": 987654321,
  "categoriaCnh": "AB",
  "dataVencimentoCnh": "31/12/2028",
  "tipoValorFrete": "FIXO",
  "valorFrete": 150.00
}

Atualização ou Associação de Motorista

Endpoint: PUT /api/tms/motoristas

Permite atualizar os dados de um motorista existente ou associar uma pessoa já cadastrada como motorista.

A atualização pode ser realizada por:

  1. motoristaKey
  2. cpfCnpj

Regras da atualização:

  • Deve ser informado apenas um identificador por requisição: motoristaKey ou cpfCnpj.
  • O envio conjunto de motoristaKey e cpfCnpj será rejeitado.
  • O PUT não cria nova pessoa.
  • Quando informado motoristaKey, o ERP atualiza os dados do motorista existente.
  • Quando informado cpfCnpj de uma pessoa existente que ainda não possui vínculo MOTORISTA, o ERP cria o vínculo de motorista.
  • Quando informado cpfCnpj de uma pessoa que já possui vínculo MOTORISTA, o ERP atualiza os dados do motorista.
  • Campos não informados no PUT preservam o valor atual do motorista.
  • O PUT não atualiza os dados cadastrais da pessoa existente.
  • O campo motoristaKey é imutável.
  • O status esperado é 200 OK quando houver apenas atualização.
  • O status esperado é 201 Created quando o PUT criar um novo vínculo de motorista.

Exemplo de JSON válido para atualização por motoristaKey:

{
  "motoristaKey": 12345,
  "cnh": 123456789,
  "registroCnh": 987654321,
  "categoriaCnh": "AB",
  "dataVencimentoCnh": "31/12/2028",
  "tipoValorFrete": "FIXO",
  "valorFrete": 150.00
}

Exemplo de JSON válido para atualização ou associação por cpfCnpj:

{
  "cpfCnpj": "12345678901",
  "registroCnh": 987654321,
  "categoriaCnh": "AB",
  "dataVencimentoCnh": "31/12/2028",
  "tipoValorFrete": "FIXO",
  "valorFrete": 150.00
}

Inativação de Motorista

Endpoint: DELETE /api/tms/motoristas/{motoristaKey}

Permite inativar o vínculo de motorista sem inativar a pessoa.

Regras da inativação:

  1. A inativação remove apenas o vínculo/tipo MOTORISTA.
  2. A pessoa permanece ativa no ERP.
  3. Vínculos e históricos já existentes são preservados.
  4. O motorista inativo deixa de estar disponível para novos vínculos com veículos.
  5. O status esperado para inativação com sucesso é 204 No Content.

Permissões

Para utilização da API, são consideradas as seguintes permissões:

  • Consultar: 4659
  • Incluir: 4660
  • Atualizar: 4661
  • Inativar: 4662

Para conhecer mais sobre como é a utilização dessa ferramenta, clique aqui.

Para saber mais sobre a utilização das APIs do ERP, clique aqui.

Disponível a partir da versão r371.01