Na mensagem a ser enviada para nossa API é necessário informar no Header o parâmetro IdKeyEmpresa, que foi destacado no tópico anterior. 

 

A Mensagem de Envio/Entrada da nossa API REST, em todas as operações. Segue o formato: 

{

"Tipo": "json",
"Sincrono": true,
"Transform": null,
"Hash": "1+15a6f8b88a9281fb146a4a4996204f6a6fb8353afc0f54d1edc342388484a9616dd59ff60394f39c1fcae7b2380dc9486d29184d95c8c0d8d2f2ed33e5b24fae",
"Documento": "{\"NFe\":{\"@xmlns\":\"http://www.portal..."
}

 

Abaixo segue detalhes sobre cada propriedade da mensagem:

Tipo:

Definição do formato que o DFe foi enviado. Temos os seguintes formatos disponíveis: 

  

- xml: xml do DFe;
- json: json do DFe com as informação que serão transformados em xml;
- txt: txt do DFe no padrão do VincoDFe ServiceBus que será transformado em xml;
- byte+xml: xml do DFe em um array de bytes;

- byte+json: json do DFe em um array de bytes com as informação que serão transformados em xml;
- byte+txt: txt do DFe no padrão do VincoDFe  ServiceBus que será transformado em xml;
- zip+xml: xml do DFe zipdado em um array de bytes;

- zip+json: json do DFe zipdado em um array de bytes com as informação que serão transformados em xml;
- zip+txt: txt do DFe zipdado em um array de bytes no padrão do VincoDFe ServiceBus que será transformado em xml;
- base64+byte+xml: xml do DFe em um array de bytes convertido em base64;

- base64+byte+json: json do DFe em um array de bytes convertido em base64 com as informação que serão transformados em xml;
- base64+byte+txt: txt do DFe em um array de bytes convertido em base64 no padrão do VincoDFe ServiceBus que será transformado em xml;

- base64+zip+xml: xml do DFe zipado em um array de bytes convertido em base64;
- base64+zip+json: json do DFe zipado em um array de bytes convertido em base64 com as informação que serão transformados em xml;
- base64+zip+txt: txt do DFe zipado em um array de bytes convertido em base64 no padrão do VincoDFe ServiceBus que será transformado em xml;

Síncrono

Se a resposta será síncrona ou não, no caso de usar síncrono o retorno da autorização da DFe estará no retorno da chamada, caso seja assíncrono o retorno da autorização estará disponível em outra requisição.

Documento

O DFe, o DFe pode ser enviado em vários formatos, os formatos são indicados na propriedade. Verifique os exemplos disponíveis e o layout esperado. 

 

Exemplo JSON

Exemplo XML

Layout dos campos

 

 Hash

 Hash para verificação da autenticidade do `sender`, o hash é obrigatório quando o VincoDFe SB assina o documento, caso contrario não é obrigado.

 

O hash é um valor formado por duas informações separadas pelo sinal + (adição):
- a primeira é a posição da Chave Privada no VincoDFe SB

- a segunda é resultado do algoritmo HMAC da entrada da Chave Privada e o conteúdo da tag "Documento" (o documento utilizado pelo VincoDFe Service Bus já foi parseado, logo, nesse ponto não existem mais os caracteres de escape “\”). O algoritmo HMAC pode ser MD5, SAH1, SHA256, SHA384 e SHA512.

Exemplo de como ficaria o Hash com a Chave Privada na posição 2 utilizando HMACMD5: “2+420f4b2d6e4b23bb74a5ea1b8bf592e9”

Exemplo de como ficaria o Hash com a Chave Privada na posição 14 utilizando HMACSHA1: “14+ddd638a3d62e0c6e312d0677f59ea974e6102735”

Exemplo de como ficaria o Hash com a Chave Privada na posição 123 utilizando HMACSHA1: “123 +415f00b7bc3e24080848a7d1b3f3f86c277e7645b697831aa7c84249d69a538df375d6e5c7c2e475d2ed1d8965327221c09eb308456e8674763bb1b7da3115dd”

 

Lembrando

 
- len(key))
o_key_pad = key.translate(trans_5C)
i_key_pad = key que somente as duas pontas (cliente, servidor(VincoDFe SB)) tem a chave privada para essa validação.

 

Para maiores informações de como o algoritmo HMAC funciona, consultar https://pt.wikipedia.org/wiki/HMAC ou acessar o site http://www.freeformatter.com/hmac-generator.html.

Dessa forma, será disponibilizada uma ferramenta para verificar a geração do HMAC no link para dowloado: http://nfe.vinco.com.br/nfe/Versions/TesteServiceBus.zip

Você também encontrará um aplicativo em .Net C# que serve para fazer testes com o ServiceBus e que permite comparar as mensagens geradas por outros aplicativos.

 

Calculando o Hash - Algoritmo HMAC usado criptografia MD5

 O algorítimo utilizado é o HMAC, utilizando o a função MD5 criptografia. (https://pt.wikipedia.org/wiki/HMAC). Primeiramente, deve-se calcular o HMAC, em python. Segue o exemplo:

 

#!/usr/bin/env python
from hashlib import md5
trans_5C = "".join(chr(x ^ 0x5c) for x in xrange(256))
trans_36 = "".join(chr(x ^ 0x36) for x in xrange(256))
blocksize = md5().block_size

 

def hmac_md5(key, msg):
if len(key) > blocksize:
key = md5(key).digest()
key += chr(0) * (blocksize.translate(trans_36)
return md5(o_key_pad + md5(i_key_pad + msg).digest())

 

if __name__ == "__main__":
h = hmac_md5("chaveprivadainformadanosuporte", "<?xmlversion...</NFe>")
print h.hexdigest() # 62c0f395c5268fe31d5866d1f7ea3ab8

 

O código acima citado geraria o hash "62c0f395c5268fe31d5866d1f7ea3ab8". Uma vez o hash gerado, iremos preencher a informação na chamada desta forma

 

{
"Documento":"<?xmlversion...</NFe>",
"Hash":"1+62c0f395c5268fe31d5866d1f7ea3ab8",
"Sincrono":"True",
"Tipo":"xml",
"Transform":null
}

 

O Hash será preenchido com a posição da chave privada no VincoDFe "1" (mais) "+" "62c0f395c5268fe31d5866d1f7ea3ab8" (hash gerado).