Os sistemas que estão integrados aos processos batch da plataforma CobranSaaS podem iniciar a importação das informações dos diferentes tipos de entidade (agrupadores, produtos, clientes, contratos etc) disponíveis na plataforma através dos métodos assíncronos da Batch API específicos para cada tipo de entidade.
A lista de registros a serem importados deverá obrigatoriamente ser informada no formato JSON (JavaScript Object Notation), sendo que cada registro deverá ser informado, individualmente, em uma única linha do arquivo contendo todos os seus atributos e cada linha deverá ser sintaticamente válida em relação ao formato JSON pois, por questões de otimização de performance, o processo batch de importação carrega e processa apenas um registro (linha) por vez, verificando se o conteúdo individual de cada registro (linha) é sintaticamente válido em relação ao formato JSON. Portanto, o conteúdo de cada linha do arquivo, individualmente, deve ser sintaticamente válido em relação ao formato JSON, embora o conteúdo completo do arquivo, por sua vez, não deva ser sintaticamente válido em relação ao formato JSON, uma vez que não deverão ser incluídos os caracteres de início de lista ("[") no início dos arquivos, nem os caracteres separadores de elementos de lista (",") após cada registro (linha), nem o caractere de final de lista ("]") no final do arquivo, conforme pode ser observado nos arquivos JSON de exemplo de importação disponibilizados neste guia.
Os métodos assíncronos de importação da API permitem que a lista de registros a serem importados seja informada no corpo (body) da requisição como uma string, recurso que, no entanto, deve ser utilizado somente no caso de importação de poucos registros, e também permitem que a lista de registros a serem importados seja informada no corpo (body) da requisição como um arquivo para upload, recurso que deve ser utilizado no caso de importação de quantidades maiores de registros.
Os atributos que deverão constar obrigatoriamente ou opcionalmente nos registros a serem importados estão descritos na documentação do método a ser utilizado para a importação de cada tipo de entidade.
O atributo id (Id Externo), de preenchimento obrigatório em todos os tipos de entidade, exceto nos tipos de entidade bloqueios e desbloqueios que não possuem este atributo, sempre deverá ser informado com a chave única de identificação do registro no sistema de origem da informação. É através do conteúdo deste atributo id que a plataforma determina, durante o processamento da importação, quais registros deverão ser inseridos (INSERT) e quais registros deverão ser atualizados (UPDATE) na base de dados da plataforma. Registros que estiverem sendo importados com ids que ainda não existem serão inseridos na base de dados da plataforma e registros que estiverem sendo importados com ids já existentes serão atualizados na base de dados da plataforma.
Além de possibilitar que registros sejam inseridos ou atualizados, apenas os métodos assíncronos de importação dos tipos de entidade aplicações, contratos, notas fiscais e saldos também possibilitam que registros possam ser excluídos (DELETE) da base de dados da plataforma desde que, na URL da chamada dos respectivos métodos, sejam informados os parâmetros de entrada full e comparador, que são de preenchimento opcional. O parâmetro de entrada full é do tipo Boolean e deverá ser informado com o conteúdo true para que a importação do tipo de entidade em questão seja assumida como completa, de forma que todos os registros contidos no arquivo sendo importado serão inseridos ou atualizados na base de dados da plataforma e todos os registros já existentes na base de dados da plataforma mas que não existirem no arquivo que estiver sendo importado serão excluídos da base de dados da plataforma, desde que o conteúdo do atributo id (Id Externo) dos registros existentes na base de dados da plataforma atenda ao critério de comparação informado através do parâmetro de entrada comparador. Se o parâmetro de entrada full for informado com o conteúdo true então a informação do parâmetro de entrada comparador será obrigatória e, caso o mesmo não seja informado, um código de erro 400 (ver Tratamento de Erros no link seudominio.cobransaas.com.br/#/docs-api/introducao/tratamento-erros) será retornado com a mensagem "O comparador deve ser informado quando for importação full".
Exemplos de utilização do parâmetro de entrada comparador: se for informado com o conteúdo "CC_%", então somente os registros cujos conteúdos dos ids externos iniciarem com o prefixo "CC_" é que serão excluídos caso não existam no arquivo sendo importado; se for informado com o conteúdo "%_CC", então somente os registros cujos conteúdos dos ids externos terminarem com o sufixo "_CC" é que serão excluídos caso não existam no arquivo sendo importado; e se for informado com o conteúdo "%CC%", então somente os registros cujos conteúdos dos ids externos possuírem "CC", independentemente da posição, é que serão excluídos caso não existam no arquivo sendo importado.
Para informar a lista de registros a serem importados através de um arquivo para upload, o parâmetro de entrada file deverá ser informado, obrigatoriamente, com o arquivo a ser importado que, por sua vez, poderá opcionalmente estar compactado no padrão ZIP, opção fortemente recomendada principalmente na importação de grandes quantidades de registros, por questões de otimização de performance. Se o arquivo informado não for válido, um código de erro 400 (ver Tratamento de Erros no link seudominio.cobransaas.com.br/#/docs-api/introducao/tratamento-erros) será retornado com a mensagem "O arquivo não foi informado corretamente".
Se a importação for iniciada com sucesso através da chamada ao método assíncrono da Batch API específico para o tipo da entidade sendo importada, será retornado um código de status 200 (OK), a resposta padrão para requisições HTTP bem sucedidas e, neste caso, o método retorna, no atributo id, o identificador do processo batch correspondente à importação cuja execução foi iniciada. No atributo dataCriacao o método retorna a data e hora de criação do processo batch e no atributo situacao o método retorna a situação da execução do processo batch que, neste caso, sempre será "INICIANDO".
Uma vez que todos os métodos de importação da Batch API são assíncronos, o andamento e a conclusão da execução do processo batch correspondente à importação cuja execução foi iniciada poderão ser verificados, utilizando o atributo id que for retornado pelo método específico da Batch API para o tipo da entidade sendo importada, conforme descrito em Obtendo Informações sobre o Processamento das Importações e em Obtendo os Registros Ignorados nas Importações.
Exemplos de chamada e de retorno dos métodos da Batch API para cada tipo de entidade importada constam na pasta Batch API do arquivo Processos Batch.postman_collection.json e exemplos de arquivos de importação para cada tipo de entidade constam no arquivo Processos Batch.Importação.zip, disponíveis como anexos em Integrando Sistemas com os Processos Batch.
0 Comentários