Skip to main content
Skip table of contents

Guia de Integrações

Nossa API segue a arquitetura SOAP, utilizando endpoints baseados em recursos para realizar operações CRUD. Todos os dados são transferidos no formato XML para facilidade de uso.

Dados de Ambiente

Homologação

https://homologa.nddcargo.com.br/wsagente/ExchangeMessage.asmx

Produção

http://wsagent.nddcargo.com.br/wsagente/exchangemessage.asmx

Autenticação

Entre em contato com suportenddcargoteam@nddcargo.com.br para obter os dados de empresa e token de autenticação.

Especificação dos métodos do WebService

O nome do WebService do nddCargo é ExchangeMessage. Ele possui uma única operação (Send), onde sempre deverá ser enviado um CrossTalk (Header). No retorno também será retornado um CrossTalk, correspondente ao enviado.

O CrossTalk de envio contém informações que permitirão que seja feito o roteamento das mensagens e definições de parâmetros para a execução dos serviços. Já o CrossTalk de retorno conterá informações correspondentes à solicitação de envio.

Especificação da mensagem de cabeçalho no padrão CrossTalk

A mensagem CrossTalk contém 2 elementos: o cabeçalho (CrossTalk_Header) e o corpo da mensagem (CrossTalk_Body). No cabeçalho são especificados valores que identificam a mensagem (ProcessCode, MessageType, ExchangePattern, Enterprise Id) e valores de controle (DateTime, GUID, Token). No corpo pode ser especificada uma mensagem, parâmetros complementares de uma mensagem de solicitação, valores de status, etc. O corpo pode ainda estar ausente ou vazio. Esta situação ocorrerá nas mensagens onde será solicitado o resultado de um processamento.

No webservice ExchangeMessage estes dois elementos são representados por dois campos: message (header) e rawdata (body).

Abaixo segue a descrição dos campos de um cabeçalho (header ou message) CrossTalk:

Campo

Descrição

Opc

Informações adicionais

ProcessCode

Código numérico determinando qual é o processo ao qual a mensagem pertence.

N

Tipos possíveis:

1000 = Lote OT 

1001 = Alterar OT

1002 = Cancelar OT

1003 = Pagamento realizados

1004 = Gerar GUID

1005 = Encerrar OT

2005 = Pagamento imediato

2006 = Solicitação de impressão

2008 = Consultar de resumo da OT

2013 = Consultar na ANTT

2014 = Consultar Status viagem Via Fácil

2015 = Consultar Recibo viagem Via Fácil

2016 = Consulta de eventos de efetivação

2017 = Confirmação de pagamentos

2018 = Donwload de operação

2019 = Envio de Operação de Vale Pedágio

2021 = Consultar de Operação de Vale Pedágio

2022 = Cancelar de Operação de Vale Pedágio

2023 = Consultar Saldo Contratante

2024 = Consultar Portador Cartão

2025 = Reprocessar Pagamento

2026 = Documentos Adicionais

2027 = Consulta Roteirizador

2029 = Consulta Saldo Cartão

3019 = Consulta do ID de Vale Pedágio

MessageType

Código numérico determinando qual é o tipo de operação que se espera realizar com a mensagem.

N

Tipos possíveis:

100: Insert

ExchangePattern

Determina o padrão de comunicação que será usado.

S

Tipos possíveis:

1: A mensagem é uma requisição. O cliente inicia uma mensagem de requisição a qual o provedor responde com uma mensagem de resposta (Response), ou uma exceção. A resposta pode conter um status (RespCode), que deve ser avaliado para determinar se a troca de mensagem ocorreu como esperado. Se a resposta for uma exceção, então a troca de mensagem falhou e uma nova tentativa pode ser realizada posteriormente

7: A mensagem é uma requisição que será processada de forma assíncrona, onde a resposta será buscada posteriormente. Neste modelo ocorre uma resposta síncrona informando que a mensagem foi aceita para processamento.

8: A mensagem é uma resposta assíncrona. Deve ser usado para os casos de busca do resultado de um processamento

ResponseCode

Código de resposta do processamento, presente apenas nas mensagens de resposta.

S

Tipos possíveis:

0: Default ou indeterminado

200: Processamento realizado com sucesso

202: A mensagem foi aceita e será processada.

400: A mensagem não foi entendida pelo servidor e deve ser modificada antes de ser enviada novamente.

500: Ocorreu uma exceção durante o processamento da requisição. Erro de processamento da solicitação do negócio

501: Ocorreu uma falha não identificada durante o processamento da requisição

600: Falha no processamento

ResponseCodeMessage

Um texto complementar ao Response Code.

S

Exemplo: "A mensagem foi aceita e será processada.”

GUID

Um Global Unique Identifier para que o consumidor possa controlar suas transações. Este mesmo GUID estará presente na mensagem de resposta e deverá ser usado para solicitar o resultado de um processamento.

S

 

EnterpriseID

CNPJ da Contratante que está enviando a mensagem.

N

 

ContentType

Especificação do tipo de dado que a mensagem está formatada.

S

Deve ser sempre “text/xml”.

ContentEncoding

Especificação do encoding em que a mensagem está formatada.

S

Deve ser sempre “utf-8”.

Observações

  • A codificação do XML Header deve ser utf-16 e do XML Body utf-8;

  • Todas as chamadas, ao WebService são síncronas. Entretanto alguns processos são assíncronos, como por exemplo envio de Operação de Pagamento e Cancelamento. Ou seja, para estes processos, deve-se enviar uma mensagem solicitando o processamento e posteriormente deve-se enviar uma nova mensagem, solicitando o resultado do processamento;

  • Ao fazer o envio de uma Operação de Pagamento e o Web Service retornar a mensagem indicando que a solicitação foi aceita e será processada, não significa necessariamente que a Operação foi cadastrada com sucesso no sistema. Existem várias validações após a solicitação de processamento que podem impedir que uma Operação de Pagamento seja declarada com sucesso no nddCargo. A mensagem apenas indica que o lote foi recebido com sucesso, e que um processamento será feito.

Legenda

As tabelas de especificação dos arquivos possuem as seguintes colunas:

#

identificador do campo na integração

Campo

nome do campo no XML

Elem.

indicação se é um Atributo (A), um Elemento (E) ou uma tag Raiz (Raiz)

Pai

Indicação do elemento a qual pertence

Tipo

Tipo de dado do elemento, podendo ser Data (D), String (S) ou Numérico (N)

Ocor.

Ocorrência do elemento, sendo:

1 = Deve existir uma única vez

1 – X = Deve existir ao menos uma vez e, caso necessário, poderá ser repetido até X vezes

1 – N = Deve existir ao menos uma vez e, caso necessário, poderá ser repetido tantas vezes for necessário

2 – N = Deve ser indicado ao menos duas vezes e, caso necessário, poderá ser repetido tantas vezes for necessário

0 – 1 = Não é obrigatória a existência

0 – N = Não é obrigatória a existência. Nos casos em que o elemento existir, poderá ser repetido tantas vezes for necessário

Tam.

Tamanho total do elemento

Dec.

Indicação de casas decimais para campos numéricos

Observação

Observações sobre o preenchimento do elemento e valores possíveis

Próximos Passos

Gerar GUID

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.