Neste artigo, vamos explorar o que é o IdIntegracao , como ele se diferencia do código numérico da chave de acesso, suas regras de unicidade e as melhores práticas para utilizá-lo corretamente. Além disso, abordaremos as diferenças na sua implementação entre o Plugnotas e o ManagerSaas, esclarecendo por que esse campo é essencial para um controle eficiente das integrações fiscais.
- 1 - O que é o idIntegracao?
- 2 - Diferença entre o "idIntegracao" e o "Código numérico que compõe a Chave de Acesso"
- 3 - Diferenças entre o idIntegracao no ManagerSaas e Plugnotas
- 4 - Importância do idIntegracao ser único
- 5 - Conclusão
1 - O que é o idIntegracao?
O campo idIntegracao é o seu identificador único, de uso opcional, que pode ser utilizado no arquivo de integração dos documentos fiscais para auxiliar no controle interno da sua aplicação. Ele permite que cada documento fiscal tenha um identificador exclusivo que facilita o rastreamento e a gestão das emissões.
Esse campo está disponível no Plugnotas por meio do arquivo de integração JSON e no ManagerSaas através do formato TX2.
2 - Diferença entre o "idIntegracao" e o "Código numérico que compõe a Chave de Acesso"
Diferentemente dos códigos do documento — onde o cNF é empregado nas NFe e NFCe, o cCT nos CTe e CTeOS, e o cMDF no MDFe —, os quais compõem a chave de acesso e são fundamentais para a validação e autenticidade dos documentos fiscais, o idIntegracao é utilizado exclusivamente para controle interno de comunicação entre as APIs da TecnoSpeed e o seu software, com o objetivo de identificar o documento que o seu software está tentando autorizar, no banco de dados da TecnoSpeed. Dessa forma, ele não interfere na formação da chave de acesso nem afeta os processos de emissão e validação dos documentos fiscais.
2.1 - Por que devo usar o "idIntegracao" para controlar meus envios em vez do "Código numérico da Chave de Acesso"?
- O "Código numérico da Chave de Acesso" pode se repetir em mais de um documento do mesmo modelo, o que pode gerar múltiplos registros em uma consulta feita por esse campo. Já o idIntegracao é único para cada documento dentro do mesmo modelo, garantindo um retorno preciso e sem duplicidades.
- O "Código numérico da Chave de Acesso" tem um tamanho padrão de 8 caracteres, pois sua função principal é evitar acessos indevidos ao documento. Por outro lado, o idIntegracao permite até 20 dígitos no ManagerSaas e até 50 no Plugnotas, possibilitando maior variação e controle. Além disso, o idIntegracao não interfere na geração da chave de acesso do documento, sendo utilizado exclusivamente para gerenciar os envios às APIs.
- Devido à limitação de 8 caracteres, o "Código Numérico da Chave de Acesso" possui um número reduzido de combinações possíveis em comparação com a quantidade de documentos fiscais eletrônicos que podem ser emitidos.
Para cada modelo de documento, é possível emitir até 999.999.999 documentos dentro de 999 séries distintas. No entanto, o "Código Numérico da Chave de Acesso" permite apenas 99.999.999 combinações, o que inevitavelmente resulta na repetição do código em mais de um documento.
- O uso do idIntegracao é especialmente recomendado para clientes que adotam o controle de numeração automática realizado pelos produtos da TecnoSpeed, pois ele facilita o rastreamento e o gerenciamento dos envios para a API, proporcionando mais organização e confiabilidade ao processo.
3 - Diferenças entre o idIntegracao no ManagerSaas e Plugnotas
No ManagerSaas, o campo idIntegracao é definido como um número inteiro, o que significa que somente valores numéricos podem ser armazenados. Esse campo aceita até 20 dígitos, proporcionando uma forma objetiva e direta de identificar e realizar operações matemáticas ou lógicas que envolvam esse identificador.
No Plugnotas, por sua vez, o campo idIntegracao é implementado como uma string, permitindo o armazenamento de sequências de caracteres. Com um tamanho máximo de até 50 caracteres, esse campo oferece maior flexibilidade, possibilitando a inclusão de letras, números e símbolos, o que pode atender a diferentes padrões e necessidades específicas de integração do sistema.
4 - Importância do idIntegracao ser único
Embora o preenchimento do idIntegracao não seja obrigatório, é fundamental que, caso ele seja utilizado, cada documento fiscal tenha um identificador único.
4.1 - Posso utilizar o mesmo idIntegracao para documentos diferentes?
Sim, você pode utilizar o mesmo idIntegracao para diferentes tipos de documentos. A validação ocorre de forma individual para cada documento. Portanto, se você enviou uma NFe com o idIntegracao X, não há impedimento para enviar um CTe utilizando o mesmo idIntegracao X.
No entanto, não é possível enviar duas NFes com o mesmo idIntegracao X. Nesse caso, o segundo envio não será processado. O envio de um idIntegracao repetido pode resultar nas seguintes exceções:
- Manager Saas
EXCEPTION, EspdManNFeAddNotasRepositorioException, Já existe uma NFe com o idIntegracao(1) informado para o CNPJ 99999999999999
EXCEPTION, EspdManNFCeAddNotasRepositorioException, Já existe uma NFCe com o idIntegracao(1) informado para o CNPJ 99999999999999
EXCEPTION;EspdManCTeAddNotasRepositorioException;Problema ao adicionar notas no repositório. Exception: Ja existe um CTe com o idIntegracao(1) informado para o CNPJ 99999999999999.
EXCEPTION;EspdManCTeOSAddNotasRepositorioException;Problema ao adicionar notas no repositório. Exception: Ja existe um CTeOS com o idIntegracao(1) informado para o CNPJ 99999999999999.
- Plugnotas
{
"error": {
"message": "Já existe uma NFe com os parâmetros informados",
"data": {
"new": {
"cnpj": "00000000000000",
"idIntegracao": "teste_idintegracao_123"
},
"current": {
"id": "68d74465260c1850d8393a18",
"idIntegracao": "teste_idintegracao_123",
"emissao": "03/09/2024",
"status": "CONCLUIDO",
"destinada": false,
"emitente": "00000000000000",
"destinatario": "00000000000000",
"valor": 30,
"dataAutorizacao": "03/09/2024",
"numero": "1",
"serie": "1",
"chave": "000000000000000000000000000000000000000000000",
"protocolo": "111270000541600",
"mensagem": "Autorizado o uso da NF-e",
"xml": "https://api.plugnotas.com.br/nfe/68d74465260c1850d8393a18/xml",
"pdf": "https://api.plugnotas.com.br/nfe/68d74465260c1850d8393a18/pdf",
"cStat": 100
}
}
}
}
Os documentos que receberem essas exceções não serão registrados em nossa base de dados, sendo necessário o reenvio com um novo valor no campo idIntegracao.
4.2 - Como evitar a repetição do idIntegracao?
Para garantir um controle mais eficiente e evitar falhas na integração, é recomendável utilizar o campo idIntegracao em todos os modelos de documentos fiscais. Com isso, cada transação recebe um identificador exclusivo dentro do seu respectivo modelo de documento, facilitando o rastreamento e a gestão correta dos registros.
Para evitar duplicidades, é importante adotar um controle interno que assegure a geração de identificadores únicos para cada documento fiscal. Algumas boas práticas para isso incluem:
Para clientes ManagerSaas:
- Utilizar um contador sequencial: Gere um número sequencial para cada documento fiscal emitido.
Para clientes Plugnotas:
- Basear-se em timestamp : Incorporar a data e hora na geração do identificador pode evitar duplicidades.
- Uso de UUIDs (Universally Unique Identifier): Essa abordagem garante que cada identificador gerado seja único globalmente.
5 - Conclusão
O campo idIntegracao é uma ferramenta valiosa para o controle interno da integração, mas seu uso requer atenção. Para evitar erros e garantir que os documentos fiscais sejam emitidos corretamente, cada um deve ter um identificador único. Ao seguir boas práticas e utilizar o idIntegracao em todos os modelos de documentos, você assegura um controle mais organizado, reduzindo o risco de duplicidades e falhas no processo.
Comentários
0 comentário
Por favor, entre para comentar.