Você já deve saber disso mas, só para alinharmos a terminologia, chamamos de ocorrências quaisquer eventos relevantes que forem observados durante ou ao final de uma operação de transporte.
Dependendo do tipo da ocorrência, ela pode estar associada a um nota fiscal, a um documento de transporte (CTe, minuta), a uma viagem (ou romaneio, ou manifesto), ou a vários desses documentos simultaneamente.
O registro correto das ocorrências é importantíssimo para que possamos ter uma visão detalhada de todo o processo de transporte, bem como para que possam ser tomadas ações ou disparadas informações para outras áreas ou empresas.
Origem dos dados
Na maior parte das vezes, as informações necessárias para o registro de uma ocorrência tem origem "lá na ponta da operação", ou seja, com o motorista ou ajudante que estão efetivamente realizando o transporte das mercadorias.
A partir dali, esses dados podem ser registrados de várias formas, algumas mais eficientes e seguras que outras, sendo as mais comuns:
Em um aplicativo móvel, instalado no celular do motorista;
Em um dispositivo de rastreamento, instalado no veículo;
Em papel, manualmente, na DANFE, DACTE, ou manifesto, para posteriormente serem digitados no sistema da transportadora;
Transmitidos por telefone ou WhatsApp para a filial da transportadora, para lá serem digitados;
etc.
Depois, para chegar até o Gestor Logístico, esses dados podem seguir por vários caminhos. Este artigo discorre sobre as formas que podem ser utilizadas para registrar essas ocorrências, mas aqui vamos focar na maneira que consideramos mais indicada, que é através da API do Gestor Logístico.
Considerações preliminares
Utilizar a API do GL é a forma mais eficiente e segura para realizar a importação dos dados. O processo pode ser totalmente automatizado, os dados podem ser enviados imediatamente após a sua coleta, a comunicação é feita através de canais seguros e criptografados, sem a possibilidade de acessos não autorizados aos dados, e todo o processo pode ser monitorado automaticamente.
Porém, é preciso ter em mente que tudo tem um custo! E apesar de ser o meio mais eficiente, é também o mais complexo para ser implementado. Você vai precisar envolver o time de TI da sua empresa, para que entendam o formato e as particularidades da nossa API, e desenvolvam um aplicativo "sob medida" para fazer o envio.
Além disso, como o processo será totalmente automatizado, e portanto (geralmente) sem nenhuma intervenção humana, esse processo precisa ser suficientemente "inteligente" para se recuperar sozinho de qualquer falha durante o envio. Por exemplo, pode ser que ocorra alguma indisponibilidade temporária da internet, ou mesmo do próprio aplicativo do GL, exatamente no momento que o seu sistema está tentando enviar uma nova ocorrência. Apesar de muito raro, isso pode ocorrer, e essas excessões precisam ser tratadas pelo seu aplicativo, para que ele tente novamente o envio posteriormente, quando todos os componentes da solução estiverem novamente operantes.
Como fazer
Mas então vamos ao que interessa: Como faço para registrar uma ocorrência via API? Vamos a um "passo a passo":
Passo 1: Entendendo o formato da API
Este artigo explica os princípios básicos para utilização da API do GL, como formato dos dados, forma de autenticação, e URLs para acesso. Comece por ele!
Passo 2: Obtendo um usuário e senha para acesso
Obviamente, o acesso à API somente será autorizado se você possuir as "credenciais" que provem que você (ou melhor, neste caso a sua aplicação), possui os direitos necessários para registrar uma ocorrência no sistema. E para isso você vai precisar ter um usuário cadastrado no sistema com os direitos necessários. Se tiver qualquer dúvida em como cadastrar este usuário, basta enviar um e-mail para o nosso time de suporte, ou com o consultor que atende sua empresa, e eles podem fazer isso por você.
Passo 3: Entendendo o serviço
Para cada ocorrência a ser registrada, sua aplicação precisará fazer um POST para o endpoint /ocorrencias, enviando no payload um JSON com todos os dados necessários. O formato do request é o seguinte:
POST /ocorrencias
header: "Authorization": "Basic ..."
header: "Content-Type": "application/json"
{
"codigo": 123,
"descricao": "...",
"instante": "aaaa-mm-ddThh:mm:ss-03:00",
"notas": "...",
"nfs": [
{
"chave": 123,
"emitente": {
"cpfOuCnpj": 123
},
"serie": 123,
"numero": 123
}
],
"dts": [
{
"chave": 123,
"emitente": {
"cpfOuCnpj": 123
},
"serie": 123,
"numero": 123
}
],
"viagem": {
"numero": 123,
"transportador": {
"cpfOuCnpj": 123
},
"veiculo": {
"placa": "..."
}
},
"despesas": [
{
"descricao": "...",
"quantidade": 123,
"valor": 123.45
}
],
"recebedor": {
"nome": "...",
"documento": "..."
},
"imagens": [
{
"descricao": "...",
"url": "...",
"notas": "..."
}
]
}
Descrição dos campos
codigo (obrigatório)
É o identificador da ocorrência, e deve seguir a tabela que foi previamente cadastrada pelo administrador do GL. No momento da implantação da integração, você deve combinar com o administrador quais códigos de ocorrência devem ser enviados para cada situação.
descricao (opcional)
É um texto breve que indica qual foi o evento ou ocorrência. Caso não seja informado, será atribuído o texto padrão cadastrado para o código informado. Por exemplo, para o código de ocorrência 1, a descrição normalmente é Entrega realizada.
instante (obrigatório)
Data e hora em que o evento efetivamente ocorreu. Por exemplo, para uma entrega que foi realizada às 15:34 do dia 18/07/22, este campo deve conter "2022-07-18T15:34:00-03:00".
notas (opcional)
Texto adicional ou observações relacionadas à ocorrência. É um dado meramente informativo, cujo objetivo é complementar a descrição da ocorrência.
nfs (obrigatório, exceto se o campo "dts" for informado)
Lista das notas fiscais às quais a ocorrência está relacionada. Por exemplo, no caso de uma entrega realizada, informar a chave ou número da nota que foi entregue.
Observar que trata-se de um "array", que pode ter uma ou várias notas.
Para cada nota fiscal, deve ser informada a chave OU o emitente/série/número do documento.
dts (obrigatório, exceto se o campo "nfs" for informado)
Caso a ocorrência esteja associada a um Documento de Transporte (CTe, minuta, etc), e não a uma ou mais notas fiscais específicas, você pode informar neste campo a chave OU o emitente/série/número do(s) documento(s) de transporte.
viagem (opcional)
Se necessário, você pode informar neste campo os dados da viagem, como número (da viagem, romaneio, ou manifesto), CNPJ da transportadora (ou agregado), e placa do veículo.
despesas (opcional)
No caso da ocorrência gerar custos adicionais a serem pagos para a transportadora (ou agregado), informar neste campo a lista de despesas, com suas respectivas descrições, quantidades e valores.
recebedor (opcional, e apenas para ocorrências de entrega)
Nome e número do documento da pessoa que recebeu as mercadorias.
imagens (opcional)
Caso existam imagens associadas à ocorrência, tais como comprovantes de entrega, ou fotos de avarias, elas podem ser enviadas neste campo. Podem ser enviados uma descrição da imagem, notas explicativas, e a URL da imagem.
Passo 4: Tratando os dados retornados pelo serviço
O serviço irá retornar um JSON com o ID da ocorrência que foi gerada no GL, para caso se queira manter uma referência no seu sistema aplicativo, mas isso normalmente não é necessário.
O único ponto que sua aplicação deve obrigatoriamente tratar é o código de retorno do processamento, que deve ser sempre 200 (OK). Qualquer valor diferente desse indica que houve um erro no processamento.
Obtendo ajuda
Como dissemos no princípio, este não é um dos procedimentos dos mais fáceis 😬 .
Mas não se deixe intimidar! Com um pouco de paciência, e depois de entendidos os conceitos, não temos dúvidas que você terá sucesso 🥷, e o resultado vai valer a pena.
E lembre-se: Nosso time está à disposição para ajudá-lo a superar qualquer dificuldade, basta nos contatar no e-mail suporte@tecnovia.com.br.