Integração HTTP Local

A integração Rest permite a comunicação através de HTTP e fornece as mesmas operações disponíveis na integração via dll, são elas:

• Emissão (Salva um lote de envio na pasta de entrada)
• Inutilização
• Cancelamento (Salva um arquivo de cancelamento na pasta de entrada)
• Reimpressão
• Impressão de texto livre em alguma impressora
• Acompanhar a resposta de um arquivo

Para ativar a integração via DLL no DF-e Client acesse o artigo:

• Como configurar a Integração via DLL no DFe Client?

E para mais detalhes da integração via DLL acesse:

• Integração DLL

Nesta integração, toda a comunicação é baseada em chamadas de POST com conteúdo JSON no serviço exposto na localização onde o DF-e Client está instalado e a porta onde o serviço é configurado (default 3090). A ação é definida através do parâmetro de URL “acao”.

• Exemplo: http://localhost:3090/?acao=emissao

Obs.: Nenhuma autenticação é necessária, o serviço será exposto localmente.

 

Contrato de configuração

Todas as requisições deverão ter no JSON base a propriedade “config” que carrega alguns metadados da requisição, ele é definido pelas seguintes propriedades:

• emitCpfCnpj : Número do CNPJ do emitente (Opcional);
• url_oobj_service : IP e porta onde o serviço HTTP está online.
• integracao: Identificador da integração definido de comum acordo junto a Oobj, este identificador define os layouts de entrada na emissão, cancelamento e outras ações necessárias;
• Integrações implementadas:
  • micros (Utiliza layout Micros na entrada)
  • cielopos (Utiliza layout Micros na entrada mas não imprime)
  • yrest (Utiliza layout txt simplificado)
  • oobj (Utiliza layout Oobj na entrada)
  • oobj-lio (Utiliza layout Oobj na entrada mas não imprime)
  • nfce-xml-sefaz (Utiliza layout SEFAZ não codificado na entrada)
  • cfe-xml-sefaz (Utiliza layout SEFAZ não codificado na entrada)
  • nfe-xml-sefaz(Utiliza layout Sefaz na entrada)
• serie: Série em que as notas enviadas para este serviço serão emitidas, também é relevante para a configuração de impressoras;
• idPDV: Identificador do PDV a ser utilizado na emissão da nota
• Conteúdo: String contendo conteúdo do lote a ser emitido de acordo com o Layout escolhido. Esse conteúdo deve ser encodado em UTF-8.
• Veja aqui como fazer o enconde do conteúdo do seu documento.

 

O CNPJ do emitente é opcional?

Sim, para os casos onde o cliente só tenha um único CNPJ configurado no periférico. Caso tenha mais, o periférico vai responder dizendo que não pode executar a operação.

Exemplo de JSON completo

{
"config":{ "emitCpfCnpj":"07385111000102", "url_oobj_service":"https://127.0.0.1:3090/", "integracao":"micros", "serie":"35", "idPDV":"1"
}, "conteudo":
"H1%7cF%7cRicardo%20Faria%7c02372992163%7c%7c%7c%7c%7c%7c%7c%7c%7c%0d%0aH2%7c19%7c267%7c0%7cVANESSA%7c0.00%0d%0aH3%7c%7c%0d%0aI%7c50004%7cCASQUINHA%20%20%20%20%20%20%20%7c1%7c2.00%7c2.00%7c18.0000%7c0.00%7c21050010%7c%7c10.0%7c5.0%0d%0aP%7c10%7cDinheiro%7c2%7c%7c%7c%7c%7c%0d%0aCPL%7cPDV%3a%2018%20%2f%20Conta%20N.%3a%20862%20%2f%20Mesa%3a%200%20%2f%20Emp.%3a%20VANESSA%0d%0aCPL%7c%2a%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%0d%0aCPL%7cSEJA%20BEM%20VINDO%20A%0d%0aCPL%7cBURGER%20KING%0d%0a"
}

Obs.: Em todos os contratos de requisição o atributo “config” fica presente no mesmo local, sendo assim nos próximos exemplos resumiremos ele.

 

Emissão

A emissão de uma nota fiscal através da integração HTTP deve ocorrer em duas etapas, a de emissão onde é solicitado o início de um novo processo de emissão, seguido do acompanhamento que é a esperado pelo arquivo de resposta.

• Ação do endpoint

http://localhost:3090/?acao=emissao

• Contrato para comunicação

{“config”: { … ver trecho Contrato de configuração … },
“conteudo”: ” String com texto posicional ou XML que identifique um novo pedido de acordo com o layout utilizado “}

• Resposta

A resposta de sucesso deste método ocorre pelo status 200 (conforme padrão do http) contendo uma String que é o identificador do arquivo para acompanhamento. Este nome deve ser utilizado de acordo com as informações presentes na requisição de Acompanhamento.

 

Acompanhamento

Acompanhamento é uma ação que só deve ser utilizada como indicativo de outras ações, sua função é acompanhar o resultado de uma ação assíncrona, como é o caso da Emissão.

Cada requisição de acompanhamento tem timeout padrão de 30 segundos (podendo ser aumentado ou diminuído de acordo com configuração do DF-e Client), após os 30 segundos caso não haja retorno o solicitante pode decidir refazer a operação ou acompanhar novamente.

** Importante, uma vez que uma requisição de acompanhamento responda com sucesso (timeout é respondido com falha) o trabalho será consumido e novos acompanhamentos do mesmo trabalho apenas resultarão em timeouts.

• Ação do endpoint

http://localhost:3090/?acao=acompanhamento&nomeacompanhamento=Nome do acompanhamento recebido

• Contrato para comunicação

{“config”: { … ver trecho Contrato de configuração … } }

• Resposta

A resposta de sucesso deste método ocorre pelo status 200 contendo uma String que é a resposta do trabalho assíncrono no layout definido pela integração.

• Timeout

A resposta de timeout deste método ocorre pelo status 504 quando o resultado da operação ainda não tiver sido produzido.

Inutilização

O cancelamento de uma nota via integração HTTP ocorre no mesmo fluxo que a emissão, uma requisição de cancelamento e uma de acompanhamento.

• Ação do endpoint

http://localhost:3090/?acao=inutilizacao

• Contrato para a comunicação

{
“config”: { … ver trecho Contrato de configuração … },
“tpAmb”: “Valor número sendo 1 – Produção e 2 – homologação”,
“cUf”: “Valor numérico”,
“ano”: “Ano com 2 dígitos”,
“serie”: “Valor numérico para a serie que será inutilizada”,
“nNfIni”: “Número inicial que deverá ser inutilizado”,
“nNfFin”: “Número final que deverá ser inutilizado“,
“justificativa”: “Justificativa para a inutilização”
}

• Resposta

A resposta de sucesso deste método ocorre pelo status 200 (conforme padrão do http) contendo uma String que é o identificador do arquivo para acompanhamento. Este nome deve ser utilizado de acordo com as informações presentes na requisição de Acompanhamento.

Cancelamento

O cancelamento de uma nota via integração HTTP ocorre no mesmo fluxo que a emissão, uma requisição de cancelamento e uma de acompanhamento.

• Ação do endpoint

http://localhost:3090/?acao=cancelarnota

• Contrato para comunicação

{
“config”: { … ver trecho Contrato de configuração … },
“chaveAcesso”: ” String com chave de acesso da nota a ser cancelada “,
“protocolo”: ” String com o protocolo de autorização da nota “,
“justificativa”: ” String com o texto da justificativa no tamanho mínimo requerido pela sefaz “,
“cpfCnpjDestinatario”: ” String com o CPF ou CNPJ do destinatário da CF-e emitida, este campo somente é aplicado para CF-e “
}

• Resposta

A resposta de sucesso deste método ocorre pelo status 200 (conforme padrão do http) contendo uma String que é o identificador do arquivo para acompanhamento. Este nome deve ser utilizado de acordo com as informações presentes na requisição de Acompanhamento.

 

Reimprimir

A solicitação de uma reimpressão via integração HTTP gera um novo pedido de reimpressão, não há resultado de acompanhamento.

• Ação do endpoint

http://localhost:3090/?acao=reimprimir

• Contrato para comunicação

{
“config”: { … ver trecho Contrato de configuração … },
“chaveAcesso”: ” String com chave de acesso da nota a ser reimpressa “
}

• Resposta

A resposta de sucesso deste método ocorre pelo status 200 e seu conteúdo é irrelevante.

 

Impressão de texto livre (Texto Auxiliar)

Solicita a impressão do texto enviado já com formatação via requisição HTTP.

• Ação do endpoint

http://localhost:3090/?acao=impressao

• Contrato para comunicação

{
“config”: { … ver trecho Contrato de configuração … },
“conteudo”: ” String com o conteúdo a ser impresso “
}

• Resposta

A resposta de sucesso deste método ocorre pelo status 200 e seu conteúdo é irrelevante.

 service exposto sobre a autorização desta nota.

Testando Integração HTTP

Veja nosso artigo Como testar Integração HTTP Oobj?