.png){kind=logo}
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 e autenticação
Os endereços dos ambientes de homologação e produção, assim como os dados de empresa e o token de autenticação, devem ser solicitados à central de atendimento pelo e-mail: suportenddcargoteam@nddcargo.com.br.
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 |