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:
E para mais detalhes da integração via DLL acesse:
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?