Pular para conteúdo

WS113 - Receber Ocorrências Dos Documentos

Objetivo

Receber as informações dos status e ocorrências de documentos conforme forem apontados pelos motoristas. Uma vez consumido, uma ocorrência NÃO será disponibilizada por este método novamente.

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

Importante

  1. 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.
  2. 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 1 do nosso sistema de integração. Caso deseje consultar a versão 2, 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;

Autenticação

  • As chamadas terão autenticação a nível de transporte (Basic Authentication);
  • Solicite o user / password ao administrador da conta.

Exemplo cabeçalho HTTP com a autenticação

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

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

TAG Tipo Descrição
qtdDocumentos integer Quantidade máxima de documentos que serão retornadas nessa consulta.

Exemplo de Request

<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

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 exportação.

Protocolo

Quando um pedido de exportação é criado no nosso sistema, um protocolo é gerado para que este processo seja acompanhado. Isso pode ser feito utilizado o método WS502.

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

O que é gerado nesta exportação

Utilizando o protocolo gerado no método WS502, o usuário receberá uma URL para acessar o arquivo XML contendo todas as ocorrências disponíveis no sistema no momento da execução, respeitando a quantidade máxima solicitada. Este arquivo XML é composto da seguinte forma:

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

Documento

TAG Tipo Descrição
Tipo string Tipo do documento.
Modelo string Modelo do documento.
Numero string Número do documento.
Serie string Série do documento.
Emissao string Data de emissão do documento. Formato: YYYY-MM-DD HH:MM:SS
Cnpj string CNPJ do destinatário do documento.
Chave string Chave do documento.
Status string Código e descrição do status do documento no momento da consulta. Formato: Código - Descrição
Ocorrencias element Elemento raiz para a lista de ocorrências do documento e é composto por um ou mais Ocorrencia.
Itens element Elemento raiz para a lista de itens do documento e é composto por um ou mais Item.
Danfes element Elemento raiz para a lista de DANFEs do documento e é composto por um ou mais Danfe.

Ocorrencia

TAG Tipo Descrição
Numero string Id da ocorrência. Este número é único e não se repete pois representa a chave do registro em nossa base de dados.
Motivo string Código da ocorrência + descrição da ocorrência, no formato: Código - Descrição.
Data string Data da ocorrência no formato: YYYY-MM-DD HH:MM:SS.
Assinatura element Elemento raiz para a Assinatura coletada pelo motorista.
Anotacao string Texto inserido na anotação feita pelo motorista.
Fotos element Elemento raiz para a lista de fotos realizadas pelo motorista. É composto por um ou mais Foto.
CnpjTransportador string CNPJ da Transportadora responsável pelo apontamento da ocorrência.
Romaneio string Número do Romaneio.
Posicao element Local de captura da ocorrência. Mais detalhes em Posicao
Assinatura
TAG Tipo Descrição
Nome string Identificação fornecida pelo assinante. Formato: nome + vírgula + espaço + documento.
Dado string URL para acessar a imagem da assinatura coletada pelo motorista.
HashEntrega string Hash (SHA1) no formato Base64 resultante da concatenação: Chave de acesso do documento + Base64 da imagem.

HashEntrega

Campo necessário para atender ao evento Comprovante de Entrega do CT-e.

Foto
TAG Tipo Descrição
Comentario string Comentário feito pelo motorista no momento da foto.
Dado string URL para acessar a foto feita pelo motorista.
HashEntrega string Hash (SHA1) no formato Base64 resultante da concatenação: Chave de acesso do documento + Base64 da imagem.

HashEntrega

Campo necessário para atender ao evento Comprovante de Entrega do CT-e.

Posicao
TAG Tipo Descrição
Latitude decimal Latitude do local de captura da ocorrência.
Longitude decimal Longitude do local de captura da ocorrência.

Item

TAG Tipo Descrição
Numero string Sequencia do item no documento (sempre inicia do numero 1).
Descricao string Descrição do item.
Barcode string Barcode do item.
Quantidade string Quantidade conferida do item no formato x/y, onde x = quantidade conferida e y = quantidade total do item.
Foto string URL para acessar a foto do item realizada pelo motorista.
Motivo string Motivo da não entrega de um item caso o motorista faça a justificativa.

A conteúdo da TAG Item é preenchido quando for detectado uma ocorrência de finalização do documento, ou seja, o documento foi Entregue, com ou sem conferência dos itens, Coletado ou Devolvido.

Danfe

TAG Tipo Descrição
Numero string Número da DANFE.
Serie string Série da DANFE.
Chave string Chave da DANFE.
Emissao string Data de emissão da DANFE no formato: YYYY-MM-DD HH:MM:SS.
Cnpj string CNPJ da DANFE.
Volume inteiro Volume coletado da DANFE.

Exemplo do arquivo XML gerado

Clique aqui para ver o exemplo 
<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>