Integração Compliance
Nesse artigo explicaremos sobre como realizar a integração com a API REST para enviar as conciliações ao InvoiCy. Para facilitar seu entendimento, acesse a documentação sobre a extensão InvoiCy Compliance no Postman, clicando aqui.
Inicialmente, é necessário gerar os tokens para integração com a API, por questões de segurança.
Geração de Tokens
Acesse aqui um exemplo completo no Postman de como gerar os tokens accessToken e o refreshToken para que seja possível enviar as demais requisições.
Com o intuito de gerar os tokens que será utilizado nas requisições do compliance, veja abaixo uma listagem com as informações que precisam ser inseridas em Headers para enviar a requisição:
° EmpPK: chave de parceiro (partner-key);
° EmpCK: informe o hash MD5 gerado a partir da concatenação da chave de acesso com o corpo da requisição md5 (chaveAcesso + body)
Enquanto que no Body(raw), o usuário deve preencher os seguintes dados e, após, enviar a requisição:
° cnpj: CNPJ da empresa que quer gerar os tokens;
° extensao: nome da extensão que se deseja o tokens. Neste caso informe "compliance"
No retorno da requisição serão apresentados o accessToken e o refreshToken, que são os tokens gerados a partir desse envio, juntamente com o status da requisição, conforme evidenciado abaixo:
Agendar Conciliação
Acesse aqui um exemplo completo no Postman de como realizar o agendamento da conciliação.
Com o intuito de agendar as conciliações através do InvoiCy Compliance, insira o token gerado anteriormente no campo Authorization em Headers.
Em seguida, no Body(raw), o usuário precisa preencher os seguintes dados, e após, enviar a requisição:
° parceiro: chave de parceiro (partner key);
° cnpjRaiz: CNPJ raiz da empresa;
° dataInicial: data inicial do período a ser conciliado (YYYY-MM-DD);
° dataFinal: data final do período a ser conciliado (YYYY-MM-DD);
° modelo: modelo do documento. Neste caso informe "nfce";
° fusoHorario: fuso horário do local onde está realizando a requisição
No retorno da requisição será exibida a URL relacionada ao envio da conciliação, juntamente com o protocolo, conforme evidenciado abaixo:
Destacando que, esta URL retornada ao realizar o agendamento da conciliação, será utilizada posteriormente para fazer o envio do arquivo compactado com os documentos a serem conciliados.
Enviar Conciliação
O cliente terá 10 minutos para enviar o(s) documento(s) a ser(em) conciliado(s), após esses 10 minutos o processo de conciliação será executado para o agendamento, se o cliente não enviar o documento antes dos 10 minutos será necessário repetir o processo anterior.
Este documento deve ser um arquivo de texto (.txt) compactado (.zip) e enviado da seguinte maneira:
Dessa forma, o usuário precisa indicar no cabeçalho de envio os seguintes dados: o CNPJ da empresa e a chave de acesso gerada pela concatenação entre o CNPJ + chaveAcesso. Em seguida, deve informar por linha de registro o número, a série, o modelo, a data de emissão (formato YYYY-MM-DD), a chave de acesso (que não é necessária em caso de inutilização) e, por fim, preencher o último campo com "S" (Sim) se o documento for cancelado ou inutilizado.
Salientando que, a URL recebida no agendamento da conciliação deve ser um método PUT, onde no Body será enviado o conteúdo em "binary", possibilitando assim realizar upload do arquivo .zip.
Sendo assim, no Body(binary), é necessário informar em documento.zip o arquivo binário e, após, enviar a requisição de conciliação de documentos. Em caso de sucesso, será retornado o status "200".
Consultar Conciliação
Acesse aqui um exemplo completo no Postman de como realizar a consulta da conciliação.
Inicialmente, para realizar este processo insira o token gerado anteriormente no campo Authorization em Headers. Em seguida, no Body(raw), o usuário precisa preencher os dados e, após, enviar a consulta.
No retorno da requisição, serão exibidos o código de retorno "100" e mensagem "Conciliação processada", juntamente com uma URL contendo um arquivo com todas divergências da conciliação, conforme demonstrado a seguir:
O conteúdo do arquivo de divergências será um arquivo de texto (.txt) no seguinte formato:
| CNPJ | Número | Série | Modelo | Status InvoiCy | Status Cliente |
|---|---|---|---|---|---|
| 99999999999999 | 111 | 39 | 65 | 3 | 1 |
| 99999999999999 | 112 | 39 | 65 | 0 | 2 |
| 99999999999999 | 113 | 39 | 65 | 2 | 2 |
Ressaltando que, cada status relacionado ao InvoiCy ou ao cliente possui uma numeração específica que se refere a um determinado tipo de status do documento. Segue abaixo essa relação:
0 = Faltante;
1 = Inconsistente;
2 = Autorizado;
3 = Rejeitado;
5 = Cancelado;
6 = Inutilizado.
Também pode ser retornada a mensagem "error-conciliacao", onde será necessário rever as informações enviadas, pois isso indica que ocorreu um erro na consulta da requisição. Além da possiblidade de retornar no campo processingAt, a quantidade de CNPJs já processados ou a data e hora do processamento, caso a conciliação ainda esteja aguardando processamento.