Integração de Abastecimento - TicketLog, Shell Expers e TruckPag


Este documento descreve o passo a passo para integração de solicitação de crédito de abastecimento utilizando a estrutura atual da integração de viagem (viagem/integrar) com suporte aos fornecedores TicketLog e Shell Expers.


Visão Geral

A funcionalidade de abastecimento utiliza a estrutura existente da API de viagem, adicionando campos específicos para gerenciar créditos de combustível com os fornecedores: - TicketLog (Fornecedor = 0) - Shell Expers (Fornecedor = 1)


Regras de Negócio

Solicitação de Crédito

  • Utiliza parcelas novas (IdViagemEvento = NULL)
  • TipoEvento = 5 (ABASTECIMENTO)
  • Status = 2 (Baixado) para realizar o crédito
  • HabilitarPagamentoCartao = false (sempre)
  • O processo comprará o crédito no fornecedor, não fará pagamento PIX

Placa do Veículo

  • A placa enviada para TicketLog ou Shell Expers será o campo "Placa" do JSON da Viagem


Estrutura de Dados

Campos Principais - ViagemEventos

Campo Descrição Valor para Abastecimento
IdViagemEvento ID do evento da viagem NULL para parcelas novas
ValorPagamento Valor do pagamento Valor do crédito para TicketLog/Shell Expers
Status Status do evento 2 = Solicitar crédito
TipoEvento Tipo de parcela 5 = ABASTECIMENTO
Instrucao Informação adicional "Compra Crédito Abastecimento"
HabilitarPagamentoCartao Habilitar pagamento cartão false (sempre)
NumeroControle Documento controle Documento de controle

Estrutura DadosAbastecimento

Campo Descrição Obrigatório Tipo
CodigoCredito Código do crédito na TicketLog/Shell Expers Não String
CodigoCliente Código do cliente (obtido automaticamente do cadastro de empresa) Não String
CodigoProduto Código do produto (deve ser enviado pelo TMS) Sim String
numerocartao Número do cartão na TicketLog/Shell Expers Não String
DataValidade Data de validade (formato yyyy-MM-dd) Não Date
DataLiberacao Data de liberação (formato yyyy-MM-dd) Não Date
Fornecedor 0 = TicketLog (padrão); 1 = Shell Expers Não* Integer

Observação: *Fornecedor é opcional. Se não informado, assume TicketLog (0). Enviar 1 apenas para Shell Expers.


Exemplos de Implementação

V1 - Solicitação de Crédito TicketLog

Endpoint: POST /Viagem/Integrar

{
  "Token": "token-autenticacao",
  "CNPJAplicacao": "12345678000195",
  "CNPJEmpresa": "98765432000198",
  "CPFCNPJClienteDestino": "11111111000111",
  "CPFCNPJClienteOrigem": "22222222000222",
  "CPFCNPJProprietario": "33333333000333",
  "CPFMotorista": "12345678901",
  "Placa": "ABC1234",
  "NumeroControle": "CTRL001",
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Usuario Sistema",
  "ViagemEventos": [
    {
      "TipoEvento": 5,
      "ValorPagamento": 500.00,
      "Status": 2,
      "HabilitarPagamentoCartao": false,
      "NumeroControle": "DOC123456",
      "Instrucao": "Compra Crédito Abastecimento",
      "DadosAbastecimento": {
      "CodigoCredito": "",
      "CodigoProduto": "DIESEL_S10",
      "NumeroCartaoOrigem": "1234567890123456", -- Informar em caso de pré-pago
      "numerocartao": "1234567890123456",
      "DataValidade": "2024-12-31",
      "DataLiberacao": "2024-01-15"
    }
  ]
}

V1 - Solicitação de Crédito Shell Expers

Endpoint: POST /Viagem/Integrar

{
  "Token": "token-autenticacao",
  "CNPJAplicacao": "12345678000195",
  "CNPJEmpresa": "98765432000198",
  "CPFCNPJClienteDestino": "11111111000111",
  "CPFCNPJClienteOrigem": "22222222000222",
  "CPFCNPJProprietario": "33333333000333",
  "CPFMotorista": "12345678901",
  "Placa": "ABC1234",
  "NumeroControle": "CTRL001",
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Usuario Sistema",
  "ViagemEventos": [
    {
      "TipoEvento": 5,
      "ValorPagamento": 500.00,
      "Status": 2,
      "HabilitarPagamentoCartao": false,
      "NumeroControle": "DOC123456",
      "Instrucao": "Compra Crédito Abastecimento",
      "DadosAbastecimento": {
        "CodigoCredito": "",
        "CodigoProduto": "DIESEL_S10",
        "NumeroCartaoOrigem": "1234567890123456", -- Informar em caso de pré-pago
        "numerocartao": "1234567890123456",
        "DataValidade": "2024-12-31",
        "DataLiberacao": "2024-01-15"
      }
    }
  ]
}

V2 - Solicitação de Crédito

Endpoint: POST /ViagemV2/Integrar

{
  "Token": "token-autenticacao",
  "CnpjAplicacao": "12345678000195",
  "CNPJEmpresa": "98765432000198",
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Usuario Sistema",
  "DadosViagem": {
    "DadosIniciais": {
      "NumeroControle": "CTRL001",
      "DeclaracaoCiot": 0
    },
    "Documentos": {
      "MotoristaDocumento": "12345678901",
      "ProprietarioDocumento": "33333333000333"
    },
    "Veiculo": {
      "Placa": "ABC1234"
    },
    "ViagemEventos": [
      {
        "IdViagemEvento": null,
        "ValorPagamento": 500.00,
        "Status": 2,
        "TipoEvento": 5,
        "Instrucao": "Compra Crédito Abastecimento",
        "HabilitarPagamentoCartao": false,
        "NumeroControle": "DOC123456",
        "DadosAbastecimento": {
          "CodigoCredito": "",
          "CodigoProduto": "DIESEL_S10",
          "NumeroCartaoOrigem": "1234567890123456", -- Informar em caso de pré-pago
          "numerocartao": "1234567890123456",
          "DataValidade": "2024-12-31",
          "DataLiberacao": "2024-01-15"
        }
      }
    ]
  }
}

Endpoint: POST /Viagem/Integrar ou POST /ViagemV2/Integrar

{
  "IdViagem": 12345,
  "CNPJAplicacao": "12345678000195",
  "Token": "token-autenticacao",
  "CNPJEmpresa": "98765432000198",
  "ViagemEventos": [
    {
      "IdViagemEvento": 67890,
      "Status": 3,
      "NumeroControle": "CREDITO123",
      "DadosAbastecimento": {
        "CodigoProduto": "DIESEL_S10"
      }
    }
  ]
}


Fluxo de Integração

1. Solicitação de Crédito

  1. Preparar dados da viagem com TipoEvento = 5
  2. Definir Status = 2 (Baixado)
  3. Preencher DadosAbastecimento com informações do fornecedor
  4. Enviar IdViagemEvento = null para parcelas novas
  5. Definir HabilitarPagamentoCartao = false
  6. Chamar endpoint de integração de viagem


Observações Importantes

  • CodigoProduto: Deve ser enviado pelo TMS conforme especificação do fornecedor
  • CodigoCliente: Será obtido automaticamente do cadastro de empresa
  • Placa: Enviada automaticamente baseada no campo "Placa" da viagem
  • Datas: Usar formato yyyy-MM-dd
  • Duplicação: Não reenviar parcelas de abastecimento em retificações
  • Fornecedores: 0 = TicketLog (padrão); 1 = Shell Expers (opcional)


Códigos de Status

Status Descrição Uso
0 Aberto/Pendente Parcela criada mas não processada
1 Bloqueado Parcela bloqueada
2 Baixado Solicitar crédito de abastecimento
5 Agendado Parcela agendada


Fornecedores Suportados

Código Fornecedor Descrição
0 TicketLog Fornecedor TicketLog
1 Shell Expers Fornecedor Shell Expers


Resposta da API

Sucesso - Solicitação de Crédito

{
  "Sucesso": true,
  "Mensagem": "Viagem integrada com sucesso",
  "Objeto": {
    "IdViagem": 12345,
    "NumeroDocumento": "DOC123456",
    "Eventos": [
      {
        "IdViagemEvento": 67890,
        "NumeroControle": "DOC123456",
        "Token": "evento-token-123",
        "TipoEventoViagem": 5,
        "OperacaoCartao": {
          "Status": 1,
          "Mensagem": "Crédito solicitado com sucesso"
        }
      }
    ]
  }
}


Tratamento de Erros

Erros Comuns

Erro Causa Solução
"CodigoProduto obrigatório" Campo CodigoProduto não informado Informar código do produto conforme fornecedor
"Fornecedor inválido" Valor de Fornecedor diferente de 0 ou 1 Usar 0 para TicketLog ou 1 para Shell Expers
"TipoEvento inválido" TipoEvento diferente de 5 para abastecimento Usar TipoEvento = 5

Exemplo de Resposta com Erro

{
  "Sucesso": false,
  "Mensagem": "Erro na validação dos dados",
  "Faults": [
    {
      "Type": 1,
      "Code": "ABAST001",
      "Message": "CodigoProduto é obrigatório para abastecimento"
    }
  ]
}


Integração de Abastecimento – TruckPag

A funcionalidade de abastecimento TruckPag utiliza o mesmo fluxo de Abastecimento já existente (TipoEvento = 5), porém com regras específicas.

Regras de Negócio TruckPag

  • TipoEvento: 5 (ABASTECIMENTO)
  • Status da parcela: sempre 2 (Baixado) para solicitar a carga
  • HabilitarPagamentoTruckPag: obrigatório = true
  • Não utiliza pagamento PIX
  • Não utiliza DadosAbastecimento
  • Não envia CodigoProduto
  • IdViagemEvento:
  • null → para novo abastecimento
  • {idDaParcela} → para atualizar/cancelar

Exemplo de Solicitação de Crédito – TruckPag

{
  "Token": "token-autenticacao",
  "CNPJAplicacao": "12345678000195",
  "CNPJEmpresa": "98765432000198",
  "Placa": "ABC1234",
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Usuario Sistema",
  "ViagemEventos": [
    {
      "TipoEvento": 5,
      "IdViagemEvento": null,
      "ValorPagamento": 1.00,
      "Status": 2,
      "HabilitarPagamentoTruckPag": true,
      "NumeroControle": "TRUCKPAG001"
    }
  ]
}


Cancelamento de Abastecimento – TruckPag

O cancelamento da carga TruckPag segue exatamente o mesmo fluxo de cancelamento de um evento comum.

Regras do Cancelamento

  • Enviar o IdViagemEvento da parcela a ser cancelada
  • Atualizar Status para 3 = Cancelado
  • Não enviar novamente HabilitarPagamentoTruckPag
  • Não reenviar ValorPagamento
  • Não reenviar TipoEvento
  • O campo NumeroControle pode ser enviado apenas para controle interno do TMS

Exemplo de Cancelamento (V1 ou V2)

{
  "IdViagem": 12345,
  "CNPJAplicacao": "12345678000195",
  "Token": "token-autenticacao",
  "CNPJEmpresa": "98765432000198",
  "ViagemEventos": [
    {
      "IdViagemEvento": 65865,
      "Status": 3,
      "NumeroControle": "CANCELAR_TRUCKPAG_001"
    }
  ]
}


Integração de Abastecimento - TruckPag

A funcionalidade de abastecimento TruckPag utiliza o mesmo fluxo de abastecimento já existente da integração de viagem, com TipoEvento = 5, porém com regras específicas para a compra/carga de abastecimento TruckPag.

Regras de Negócio TruckPag

  • TipoEvento = 5 (ABASTECIMENTO)
  • Status da parcela = 2 (Baixado) para solicitar a compra/carga do abastecimento
  • HabilitarPagamentoTruckPag = true (obrigatório)
  • Não utiliza pagamento PIX
  • Não utiliza DadosAbastecimento
  • Não envia CodigoProduto
  • IdViagemEvento:
  • null para novo abastecimento
  • {idDaParcela} para atualizar ou cancelar uma parcela existente

Campos Principais - TruckPag

Campo Descrição Valor para TruckPag
IdViagemEvento ID do evento da viagem null para novo abastecimento; ID da parcela para cancelamento/atualização
ValorPagamento Valor da compra/carga de abastecimento Valor a ser carregado/comprado na TruckPag
Status Status do evento 2 = Solicitar compra/carga; 3 = Cancelar
TipoEvento Tipo de parcela 5 = ABASTECIMENTO
HabilitarPagamentoTruckPag Habilita a compra/carga TruckPag true para solicitação de novo abastecimento
NumeroControle Documento de controle Controle interno do TMS
Placa Placa do veículo Enviada no nível da viagem

Fluxo de Compra do Abastecimento - TruckPag

  1. Preparar os dados da viagem com a placa do veículo.
  2. Criar uma nova parcela em ViagemEventos com IdViagemEvento = null.
  3. Definir TipoEvento = 5.
  4. Definir Status = 2.
  5. Informar ValorPagamento com o valor da compra/carga de abastecimento.
  6. Informar HabilitarPagamentoTruckPag = true.
  7. Não enviar DadosAbastecimento.
  8. Não enviar CodigoProduto.
  9. Chamar o endpoint de integração de viagem.

Exemplo de Solicitação de Compra/Carga - TruckPag

Endpoint: POST /Viagem/Integrar

{
  "Token": "token-autenticacao",
  "CNPJAplicacao": "12345678000195",
  "CNPJEmpresa": "98765432000198",
  "Placa": "ABC1234",
  "DocumentoUsuarioAudit": "12345678901",
  "NomeUsuarioAudit": "Usuario Sistema",
  "ViagemEventos": [
    {
      "TipoEvento": 5,
      "IdViagemEvento": null,
      "ValorPagamento": 1.00,
      "Status": 2,
      "HabilitarPagamentoTruckPag": true,
      "NumeroControle": "TRUCKPAG001"
    }
  ]
}

Cancelamento de Abastecimento - TruckPag

O cancelamento da carga TruckPag segue o mesmo fluxo de cancelamento de um evento comum.

Regras do Cancelamento

  • Enviar o IdViagemEvento da parcela a ser cancelada.
  • Atualizar Status para 3 = Cancelado.
  • Não enviar novamente HabilitarPagamentoTruckPag.
  • Não reenviar ValorPagamento.
  • Não reenviar TipoEvento.
  • O campo NumeroControle pode ser enviado apenas para controle interno do TMS.

Fluxo de Cancelamento - TruckPag

  1. Obter o IdViagemEvento da parcela TruckPag a ser cancelada.
  2. Preparar a requisição com Status = 3.
  3. Não reenviar os campos de solicitação da compra/carga.
  4. Chamar o endpoint de integração de viagem.

Exemplo de Cancelamento - TruckPag (V1 ou V2)

Endpoint: POST /Viagem/Integrar ou POST /ViagemV2/Integrar

{
  "IdViagem": 12345,
  "CNPJAplicacao": "12345678000195",
  "Token": "token-autenticacao",
  "CNPJEmpresa": "98765432000198",
  "ViagemEventos": [
    {
      "IdViagemEvento": 65865,
      "Status": 3,
      "NumeroControle": "CANCELAR_TRUCKPAG_001"
    }
  ]
}

Observações Importantes - TruckPag

  • A integração TruckPag não utiliza o objeto DadosAbastecimento.
  • A integração TruckPag não utiliza o campo CodigoProduto.
  • A integração TruckPag não utiliza o campo Fornecedor dos fornecedores TicketLog/Shell Expers.
  • A compra/carga TruckPag não realiza pagamento PIX.
  • Para novo abastecimento TruckPag, HabilitarPagamentoTruckPag deve ser enviado como true.
  • Para cancelamento, enviar somente o IdViagemEvento, Status = 3 e, opcionalmente, NumeroControle.