2019
Integração Compliance
30 de dezembro de 2019Olá! Nesse artigo iremos explicar sobre a integração com a API para enviar as conciliações ao InvoiCy.
Para facilitar seu entendimento também criamos uma documentação de integração com o Postman, para acessá-la clique aqui.
Por questões de segurança, é necessário gerar um token para integração com a API.
1. Como gerar o token de segurança para o compliance:
O token a ser utilizado nas requisições do compliance deve ser gerado da seguinte forma:
{{ host-invoicy }} – o host do invoicy
{{ pk }} – chave de parceiro (partner-key)
{{ ck }} – Hash MD5 da chave de acesso com o corpo da requisição md5(chaveAcesso + body)
{{ cnpj }} – CNPJ da empresa que quer gerar o token
{{ extensao }} – nome da extensão que se deseja o token (nesse caso ‘compliance’)
O tipo da resposta será: Content-Type: application/json
2. Como agendar a conciliação:
O cliente poderá fazer o agendamento da conciliação utilizando o token da seguinte forma:
{{ access-token }} – token gerado no passo 1
{{ pk }} – chave de parceiro (partner key)
{{ cnpj-raiz }} – CNPJ raiz da empresa
{{ data-inicial }} – data inicial do período a ser conciliado (YYYY-MM-DD)
{{ data-final }} – data final do período a ser conciliado (YYYY-MM-DD)
{{ modelo }} – modelo do documento (nfce ou nfe)
{{ fusoHorario }} – Fuso horário de onde está fazendo a requisição, ex: -0300 || -03:00
O tipo da resposta será: Content-Type: application/json
OBSERVAÇÃO: a URL retornada ao fazer o agendamento da conciliação, será utilizada posteriormente para fazer o envio do arquivo compactado com os documentos a serem conciliados.
3. Como enviar documentos para conciliação:
O cliente terá 10 minutos para enviar o documento a ser conciliado, 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 passo 2.
- O conteúdo do documento deve seguir a seguinte regra:
* Campos obrigatórios
– Para cada empresa:
1 2
99999999999999|51d19cb4cfba20398cc3ff20b091f243
1 – CNPJ *
2 – hashMD5(cnpj + chaveAcesso) *
– Para cada documento:
1 2 3 4 5 6
99999|999|99|9999-99-99|99999999999999999999999999999999999999999999|S
1 – Número *
2 – Série *
3 – Modelo *
4 – Data de emissão (YYYY-MM-DD) *
5 – Chave de acesso (em caso de inutilização, não é necessário informar)
6 – Documento cancelado/inutilizado (S – sim)
Os dados devem ser separados por | (pipe)
Exemplo do conteúdo:
O documento deve ser um arquivo de texto (.txt) compactado (.zip) e enviado da seguinte forma:
{{ url }} – url recebida no passo 2
documento.zip – arquivo binário
OBSERVAÇÃO: exemplificando o envio através do Postman, ao clicar na url recebida no passo 2, a mesma deverá ser um método PUT, onde no Body será enviado o conteúdo em ‘binary’, possibilitando assim fazer upload do arquivo .zip, como demonstramos na imagem a seguir.
Retorno da requisição com status 200 em caso de sucesso.
4. Como consultar a conciliação:
A conciliação poderá ser consultada da seguinte forma:
{{ protocolo }} – Protocolo recebido no agendamento da conciliação
{{ access-token }} – token gerado no passo 1
Os retornos possíveis na consulta da conciliação seguem:
{{ url-divergencias }} – url contendo um arquivo com todas divergências da conciliação.
O conteúdo do arquivo de divergências será um arquivo de texto (.txt) no seguinte formato:
1 2 3 4 5 6
99999999999999|99999|999|99|9|9
1 – CNPJ
2 – Número
3 – Série
4 – Modelo
5 – Status do documento InvoiCy
6 – Status do documento Cliente
Exemplo de retorno:
- Status do documento
1 – INCONSISTENTE
0 – FALTANTE
2 – AUTORIZADO
3 – REJEITADO
5 – CANCELADO
6 – INUTILIZADO
{{ cnpjs-processados }} – quantidade de CNPJ’s já processados (integer)
{{ erro-conciliacao }} – mensagem informando qual o erro que ocorreu (string)
{{ data-processamento }} – data e hora do processamento (YYYY-MM-DDTHH:mm:ss.SSSZ)