WS012 - Send Route to Verify with Pre-Registered Documents

Click here to see version history

Update date	Service publication date	Changes
02/01/2021	05/02/2021	Addition of the Scheduling field to the document

Objective

This integration aims to allow the sending of a route to be tracked by Comprovei©, using only the keys of documents pre-registered in the system.

Method description


`Método`	uploadRouteUsingDocumentKey
`Versão`	2
`WSDL principal`	https://soap.comprovei.com.br/importQueue/v2/index.php?wsdl
`WSDL de contingência`	https://soapcontingencia.comprovei.com.br/importQueue/v2/index.php?wsdl
`XSD`	https://soap.comprovei.com.br/importQueue/schemas/WS012.xsd

Important

The connection to our service must be made to our main server, however we strongly suggest that a connection to our contingency server is also made available, as a guarantee of the availability of our services. The contingency server is only turned on in situations where our main server is unavailable. Making the connection url parameterizable is also a good practice;
Our connections are secure using the SSL protocol. For security reasons, our certificates are constantly changed without prior notice. Therefore, it is recommended that you do not develop integrations based on a fixed certificate.
We constantly (and without prior notice) add new fields and structures to both requests and responses from our web services. Anyone who uses our webservices must implement it in such a way that the programs that consume these webservices do not stop working when the mentioned field changes occur.

Features

Calls will be made via SOAP over HTTPS;
The origin of the Web Service call will be the client's system;

Important

Documents must be previously registered with Comprovei©, using WS013 or WS015, otherwise the route will be completely rejected.

Important

The user of this Web Service must store the protocol generated in the response. Support tickets regarding this integration will require this protocol.

Authentication

Calls will have message-level authentication (SOAP Header);
Request the username / password from the account administrator.

Request

The request for our Web Service is composed as follows:

Within the <Credentials> TAG:

TAG	Type	Description
`Usuario`	string	User for authentication.
`Senha`	string	User password for authentication

Body

Inside the <uploadRouteUsingDocumentKey> TAG:

TAG	Type	Description
`Rotas`	root	Root of the xml and composed of Rota.
`nomeArquivo`	string	Name of the sent file, with the extension. Example: route.xml.

Request Example

<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>
                <Rota numero="0403645401">
                    <rotadestino>DestinoDaRota</rotadestino>
                    <rotanome>NomeDaRota</rotanome>
                    <Data>20190107</Data>
                    <Regiao>RegiaoDaRota</Regiao>
                    <Transportadora>
                        <Codigo>12345678901234</Codigo>
                        <Razao>RazaoDaTransportadora</Razao>
                    </Transportadora>
                    <Motorista>
                        <Usuario>65040930160</Usuario>
                        <PlacaVeiculo>AAA1234</PlacaVeiculo>
                    </Motorista>
                    <Base>
                        <Origem codigo="codigobasedeorigem">
                            <Nome>NomeDaBaseDeOrigem</Nome>
                            <Rua>RuaDaBaseDeOrigem</Rua>
                            <Numero>1234</Numero>
                            <Complemento>ComplementoDaBaseDeOrigem</Complemento>
                            <Bairro>BairroDaBaseDeOrigem</Bairro>
                            <Cidade>CidadeDaBaseDeOrigem</Cidade>
                            <Estado>UFDaBaseDeOrigem</Estado>
                            <CEP>CEPDaBaseDeOrigem</CEP>
                            <Pais>BR</Pais>
                            <CodigoIBGE>12345678</CodigoIBGE>
                        </Origem>
                        <Destino codigo="codigobasededestino">
                            <Nome>NomeDaBaseDeDestino</Nome>
                            <Rua>RuaDaBaseDeDestino</Rua>
                            <Numero>1234</Numero>
                            <Complemento>ComplementoDaBaseDeDestino</Complemento>
                            <Bairro>BairroDaBaseDeDestino</Bairro>
                            <Cidade>CidadeDaBaseDeDestino</Cidade>
                            <Estado>UFDaBaseDeDestino</Estado>
                            <CEP>CEPDaBaseDeDestino</CEP>
                            <Pais>BR</Pais>
                            <CodigoIBGE>12345678</CodigoIBGE>
                        </Destino>
                    </Base>
                    <limites>
                        <inicio>20190107 0800</inicio>
                        <fim>20190107 1800</fim>
                    </limites>
                    <TipoRota>D</TipoRota>
                    <TipoMaterial>TipoMaterialTransportado</TipoMaterial>
                    <Fornecimento>CodigoFornecimentoRota</Fornecimento>
                    <TipoFrete>TipoFreteDaRota</TipoFrete>
                    <Paradas>
                        <Parada numero="1">
                            <Documento>
                                <ChaveNota>35150461087367000260550010011203161001234567</ChaveNota>
                            </Documento>
                        </Parada>
                    </Paradas>
                </Rota>
            </Rotas>
            <nomeArquivo>rota.xml</nomeArquivo>
        </uploadRouteUsingDocumentKey>
    </Body>
</Envelope>

Response

Our Web Service responds to you as follows:

TAG	Type	Description
`status`	string	Success or error message for the method call.
`protocolo`	string	Protocol for checking the progress of the import request.

Protocol

When a file is accepted into our system, a protocol is generated so that the import process can be monitored. This can be done using the WS501 method.

Response Example

<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>

Our Route XML

Our XML for importing a route is composed of the following TAGs:

TAG	Type	Required	Description
`Rotas`	root	Yes	Root of the xml and composed of Rota.

Route

TAG	Type	Required	Description
`rotadestino`	string	No	Indication of the destination or route itinerary (limited to 30 characters).
`rotanome`	string	No	Indication of the route name.
`Data`	string	Yes	Route operation start date. The format YYYYMMDD is mandatory.
`Regiao`	string	No	Route region.
`Transportadora`	element	Yes	Structure initial element that contains information about the Transporter that will execute the route.
`Motorista`	element	Yes	Structure initializer element that contains information about the Driver that will execute the route.
`Base`	element	No	Structure initial element that contains information about the Base of origin and destination of the route.
`limites`	element	No	Initializing element of the structure that contains information about the dates and times Limits of the start and end of the route.
`TipoRota`	string	No	Type of route sent. Allowed values: - D (Distribution) - T (Transshipment) - P (Place) - R (Return)
`TipoMaterial`	string	No	Type of route material.
`Fornecimento`	string	No	Route supply code.
`TipoFrete`	string	No	Type of freight contracted for the route.
`Modal`	string	No	Mode of transport contracted for the document.
`CamposLivres`	element	No	These fields are not replicated. CamposLivres
`Paradas`	element	Yes	Structure initializer element that contains information about all Stops that will be made by the driver.

Atributo	Type	Required	Description
`numero`	string	Yes	Route attribute. Corresponds to the route number in the system.

Carrier

Conveyor structure start indicator. A route can contain a single carrier.

TAG	Type	Required	Description
`Codigo`	string	Yes	Carrier code. Normally it is the CNPJ. Send numbers only.
`Razao`	string	Yes	Name of the carrier. You can use a short name (business name).

If you do not have this information, the fields must be sent without content (empty).

Driver

Driver structure start indicator. A route can contain a single driver.

TAG	Type	Required	Description
`Usuario`	string	Yes	Driver code registered with Comprovei.
`PlacaVeiculo`	string	Yes	Vehicle plate in the format: AAA9999 (without dash or space).
`TipoVeiculo`	string	No	Type of vehicle that will be used to complete the route.
`Nome`	string	No	Driver's name. This field will only be used when automatic driver registration is necessary!.
`Telefone`	string	No	Driver's telephone number, in the format DDDNNNNNNNNN. This field will only be used when automatic driver registration is necessary!.
`CNH`	element	No	Driver's license. This element will only be used when automatic driver registration is necessary!.
`CPF`	element	No	Driver's CPF. This element will only be used when automatic driver registration is necessary!.

If you do not have this information, the fields must be sent without content (empty) and the route must be associated with a driver manually.

The CNH element is composed as follows:

TAG	Type	Required	Description
`Numero`	string	*	Driver's driver's license number.
`Vencimento`	string	*	Expiration date of the driver's driver's license, in the format YYYMMDD.

*

The fields are mandatory if you want to provide the driver's driver's license.

Base

Indicator of the beginning of the structure of the source and destination bases. This information is optional and must be filled in when using routing.

TAG	Type	Required	Description
`Origem`	element	*	Route start location.
`Destino`	element	*	Route end location.

Source and Destination are composed as follows:

TAG	Type	Required	Description
`Nome`	string	*	Base registration name.
`Rua`	string	*	Street of the base of origin (Street, Avenue, Square, etc.).
`Numero`	integer	*	Base number.
`Complemento`	string	*	Complement of the base address.
`Bairro`	string	*	Base neighborhood.
`Cidade`	string	*	Base city.
`Estado`	string	*	UF of the base (For example: SP, MG).
`CEP`	string	*	ZIP code (only numbers, without dashes or spaces) of the base.
`Pais`	string	*	Base country, in alpha-2 (BR), alpha-3 (BRA) or in full (Brazil). See the list here.
`Contato`	string	No	Name of the person responsible for the base to contact.
`Email`	string	No	Email of the person responsible for the base to get in touch.
`Telefone`	string	No	Telephone number of the person responsible for the base to contact, in the format DDDNNNNNNNNN.
`Cnpj`	string	No	CNPJ of the base, using only numbers.
`CnpjMatriz`	string	No	If the base is a branch or associated with a carrier/shipper with a different CNPJ, the CNPJ of the associated company in question must be informed, using only numbers.
`TipoMatriz`	string	No	If this is the case mentioned above, inform the type of matrix. Allowed values: - courier (Carrier) - shipper (Shipper).
`CodigoIBGE`	string	No	Municipality identifier code.
`Posicao`	element	No	Element for sending position of the base.

Atributo	Type	Required	Description
`codigo`	string	*	Base identification code (Ideally, it should be unique).

Base Position

Element for sending the base location.

TAG	Type	Required	Description
`Latitude`	decimal	*	Base latitude, in decimal. Ex.: -23.5489
`Longitude`	decimal	*	Base length, in decimal. Ex.: 46.6388

*

If you want to send the location of origin and final destination of the route, all TAGs that make up these elements become mandatory.

Limits

TAG	Type	Required	Description
`inicio`	string	No	Deadline date/time for starting the route. Format: YYYYMMDD HHMM .
`fim`	string	No	Deadline date/time for the end of the route. Format: YYYYMMDD HHMM .

CamposLivres

TAG	Type	Required	Description
`CampoLivre1`	string	No	Free Field
`CampoLivre2`	string	No	Free Field
`CampoLivre3`	string	No	Free Field
`CampoLivre4`	string	No	Free Field
`CampoLivre5`	string	No	Free Field

Stops

Element responsible for grouping all Stop elements of the route.

TAG	Type	Required	Description
`Paradas`	element	Yes	Stop structure start indicator. A route can be composed of several elements Stop.

Stop

Indicator of the start of a stop structure.

Atributo	Type	Required	Description
`numero`	string	Yes	Stop attribute. Corresponds to the stop number in the system.

TAG	Type	Required	Description
`Documento`	element	Yes	Document structure start indicator. In the case of deliveries with more than one document, a new stop must be created for each document. The system identifies several documents at the same address and performs consolidation.

Document

Indicator of the beginning of a document's structure. A stop must have a single document. In the case of several documents for the same location, a stop must be created for each document, as the system automatically recognizes the address and consolidates these documents on the route.

TAG	Type	Required	Description
`ChaveNota`	string	Yes	Document key. Normally it is the tax document key (barcode). This field is mandatory and its content must be unique for different documents.
`Agendamento`	string	No	Indicator of agreed delivery date. This field should not be sent if scheduling is not applied to the note.
`Itinerario`	element	No	Itinerary data

Atributo	Type	Required	Description
`numero`	string	Yes	Route attribute. Corresponds to the route number in the system.

Itinerary

TAG	Type	Required	Description
`ChaveUnica`	string	*	Unique itinerary key
`Codigo`	string	*	Itinerary code
`Descricao`	string	*	Itinerary description
`CodigoDeBarras`	string	*	Itinerary barcode
`Data`	string	*	Itinerary date
`Turno`	string	*	Itinerary shift
`Prioridade`	string	*	Itinerary priority
`Tipo`	string	*	Itinerary type
`PontoTransbordo1`	string	*	Itinerary transfer point
`CnpjTransportador1`	string	*	CNPJ of the itinerary carrier
`NomeTransportador1`	string	*	Name of itinerary carrier
`Filial`	string	*	Itinerary branch