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 |