Pular para conteúdo

WS012 - Enviar Rota para Comprovei com Documentos Pré Cadastrados

Clique aqui para ver histórico de versões
Data de atualização Data de publicação do serviço Alterações
15/04/2021 15/04/2021 Criação da v3

Objetivo

Esta integração tem por objetivo permitir o envio de uma rota para que seja rastreada pela Comprovei©, utilizando somente as chaves dos documentos pré cadastrados no sistema.

Descrição do método
Método uploadRouteUsingDocumentKey
Versão 3
WSDL principal https://soap.comprovei.com.br/importQueue/v3/index.php?wsdl
WSDL de contingência https://soapcontingencia.comprovei.com.br/importQueue/v3/index.php?wsdl
XSD https://soap.comprovei.com.br/importQueue/v3/schemas/validation/WS012.xsd

Importante

  1. A conexão ao nosso serviço deve ser feito ao nosso servidor principal, porém sugerimos fortemente que também seja disponibilizada uma conexão ao nosso servidor de contingência, como garantia de disponibilidade dos nossos serviços. O servidor de contingência só é ligado em situações de indisponibilidade do nosso servidor principal. Tornar parametrizável a url de conexão também é uma boa prática;
  2. Nossas conexões são seguras utilizando o protocolo SSL. Por questão de segurança nossos certificados são alterados constantemente e sem aviso prévio. Portanto é recomendável que não desenvolvam as integrações baseadas em um certificado fixo.
  3. Constantemente (e sem aviso prévio) adicionamos novos campos e estruturas tanto nas requisições quanto nas respostas dos nossos webservices. Quem for utilizar nossos webservices deve implementar de tal maneira que os programas que consomem estes webservices não deixem de funcionar quando houver as alterações de campos mencionadas.

Versão

Você está acessando a versão 3 do nosso sistema de integração. Caso deseje consultar a versão anterior, clique aqui.

Características

  • As chamadas serão realizadas via SOAP sobre HTTPS;
  • A origem do chamado do Web Service será o sistema do cliente;

Importante

Os documentos devem estar previamente cadastrados na Comprovei©, utilizando o WS013 ou o WS015, caso contrário a rota será totalmente rejeitada.

Importante

O usuário deste Web Service deve armazenar o protocolo gerado na resposta. Chamados de suporte referentes a esta integração irão necessitar deste protocolo.

Autenticação

  • As chamadas terão autenticação a nível de mensagem (SOAP Header);
  • Solicite o usuario / senha ao administrador da conta.

Request

A requisição para o nosso Web Service é composta da seguinte forma:

Dentro da TAG <Credenciais>:

TAG Tipo Descrição
Usuario string Usuario para autenticação.
Senha string Senha do usuário para autenticação

Body

Dentro da TAG <uploadRouteUsingDocumentKey>:

TAG Tipo Descrição
Rotas root Raiz do xml e composto por Rota.
nomeArquivo string Nome do arquivo enviado, com a extensão. Exemplo: rota.xml.

Exemplo de Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Header>
        <Credenciais xmlns="WebServiceComprovei">
            <Usuario>usuario</Usuario>
            <Senha>teste</Senha>
        </Credenciais>
    </Header>
    <Body>
        <uploadRouteUsingDocumentKey xmlns="WebServiceComprovei:uploadRouteUsingDocumentKey">
            <Rotas xmlns="WebServiceComprovei:WS012">
                <Rota numero="String">
                    <rotadestino>String</rotadestino>
                    <rotanome>String</rotanome>
                    <Data>String</Data>
                    <Regiao>String</Regiao>
                    <Transportadora>
                        <Codigo>String</Codigo>
                        <Razao>String</Razao>
                    </Transportadora>
                    <Motorista>
                        <Usuario>String</Usuario>
                        <PlacaVeiculo>String</PlacaVeiculo>
                        <TipoVeiculo>String</TipoVeiculo>
                        <Nome>String</Nome>
                        <Telefone>String</Telefone>
                        <CNH>
                            <Numero>String</Numero>
                            <Vencimento>String</Vencimento>
                        </CNH>
                    </Motorista>
                    <Base>
                        <Origem codigo="String">
                            <Nome>String</Nome>
                            <Rua>String</Rua>
                            <Numero>Int</Numero>
                            <Complemento>String</Complemento>
                            <Bairro>String</Bairro>
                            <Cidade>String</Cidade>
                            <Estado>String</Estado>
                            <CEP>String</CEP>
                            <Pais>String</Pais>
                            <Contato>String</Contato>
                            <Email>String</Email>
                            <Telefone>String</Telefone>
                            <Cnpj>String</Cnpj>
                            <CnpjMatriz>String<CnpjMatriz>
                            <TipoMatriz>String ("courier" ou "shipper")</TipoMatriz>
                            <CodigoIBGE>String</CodigoIBGE>
                            <Posicao>
                                <Latitude>String</Latitude>
                                <Longitude>String</Longitude>
                            </Posicao>
                        </Origem>
                        <Destino codigo="String">
                            <Nome>String</Nome>
                            <Rua>String</Rua>
                            <Numero>Int</Numero>
                            <Complemento>String</Complemento>
                            <Bairro>String</Bairro>
                            <Cidade>String</Cidade>
                            <Estado>String</Estado>
                            <CEP>String</CEP>
                            <Pais>String</Pais>
                            <Contato>String</Contato>
                            <Email>String</Email>
                            <Telefone>String</Telefone>
                            <Cnpj>String</Cnpj>
                            <CnpjMatriz>String</CnpjMatriz>
                            <TipoMatriz>String ("courier" e "shipper")</TipoMatriz>
                            <CodigoIBGE>String</CodigoIBGE>
                            <Posicao>
                                <Latitude>String</Latitude>
                                <Longitude>String</Longitude>
                            </Posicao>
                        </Destino>
                    </Base>
                    <limites>
                        <inicio>String</inicio>
                        <fim>String</fim>
                    </limites>
                    <TipoRota>String ("D", "T", "P", "R")</TipoRota>
                    <TipoMaterial>String</TipoMaterial>
                    <Fornecimento>String</Fornecimento>
                    <TipoFrete>String</TipoFrete>
                    <Modal>String</Modal>
                    <CamposLivres>
                        <CampoLivre1>String</CampoLivre1>
                        <CampoLivre2>String</CampoLivre2>
                        <CampoLivre3>String</CampoLivre3>
                        <CampoLivre4>String</CampoLivre4>
                        <CampoLivre5>String</CampoLivre5>
                    </CamposLivres>
                    <Paradas>
                        <Parada numero="String">
                            <Documento>
                                <ChaveNota>String</ChaveNota>
                                <Agendamento>String</Agendamento>
                                <Itinerario>
                                    <ChaveUnica>String</Chaveunica>
                                    <Codigo>String</Codigo>
                                    <Descricao>String</Descricao>
                                    <CodigoDeBarras>String</CodigoDeBarras>
                                    <Data>String</Data>
                                    <Turno>String</Turno>
                                    <Prioridade>String</Prioridade>
                                    <Tipo>String</Tipo>
                                    <PontoTransbordo1>String</PontoTransbordo1>
                                    <CnpjTransportador1>String</CnpjTransportador1>
                                    <NomeTransportador1>String</NomeTransportador1>
                                    <Filial>String</Filial>
                                </Itinerario>
                            </Documento>
                        </Parada>
                    </Paradas>
                </Rota>
            </Rotas>
            <nomeArquivo>String</nomeArquivo>
        </uploadRouteUsingDocumentKey>
    </Body>
</Envelope>

Response

Nosso Web Service responde para você da seguinte forma:

TAG Tipo Descrição
status string Mensagem de sucesso ou de erro para a chamada do método.
protocolo string Protocolo para consultar a evolução do pedido de importação.

Protocolo

Quando um arquivo é aceito no nosso sistema, um protocolo é gerado para que o processo de importação seja acompanhado. Isso pode ser feito utilizando o método WS501.

Exemplo de Response

<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:WebServiceComprovei" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
      <ns1:uploadRouteUsingDocumentKeyResponse>
         <status xsi:type="xsd:string">Arquivo adicionado para a fila de importação!</status>
         <protocolo xsi:type="xsd:string">2017022258add9af06990</protocolo>
      </ns1:uploadRouteUsingDocumentKeyResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Nosso XML de Rota

Nosso XML para importar uma rota é composto pelas seguintes TAGs:

TAG Tipo Obrigatório Descrição
Rotas root Sim Raiz do xml e composto por Rota.

Rota

TAG Tipo Obrigatório Descrição
rotadestino string Não Indicação do destino ou roteiro da rota (limitado a 30 caracteres).
rotanome string Não Indicação do nome da rota.
Data string Sim Data de inicio da operação da rota. Obrigatório o formato AAAAMMDD.
Regiao string Não Região da rota.
Transportadora element Sim Elemento inicializador da estrutura que contêm informações sobre a Transportadora que executará a rota.
Motorista element Sim Elemento inicializador da estrutura que contêm informações sobre o Motorista que executará a rota.
Base element Não Elemento inicializador da estrutura que contêm informações sobre a Base de origem e destino da rota.
limites element Não Elemento inicializador da estrutura que contêm informações as datas e horários Limites de início e fim da rota.
TipoRota string Não Tipo da rota enviada. Valores permitidos:
- D (Distribuição)
- T (Transbordo)
- P (Praça)
- R (Retorno)
TipoMaterial string Não Tipo do material da rota.
Fornecimento string Não Código de fornecimento da rota.
TipoFrete string Não Tipo do frete contratado para a rota.
Modal string Não Modal de transporte contratado para o documento.
CamposLivres element Não Estes campos não são replicados. CamposLivres
Paradas element Sim Elemento inicializador da estrutura que contêm informações sobre todas as Paradas que serão feitas pelo motorista.
Atributo Tipo Obrigatório Descrição
numero string Sim Atributo de Rota. Corresponde ao número da rota no sistema.

Transportadora

Indicador de inicio da estrutura Transportadora. Uma rota pode conter uma única transportadora.

TAG Tipo Obrigatório Descrição
Codigo string Sim Código da transportadora. Normalmente é o CNPJ. Enviar somente números.
Razao string Sim  Nome da transportadora. Pode-se utilizar um nome curto (nome fantasia).

Caso não possua essas informações, os campos devem ser enviados sem conteúdo (vazios).

Motorista

Indicador de inicio da estrutura Motorista. Uma rota pode conter um único motorista.

TAG Tipo Obrigatório Descrição
Usuario string Sim Código do motorista cadastrado no Comprovei.
PlacaVeiculo string Sim Placa do veículo no formato: AAA9999 (sem traço ou espaço).
TipoVeiculo string Não Tipo do veículo que será utilizado na realização da rota.
Nome string Não Nome do motorista. Este campo será utilizado somente quando o cadastro automático do motorista for necessário!.
Telefone string Não Telefone do motorista, no formato DDDNNNNNNNNN. Este campo será utilizado somente quando o cadastro automático do motorista for necessário!.
CNH element Não CNH do motorista. Este elemento será utilizado somente quando o cadastro automático do motorista for necessário!.

Caso não possua essas informações, os campos devem ser enviados sem conteúdo (vazios) e a rota ser associada a um motorista manualmente.

O elemento CNH é composto da seguinte forma:

TAG Tipo Obrigatório Descrição
Numero string * Número da CNH do motorista.
Vencimento string * Data de vencimento da CNH do motorista, no formato AAAAMMDD.

*

Os campos são obrigatórios caso queira informar a CNH do motorista.

Base

Indicador de inicio da estrutura das bases origem e destino. Essas informações são opcionais e devem ser necessariamente preenchidas nos casos de utilização da roteirização.

TAG Tipo Obrigatório Descrição
Origem element * Local de início da rota.
Destino element * Local de finalização da rota.

Origem e Destino são compostos da seguinte forma:

TAG Tipo Obrigatório Descrição
Nome string * Nome de cadastro da base.
Rua string *  Logradouro da base de origem (Rua, Avenida, Praça,etc).
Numero integer * Número da base.
Complemento string * Complemento do endereço da base.
Bairro string * Bairro da base.
Cidade string * Cidade da base.
Estado string * UF da base (Por exemplo: SP, MG).
CEP string * CEP (somente números, sem traço ou espaços) da base.
Pais string * País da base, em alpha-2 (BR), alpha-3 (BRA) ou por extenso (Brasil). Veja a lista aqui.
Contato string Não Nome da pessoa responsável pela base para entrar em contato.
Email string Não Email do responsável da base para entrar em contato.
Telefone string Não Telefone do responsável da base para entrar em contato, no formato DDDNNNNNNNNN.
Cnpj string Não CNPJ da base, utilizando somente números.
CnpjMatriz string Não Caso a base seja filial ou associada à uma transportadora/embarcadora com CNPJ diferente, o CNPJ da associada em questão deve ser informada, utilizando somente números.
TipoMatriz string Não Se for o caso citado acima, informar o tipo da matriz. Valores permitidos:
- courier (Transportadora)
- shipper (Embarcador).
CodigoIBGE string Não Código identificador do município.
Posicao element Não Elemento para envio de posição da base.
Atributo Tipo Obrigatório Descrição
codigo string * Código de identificação da base (Ideal é que seja único).
Posição da Base

Elemento para o envio da localização da base.

TAG Tipo Obrigatório Descrição
Latitude decimal * Latitude da base, em decimal. Ex.: -23.5489
Longitude decimal * Longitude da base, em decimal. Ex.: 46.6388

*

Caso queira enviar o local de origem e destino final da rota, todas as TAGs que compõem esses elementos passam a ser obrigatórias.

Limites

TAG Tipo Obrigatório Descrição
inicio string Não Data/Hora limite para início da rota. Formato: AAAAMMDD HHMM .
fim string Não Data/Hora limite para fim da rota. Formato: AAAAMMDD HHMM .

CamposLivres

TAG Tipo Obrigatório Descrição
CampoLivre1 string Não Campo Livre
CampoLivre2 string Não Campo Livre
CampoLivre3 string Não Campo Livre
CampoLivre4 string Não Campo Livre
CampoLivre5 string Não Campo Livre

Paradas

Elemento responsável por agrupar todos os elementos Parada da rota.

TAG Tipo Obrigatório Descrição
Paradas element Sim Indicador de início da estrutura de paradas. Uma rota pode ser composta por vários elementos Parada.
Parada

Indicador de início da estrutura de uma parada.

Atributo Tipo Obrigatório Descrição
numero string Sim Atributo de Parada. Corresponde ao número da parada no sistema.
TAG Tipo Obrigatório Descrição
Documento element Sim Indicador de início da estrutura do Documento. No caso de entregas com mais de um documento, deve-se criar uma nova parada para cada documento. O sistema identifica vários documentos em um mesmo endereço e realiza a consolidação.
Documento

Indicador de início da estrutura de um documento. Uma parada deve ter um único documento. Para o caso de vários documentos para o mesmo local, deve-se criar uma parada para cada documento, pois o sistema automáticamente reconhece pelo endereço e consolida estes documentos na rota.

TAG Tipo Obrigatório Descrição
ChaveNota string Sim Chave do documento. Normalmente é a chave do documento fiscal (barcode). Este campo é obrigatório e seu conteúdo deve ser único para documentos diferentes.
Agendamento string Não Indicador de Data acordada para entrega. Este campo não deve ser enviado caso não se aplique agendamento à nota.
Itinerario element Não Dados do Itinerario
Atributo Tipo Obrigatório Descrição
numero string Sim Atributo de Rota. Corresponde ao número da rota no sistema.

Itinerario

TAG Tipo Obrigatório Descrição
ChaveUnica string * Chave única do itinerário
Codigo string * Código do itinerário
Descricao string * Descricao do itinerário
CodigoDeBarras string * Código de Barras do itinerário
Data string * Data do itinerário
Turno string * Turno do itinerário
Prioridade string * Prioridade do itinerário
Tipo string * Tipo do itinerário
PontoTransbordo1 string * Ponto de transbordo do itinerário
CnpjTransportador1 string * CNPJ do transportador do itinerário
NomeTransportador1 string * Nome do transportador do itinerário
Filial string * Filial do itinerário