Voltar para ""

Cadastro via SOAP

A funcionalidade do Webhook, permite enviar notificações específicas para NF-e, NFC-e, NFS-e, certificado digital e GNRE ao cadastrar uma notificação via tela, conforme detalhado no artigo de configurações. No entanto, esta e outras opções também estão disponíveis via Web Service.

Existem duas possibilidades para realizar o cadastro, a consulta ou a atualização de um Webhook via SOAP, sendo elas: empresa ou parceiro. Além disso, há algumas diferenças importantes no momento de realizar determinada ação em ambas as possibilidades, que serão esclarecidas no decorrer do artigo.

Para realizar qualquer ação do Webhook via SOAP, é necessário estabelecer uma comunicação com o Web Service apropriado. Primeiramente, visualize a estrutura WSDL do mesmo:

• Homologação: https://homolog.invoicy.com.br/awebhook.aspx?wsdl
• Produção: https://app.invoicy.com.br/awebhook.aspx?wsdl

Em seguida, será necessário realizar o consumo do Web Service para efetuar a integração.

Cadastro para Empresa

Trata-se de um Webhook exclusivo para a sua empresa, que enviará notificações para o link configurado. Para realizar esse cadastro, é essencial que a informação EmpCNPJ seja preenchida no momento do envio da requisição.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="InvoiCy">
    <soapenv:Header/>
    <soapenv:Body>
        <inv:webhook.Execute>
            <inv:Invoicywebhook>
                <Cabecalho>
                    <EmpPK>ABCabcCBAcbaA+CabcCBAc==</EmpPK>
                    <EmpCK>251b34a2728849b0f83dbfb28b14bf0b</EmpCK>
                    <EmpCO>1</EmpCO>
                    <EmpCNPJ>99999999999999</EmpCNPJ>
                </Cabecalho>
                <Dados>
                    <DadosItem><!-- (1) --></DadosItem>
                </Dados>
            </inv:Invoicywebhook>
        </inv:webhook.Execute>
    </soapenv:Body>
</soapenv:Envelope>

1. Neste campo, informe o XML de envio. Para visualizar um exemplo de envio, clique aqui.

No XML de envio devem ser preenchidos os seguintes campos:

Descrição: Neste campo de texto deve ser informada a descrição ou título que se deseja atribuir ao Webhook que está sendo cadastrado.

Status: Indica se o Webhook configurado está preparado para receber mensagens ou não. Neste campo, deve ser informado "A" para Ativo ou "I" para Inativo.

Tipo Autenticação: Define como o InvoiCy irá se autenticar para realizar a conexão com a URL informada. Nesse campo informe os seguintes valores:

• 0 - Sem autenticação: parametrizado dessa forma, ao realizar a requisição para a URL informada nenhum tipo de Authorization Request Header será enviado na conexão.

• 1 - Basic Auth: ao usar esse tipo de autenticação, quando o InvoiCy se comunicar com o sistema do parceiro, será adicionado ao cabeçalho da requisição o seguinte entity header: Authorization: Basic {Valor informado no campo TokenAutenticacao}. O Basic Authentication é o sistema de autenticação mais comum do protocolo HTTP. Ele é incluído no header da requisição HTTP dessa maneira: Authorization: Basic {credenciais em base64 no formato usuário:senha}Para autorizar como nome de usuário/senha o cliente enviaria: Authorization: Basic AXXxxxxxxXXX0xxXxXX==

• 2 - Bearer Token: optando por esse tipo de autenticação, no cabeçalho da requisição ao sistema do parceiro será adicionado o seguinte entity header: Authorization: Bearer {Valor informado no campo TokenAutenticacao}.

Bearer: Bearer authentication (também conhecido como token authentication) é um Schema para autenticação HTTP que envolve tokens de segurança. O Bearer Token é uma string enigmática, geralmente gerada pelo servidor em resposta a uma solicitação de login. O cliente deve enviar este token no cabeçalho Authorization ao solicitar recursos protegidos "Authorization: Bearer"

Token: Neste campo é parametrizado o Token pelo qual o InvoiCy irá se autorizar/autenticar na API do parceiro em cada requisição. O Token de autenticação será definido para cada empresa, podendo ser configurado o mesmo token para todas as empresas. Será o parceiro quem irá definir a informação que deseja colocar neste campo, e posteriormente validar na API que o InvoiCy enviou o token informado.

URL: Neste campo é informada a URL com a qual o InvoiCy irá realizar a requisição POST para enviar a notificação da troca de status do documento. Lembrando que a URL deve ser válida e segura (https).

Módulo: É nessa etapa que será escolhido o módulo que será vinculado ao Webhook em questão. Nesse campo temos os seguintes valores: 1 - NF-e 2 - NFC-e 4 - NFS-e 12 - GNRE 14 - Certificado Digital

Tipo Notificação: Defina o tipo de notificação a ser enviado. Nesse campo temos os seguintes valores: 1 - Emissão do documento 2 - Atualização de status 3 - Evento 4 - Documento recebido 5 - Atualização de dados 6 - Documento inutilizado 7 - Documento autorizado na SEFAZ 8 - Vencimento do certificado 9 - Inclusão na fila para consulta 10 - Novo documento não encontrado 11 - Novo documento encontrado

Vale ressaltar que cada módulo tem suas características, então os tipos de notificações variam conforme o módulo em questão. Para estabelecer essa relação, disponibilizamos a seguinte tabela:

MÓDULO (VALOR)	TIPO DE NOTIFICAÇÃO (VALOR)
NF-e (1)	3 - Evento 4 - Documento recebido 5 - Atualização de dados 6 - Documento inutilizado 7 - Documento autorizado na SEFAZ
NFC-e (2)	3 - Evento 6 - Documento inutilizado 7 - Documento autorizado na SEFAZ
NFS-e (4)	1 - Emissão do documento 2 - Atualização do status 3 - Evento 4 - Documento recebido 5 - Atualização de dados 6 - Documento inutilizado 9 - Inclusão na fila para consulta 10 - Novo documento não encontrado 11 - Novo documento encontrado
GNRE (12)	1 - Emissão do documento
Certificado Digital (14)	8 - Vencimento do certificado

Cadastro para Parceiro

Trata-se de um cadastro para utilizar o mesmo Webhook para mais de uma empresa da sua base, visando facilitar o processo. Para realizar esse cadastro, é necessário remover a informação do campo EmpCNPJ, conforme demonstrado abaixo:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="InvoiCy">
    <soapenv:Header/>
    <soapenv:Body>
        <inv:webhook.Execute>
            <inv:Invoicywebhook>
                <Cabecalho>
                    <EmpPK>ABCabcCBAcbaA+CabcCBAc==</EmpPK>
                    <EmpCK>db6441614f6623a85869b86a0d54f080</EmpCK>
                    <EmpCO>1</EmpCO>
                    <EmpCNPJ></EmpCNPJ>
                </Cabecalho>
                <Dados>
                    <DadosItem><!-- (1) --></DadosItem>
                </Dados>
            </inv:Invoicywebhook>
        </inv:webhook.Execute>
    </soapenv:Body>
</soapenv:Envelope>

1. Neste campo, informe o XML de envio. Para visualizar um exemplo de envio, clique aqui.

Além disso, o hash MD5 precisa ser gerado no seguinte formato: chave de parceiro + XML da requisição.

No XML de envio, existe apenas um grupo diferente do que já foi visto anteriormente, que contempla o CNPJ das empresas que terão o Webhook replicado.

Consulta

Como estabelecido anteriormente, quando a ação é relacionada a empresa, é necessário informar o campo EmpCNPJ na estrutura SOAP. Contudo, quando for realizada a consulta de um Webhook de parceiros, remova a informação do campo em questão.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="InvoiCy">
    <soapenv:Header/>
    <soapenv:Body>
        <inv:webhook.Execute>
            <inv:Invoicywebhook>
                <Cabecalho>
                    <EmpPK>ABCabcCBAcbaA+CabcCBAc==</EmpPK>
                    <EmpCK>d74d20688f1a52228a65257901dffb9d</EmpCK>
                    <EmpCO>1</EmpCO>
                    <EmpCNPJ>99999999999999</EmpCNPJ>
                </Cabecalho>
                <Dados>
                    <DadosItem><!-- (1) --></DadosItem>
                </Dados>
            </inv:Invoicywebhook>
        </inv:webhook.Execute>
    </soapenv:Body>
</soapenv:Envelope>

1. Neste campo, informe o XML de envio. Para visualizar um exemplo de envio, clique aqui.

O XML de envio conta com o seguinte campo:

Identificador: Trata-se de um campo gerado automaticamente pelo InvoiCy no momento do cadastro do Webhook. Se o campo não for preenchido, a consulta irá retornar todos os Webhooks disponíveis para aquela empresa ou chave de parceiro. Caso seja preenchido, o retorno trará apenas o Webhook identificado.

O que define se a consulta será realizada para empresa ou parceiro é o preenchimento, ou não, da tag EmpCNPJ e como o hash MD5 foi gerado. Para empresa, deve ser gerado com base na chave de acesso da empresa + XML da requisição. Para consultar um Webhook de parceiros, o Hash deve ser gerado no seguinte formato: chave de parceiro + XML da requisição.

Atualização

Para atualizar dados em um Webhook já existente, é preciso enviar o XML de cadastro juntamente com o campo identificador, para que os dados sejam sobrescritos.

Novamente, nesse caso também existe a regra que contempla o campo EmpCNPJ e a forma de geração do hash MD5, já comentados acima. É isso que irá definir se a solicitação é para empresa ou parceiro. Para obter o campo Identificador e a estrutura completa para atualização, basta consultar os Webhooks disponíveis.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="InvoiCy">
    <soapenv:Header/>
    <soapenv:Body>
        <inv:webhook.Execute>
            <inv:Invoicywebhook>
                <Cabecalho>
                    <EmpPK>ABCabcCBAcbaA+CabcCBAc==</EmpPK>
                    <EmpCK>1e7625e0f3598e3b2bb86e9e0396b6fb</EmpCK>
                    <EmpCO>1</EmpCO>
                    <EmpCNPJ>99999999999999</EmpCNPJ>
                </Cabecalho>
                <Dados>
                    <DadosItem><!-- (1) --></DadosItem>
                </Dados>
            </inv:Invoicywebhook>
        </inv:webhook.Execute>
    </soapenv:Body>
</soapenv:Envelope>

1. Neste campo, informe o XML de envio. Para visualizar um exemplo de envio, clique aqui.

No exemplo acima, é possível identificar que a alteração será feita para um Webhook de parceiros, por conter o grupo Empresas no XML de envio. Logo, o código hash MD5 deve ser gerado com base na chave de parceiro e o campo EmpCNPJ não deve ser preenchido na estrutura SOAP. Também existe a opção de excluir o Webhook através da atualização de cadastro, informe o texto "DELETAR" no campo Modo.