Objetivo
Fazer upload 1 ou mais documentos
para o Comprovei.
Características
- As chamadas serão realizadas via
"SOAP" sobre HTTPS;
- A origem do chamado do web service será o
sistema do cliente;
- Importante: o usuário deste webservice deve armazenar o protocolo gerado. 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 transporte (Basic
Authentication);
- Solicite
o user / password ao administrador da conta.
POST https://soap.comprovei.com.br/importQueue/index.php HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "urn:WebServiceComprovei#uploadDocuments"
Authorization: Basic {* user/password codificado em BASE64}
Content-Length: {quantidade de bytes enviados}
Host: soap.comprovei.com.br
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Descrição do método
|
Método
|
uploadDocuments
|
|
Endereço
de acesso
|
https://soap.comprovei.com.br/importQueue/index.php?wsdl
|
|
Versão
atual
|
1.0
(22/02/2017) Versão inicial 1.1 (16/03/2017) Adicionada seção sobre a tag Rota.
|
Parâmetros de entrada
|
Atributo
|
Tipo
|
Descrição
|
|
conteudoArquivo
|
String
|
Conteúdo
do arquivo XML codificado em Base64. |
Estrutura do arquivo XML
Estrutura Documentos.
TAG raiz que contém todas as estruturas Documento.
|
Atributo
|
Tipo
|
Obrigatório
|
Descrição
|
|
Documento
|
Estrutura Documento
|
Sim
|
Contém todas as informações acerca do documento.
|
Estrutura
Documento. Contém diversas informações sobre o documento a ser importado.
|
Atributo
|
Tipo
|
Obrigatório
|
Descrição
|
|
Tipo
|
String
|
Sim
|
Tipo do documento NFS, OS, REQ, etc. O sistema não
valida esta informação, apenas exibe para melhor orientação.
|
|
TipoParada
|
String
|
Sim
|
E = Documento de entrega | C = Documento de
coleta | CA = Documento de coleta de danfes | CB = Documento de coleta com
conferência
|
|
Modelo
|
String
|
Sim
|
Modelo fiscal do documento (verificar junto a SEFAZ
os modelos disponíveis).
|
|
Numero
|
String
|
Sim
|
Número do documento. Somente números sem caracteres
especiais ou espaços.
|
|
Valor
|
String
|
Sim
|
Valor total do documento. Números decimais
podem ter como separador "." ou ",".
|
|
Serie
|
Integer
|
Sim
|
Série do documento. Valor padrão “0".
|
|
Emissao
|
String
|
Sim
|
Data de emissão do documento. Obrigatório o formato YYYYMMDD.
|
|
Atualizacao
|
String
|
Não
|
Data de envio do documento à
transportadora. Obrigatório o formato YYYYMMDD.
|
|
Chave
|
String
|
Sim
|
Chave do documento. Normalmente é a chave do
documento fiscal (barcode).
|
|
cnpj
|
String
|
Sim
|
CNPJ (ou CPF) do destinatário do documento. SOMENTE NÚMEROS, NÃO COLOCAR
".", "-","/".
|
|
cnpjEmissor
|
String
|
Sim
|
CNPJ do emitente do documento e/ou do
embarcador. SOMENTE NÚMEROS, NÃO COLOCAR ".",
"-","/".
|
|
cnpjTransportador
|
String
|
Sim
|
CNPJ do transportador. SOMENTE NÚMEROS, NÃO
COLOCAR ".", "-","/".
|
|
Remessa
|
String
|
Não
|
Número da remessa do documento.
|
|
Pedido
|
String
|
Não
|
Número do pedido do documento.
|
|
Placa
|
String
|
Não
|
Placa do veículo associado ao documento.
|
|
Filial
|
String
|
Não
|
Filial associada ao documento.
|
|
Peso
|
String
|
Não
|
Peso total da carga do documento.
|
|
Cubagem
|
String
|
Não
|
Volume total da carga do documento.
|
|
ONU
|
String
|
Não
|
Código de periculosidade da carga do documento.
|
|
Janela
|
String
|
Não
|
Janela de entrega
|
|
Cliente
|
Estrutura Cliente
|
Sim
|
Contém informações do cliente destinatário do
documento (cliente final).
|
|
SKUs
|
Estrutura SKUs
|
Sim
|
Contém informações sobre os itens a serem
entregues/coletados no cliente final.
|
Estrutura Rota. Deve
estar dentro da estrutura documento. A estrutura Rota NÃO é obrigatória.
|
Atributo
|
Tipo
|
Obrigatório
|
Descrição
|
|
Nome
|
String
|
Sim
|
Nome da rota
|
|
Data
|
String
|
Sim
|
Data da Rota. Obrigatório o formato YYYYMMDD.
|
|
Motorista
|
String
|
Sim
|
Código do motorista responsável pela rota.
|
Estrutura
Cliente. Contém diversas informações sobre o cliente destinatário do documento
(cliente final).
|
Atributo
|
Tipo
|
Obrigatório
|
Descrição
|
|
Codigo
|
Integer
|
Sim
|
Código do cliente (ou CNPJ). Esse código é
estritamente numérico.
|
|
Contato
|
String
|
Sim
|
Nome do contato do cliente destinatário.
|
|
Telefone
|
String
|
Sim
|
Celular (para envio de SMS) do contato do cliente
destinatário.
|
|
Email
|
String
|
Sim
|
Email (para envio de emails) do contato do cliente
destinatário.
|
|
Razao
|
String
|
Sim
|
Razão social ou nome fantasia do cliente
destinatário.
|
|
Endereco
|
String
|
Sim
|
Endereço de entrega do cliente destinatário. Somente
rua e número, separado por vírgula (","), sem complementos.
|
|
Bairro
|
String
|
Não
|
Bairro.
|
|
Cidade
|
String
|
Sim
|
Cidade.
|
|
Estado
|
String
|
Sim
|
Estado (UF).
|
|
Pais
|
String
|
Sim
|
País
|
|
CEP
|
String
|
Sim
|
CEP do endereço de entrega.
|
|
Regiao
|
String
|
Não
|
Região ou filial ou rota do endereço de entrega
|
|
TipoCliente
|
String
|
Não
|
Tipo do cliente
|
|
Mensagem
|
String
|
Não
|
Mensagem a ser exibida no dispositivo do motorista
durante a entrega/coleta.
|
Estrutura SKUs.
TAG raiz para agrupar todas as estruturas SKU.
|
Atributo
|
Tipo
|
Obrigatório
|
Descrição
|
|
SKU
|
Estrutura SKU
|
Sim
|
Contém informações sobre o item a ser
entregue/coletados no cliente final.
|
Estrutura SKU. Contém
informações sobre o item a ser entregue/coletado.
|
Atributo
|
Tipo
|
Obrigatório
|
Descrição
|
|
codigo
|
Atributo da TAG. String
|
Sim
|
Código do item.
|
|
PesoBruto
|
String
|
Não
|
Peso bruto total deste item. Números decimais podem
ter como separador "." ou ",".
|
|
PesoLiquido
|
String
|
Não
|
Peso líquido total deste item. Números decimais podem
ter como separador "." ou ",".
|
|
Volumes
|
String
|
Sim
|
Quantidade total de volumes deste item.
|
|
Descricao
|
String
|
Sim
|
Descrição deste item.
|
|
Qde
|
String
|
Sim
|
Quantidade total deste item.
|
|
Uom
|
String
|
Sim
|
Unidade de medida deste item.
|
|
Barcode
|
String
|
Sim
|
Código de barras deste item (para conferência).
|
Estrutura Janela
de entrega/coleta. TAG raiz para agrupar os horários de início e fim.
|
Atributo
|
Tipo
|
Obrigatório
|
Descrição
|
|
DataHoraIni
|
String
|
Sim
|
Horário de início da janela de entrega/coleta.
Obrigatório utilizar o formato YYYYMMDD HHMM
|
|
DataHoraFim
|
String
|
Sim
|
Horário de fim da janela de entrega/coleta.
Obrigatório utilizar o formato YYYYMMDD HHMM
|
Exemplo da requisição
<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:uploadDocuments
soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<conteudoArquivo
xsi:type="xsd:string">PD94bWwgdmVyc2l G8+MDwvUGVzb0JydXRvPgogICAgICAgICAgICA8UGVzb0xpcXVpZG8+MDwvUGVzb0xpcXVpZG8vbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPERvY3VtZW50b3M……</conteudoArquivo>
</urn:uploadDocuments>
</soapenv:Body>
</soapenv:Envelope>
Parâmetros de saída
Estrutura básica
de saída. Contém código e mensagem do retorno da chamada, além da estrutura
Notifications.
|
Atributo
|
Tipo
|
Descrição
|
|
Code
|
Integer
|
Código geral de retorno (ver tabela de Códigos de
Retorno da Chamada).
|
|
Status
|
String
|
Mensagem geral de retorno (ver tabela
de Códigos de Retorno da Chamada).
|
|
protocolo
|
String
|
Protocolo
para consultar a evolução do pedido de importação (em caso de sucesso).
|
|
Notifications
|
Estrutura
Notifications
|
Estrutura
que pode conter Error ou Warning
|
Estrutura Notification.
Contém as estruturas Error e Warning.
|
Atributo
|
Tipo
|
Descrição
|
|
Error
|
Estrutura
Error
|
Contém
o código de erro, a chave do documento e a mensagem para aquele documento.
|
|
Warning
|
Estrutura
Warning
|
Contém
o código de aviso, a chave do documento e a mensagem para aquele documento.
|
Estruturas Error
e Warning. Contem códigos, chave e mensagens.
|
Atributo
|
Tipo
|
Descrição
|
|
Code
|
Integer
|
Código
de erro/alerta para o documento (ver tabela de Códigos de Retorno do
Documento).
|
|
Doc
|
String
|
Chave
de identificação deste documento.
|
|
Mensagem
|
String
|
Mensagem
de alerta para este documento.
|
Códigos de
Retorno da Chamada
|
Código
|
Descrição
|
|
0
|
Todos os
documentos adicionados à fila de importação!
|
|
1
|
Arquivo identificado como xml inválido ou
corrompido.
|
|
3
|
Alguns documentos apresentaram erros. Estes
não foram adicionados à fila de importação.
|
|
4
|
Todos os
documentos apresentam erros e não foram adicionados à fila de importação.
|
|
999
|
Usuário não autenticado! |
Códigos de Retorno do Documento
|
Código
|
Descrição
|
|
3
|
Documento com esta chave já importado.
|
|
8
|
Itens do documento estão sem código.
Importação abortada.
|
Exemplo
da resposta
<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:uploadDocumentsResponse>
<Code
xsi:type="xsd:integer">3</Code>
<Status
xsi:type="xsd:string">Alguns documentos apresentaram erros. Estes
não foram adicionados à fila de importação.</Status>
<protocolo
xsi:type="xsd:string">2017022258ade8611f302</protocolo>
<Notifications
xsi:type="ns1:Notifications">
<Error
SOAP-ENC:arrayType="ns1:Notification[6]"
xsi:type="ns1:ArrayNotifications">
<item
xsi:type="ns1:Notification">
<Code
xsi:type="xsd:integer">3</Code>
<Doc
xsi:type="xsd:string">35170104692027001034550050029045471273826851</Doc>
<Mensagem
xsi:type="xsd:string">Documento com esta chave já
importado</Mensagem>
</item>
<item
xsi:type="ns1:Notification">
<Code xsi:type="xsd:integer">3</Code>
<Doc
xsi:type="xsd:string">35170104692027001034550050029079271914086761</Doc>
<Mensagem
xsi:type="xsd:string">Documento com esta chave já
importado</Mensagem>
</item>
<item
xsi:type="ns1:Notification">
<Code
xsi:type="xsd:integer">3</Code>
<Doc
xsi:type="xsd:string">35170104692027001034550050029079411001805635</Doc>
<Mensagem
xsi:type="xsd:string">Documento com esta chave já
importado</Mensagem>
</item>
<item
xsi:type="ns1:Notification">
<Code
xsi:type="xsd:integer">3</Code>
<Doc
xsi:type="xsd:string">41170109078580000104550010000061221977415460</Doc>
<Mensagem
xsi:type="xsd:string">Documento com esta chave já
importado</Mensagem>
</item>
</Error>
</Notifications>
</ns1:uploadDocumentsResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
|
|
