WS113 - Receive Occurrences of Documents

Objective

Receive information on the status and occurrences of documents as indicated by drivers. Once consumed, an instance will NOT be made available by this method again.

Method description


`Método`	downloadDocumentsHistory
`Versão`	1
`WSDL`	https://soap.comprovei.com.br/exportQueue/index.php?wsdl

Important

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.

Version

You are accessing version 1 of our integration system. If you wish to consult version 2, click here.

Features

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

Authentication

Calls will have transport-level authentication (Basic Authentication);
Request user / password from the account administrator.

Example HTTP header with authentication

POST https://soap.comprovei.com.br/exportQueue/index.php HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "urn:WebServiceComprovei#downloadDocumentsHistory"
Authorization: Basic BASE64(user:password)
Content-Length: {quantidade de bytes enviados}
Host: soap.comprovei.com.br
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Request

The request for our Web Service is composed as follows:

TAG	Type	Description
`qtdDocumentos`	integer	Maximum number of documents that will be returned in this query.

Request Example

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:WebServiceComprovei">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:downloadDocumentsHistory soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <qtdDocumentos xsi:type="xsd:integer">2</qtdDocumentos>
      </urn:downloadDocumentsHistory>
   </soapenv:Body>
</soapenv: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 export request.

Protocol

When an export order is created in our system, a protocol is generated so that this process can be monitored. This can be done using the WS502 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:downloadDocumentsHistoryResponse>
         <status xsi:type="xsd:string">Exportação adicionada a fila com sucesso. Acompanhe o processamento utilizando o protocolo fornecido!</status>
         <protocolo xsi:type="xsd:string">20170823599de095e8249</protocolo>
      </ns1:downloadDocumentsHistoryResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

What is generated in this export

Using the protocol generated in method WS502, the user will receive a URL to access the XML file containing all occurrences available in the system at the time of execution, respecting the maximum quantity requested. This XML file is composed as follows:

TAG	Type	Required	Description
`Documentos`	root	Yes	Root of the xml and composed of Document.

Document

TAG	Type	Description
`Tipo`	string	Document type.
`Modelo`	string	Document template.
`Numero`	string	Document number.
`Serie`	string	Document series.
`Emissao`	string	Date of issue of the document. Format: YYYY-MM-DD HH:MM:SS
`Cnpj`	string	CNPJ of the recipient of the document.
`Chave`	string	Document key.
`Status`	string	Code and description of the document status at the time of the query. Format: Code - Description
`Ocorrencias`	element	Root element for the list of document occurrences and is composed of one or more Occurrence.
`Itens`	element	Root element for the list of document items and is composed of one or more Item.
`Danfes`	element	Root element for the list of DANFEs in the document and is composed of one or more Danfe.

Occurrence

TAG	Type	Description
`Numero`	string	Occurrence ID. This number is unique and is not repeated as it represents the record key in our database.
`Motivo`	string	Occurrence code + occurrence description, in the format: Code - Description.
`Data`	string	Date of occurrence in the format: YYYY-MM-DD HH:MM:SS.
`Assinatura`	element	Root element for the Signature collected by the driver.
`Anotacao`	string	Text inserted in the note made by the driver.
`Fotos`	element	Root element for the list of photos taken by the driver. It consists of one or more Photo.
`CnpjTransportador`	string	CNPJ of the Carrier responsible for reporting the occurrence.
`Romaneio`	string	Mailing Number.
`Posicao`	element	Location of capture of the occurrence. More details in Posicao

Subscription

TAG	Type	Description
`Nome`	string	Identification provided by the subscriber. Format: name + comma + space + document.
`Dado`	string	URL to access the signature image collected by the driver.
`HashEntrega`	string	Hash (SHA1) in Base64 format resulting from the concatenation: Document access key + Image Base64.

HashEntrega

Field required to meet the CT-e Proof of Delivery event.

Photo

TAG	Type	Description
`Comentario`	string	Comment made by the driver at the time of the photo.
`Dado`	string	URL to access the photo taken by the driver.
`HashEntrega`	string	Hash (SHA1) in Base64 format resulting from the concatenation: Document access key + Image Base64.

HashEntrega

Field required to meet the CT-e Proof of Delivery event.

Position

TAG	Type	Description
`Latitude`	decimal	Latitude of the occurrence capture location.
`Longitude`	decimal	Longitude of the occurrence capture location.

Item

TAG	Type	Description
`Numero`	string	Sequence of the item in the document (always starts with number 1).
`Descricao`	string	Item description.
`Barcode`	string	Item barcode.
`Quantidade`	string	Checked quantity of the item in the format x/y, where x = checked quantity and y = total quantity of the item.
`Foto`	string	URL to access the photo of the item taken by the driver.
`Motivo`	string	Reason for not delivering an item if the driver provides justification.

Note

The content of the Item TAG is filled in when an occurrence of document completion is detected, that is, the document was Delivered, with or without checking the items, Collected or Returned.

Danfe

TAG	Type	Description
`Numero`	string	DANFE number.
`Serie`	string	DANFE series.
`Chave`	string	DANFE key.
`Emissao`	string	DANFE issue date in the format: YYYY-MM-DD HH:MM:SS.
`Cnpj`	string	DANFE CNPJ.
`Volume`	whole	Volume collected from DANFE.

Example of the generated XML file

Click here to see the example

<Documentos>
    <Documento>
        <Tipo>NFS</Tipo>
        <Modelo>EFS</Modelo>
        <Numero>247844</Numero>
        <Serie>1</Serie>
        <Emissao>2015-11-09 00:00:00</Emissao>
        <Cnpj>99999990003</Cnpj>
        <Chave>331111</Chave>
        <Status>0 - Pendente</Status>
        <Ocorrencias>
            <Ocorrencia>
            <Numero>24078</Numero>
            <Motivo>995 - Rota Cancelada</Motivo>
            <Data>2017-08-22 14:20:07</Data>
            <Assinatura/>
            <Anotacao/>
            <Fotos/>
            </Ocorrencia>
        </Ocorrencias>
        <Itens/>
        <Danfes/>
    </Documento>
    <Documento>
        <Tipo>NFS</Tipo>
        <Modelo>55</Modelo>
        <Numero>247834</Numero>
        <Serie>1</Serie>
        <Emissao>2017-06-30 00:00:00</Emissao>
        <Cnpj>07170938001685</Cnpj>
        <Chave>35140861079117010402550110002478341965483330</Chave>
        <Status>4 - Entregue SL</Status>
        <Ocorrencias>
            <Ocorrencia>
            <Numero>24079</Numero>
            <Motivo>995 - Rota Cancelada</Motivo>
            <Data>2017-08-22 14:20:07</Data>
            <Assinatura/>
            <Anotacao/>
            <Fotos/>
            </Ocorrencia>
            <Ocorrencia>
            <Numero>24111</Numero>
            <Motivo>0 - Entrega Normal</Motivo>
            <Data>2017-08-22 17:46:01</Data>
            <Assinatura/>
            <Anotacao/>
            <Fotos>
                <Foto>
                    <Comentario/>
                    <Dado>**URL**</Dado>
                </Foto>
            </Fotos>
            </Ocorrencia>
        </Ocorrencias>
        <Itens>
            <Item>
            <Numero>1</Numero>
            <Descricao>PERFORMANCE ADULT</Descricao>
            <Barcode>7896181211754</Barcode>
            <Quantidade>0/15</Quantidade>
            <Foto/>
            <Motivo/>
            </Item>
        </Itens>
        <Danfes/>
    </Documento>
</Documentos>