Voltar para ""

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.

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.

Exportar CSV

Acesse aqui um exemplo completo no Postman de como realizar a exportação.

Com o intuito de exportar os documentos fiscais conciliados em formato CSV, 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:

Campo	Tipo	Validação	Descrição
parceiro	string	Obrigatório, mínimo 1 caractere	Identificador único do parceiro.
cnpjRaiz	string	Exatamente 8 dígitos	Raiz do CNPJ (8 primeiros dígitos).
modelo	string	Enum: "nfe" ou "nfce"	Tipo de documento fiscal.
dataInicial	string	ISO 8601, deve ser < dataFinal	Data inicial do período (exemplo: "2026-01-01").
dataFinal	string	ISO 8601, deve ser > dataInicial	Data final do período (exemplo: "2026-01-31").
fusoHorario	string	Regex: ^[+-][0-2]\d:?\d\d$	Offset de timezone (exemplo: "-03:00" ou "-0300").

Importante: Esta rota implementa um padrão assíncrono. A requisição retorna imediatamente com HTTP 200, porém o arquivo CSV é processado em background, ficando disponível em aproximadamente 10 minutos.

No retorno da requisição serão apresentados os seguintes campos:

° url: URL pré-assinada do Google Cloud Storage onde o arquivo CSV estará disponível para download. A URL é válida por 2 dias;
° availableAt: timestamp ISO 8601 indicando quando o arquivo estará pronto para download;

O usuário deve aguardar até o horário indicado em availableAt antes de realizar o download. Tentar acessar a URL antes desse momento pode resultar em erro 404.

Após o arquivo estar disponível, o download pode ser realizado diretamente pela URL retornada. O CSV gerado seguirá o formato abaixo:

12345678000195,nfce,1,1001,2,2024-01-01,2024-01-01,35240101234567890123456789012345678901234567
12345678000195,nfce,1,1002,2,2024-01-02,2024-01-02,35240101234567890123456789012345678901234568
12345678000195,nfce,2,5001,3,2024-01-15,2024-01-15,35240101234567890123456789012345678901234569
12345678000195,nfce,1,1003,5,2024-01-20,2024-01-20,35240101234567890123456789012345678901234570

As colunas presentes no arquivo são, respectivamente: cnpj, modelo, serie, numero, status, data_inclusao, data_emissao e chave_acesso.

Os valores de status presentes no arquivo seguem a mesma nomenclatura utilizada na conciliação:

0 = Faltante;
1 = Inconsistente;
2 = Autorizado;
3 = Rejeitado;
5 = Cancelado;
6 = Inutilizado;