Importação de Entidades via Batch API

Os sistemas integrados aos processos batch da plataforma CobranSaaS podem iniciar a importação de diferentes tipos de entidades (agrupadores, produtos, clientes, contratos, etc.) por meio de métodos assíncronos da Batch API específicos para cada categoria.

A lista de registros deve ser informada obrigatoriamente no formato JSON. Cada registro deve ocupar uma única linha do arquivo, contendo todos os seus atributos. É essencial que cada linha, individualmente, seja um JSON sintaticamente válido. Por questões de otimização de performance, o processo carrega e processa apenas um registro por vez, validando o conteúdo de cada linha de forma isolada.

Atenção à estrutura do arquivo: embora cada linha precise ser um JSON válido, o arquivo como um todo não deve seguir a sintaxe de uma lista global. Isso significa que você não deve incluir o colchete de início ([), nem o de fechamento (]), e não deve utilizar vírgulas para separar os registros ao final de cada linha. Você pode conferir este modelo nos arquivos de exemplo disponibilizados neste guia.

A API oferece duas formas de envio no corpo (body) da requisição:

1. Como String: Recomendado apenas para a importação de poucos registros.

2. Como Arquivo (Upload): Recurso obrigatório para grandes volumes de dados. Neste caso, deve-se utilizar o parâmetro file, sendo altamente recomendável que o arquivo esteja compactado no padrão ZIP para melhorar a performance.

Os atributos obrigatórios e opcionais de cada entidade estão detalhados na documentação de cada método. O atributo id (ID Externo) é de preenchimento obrigatório para quase todos os tipos (exceto bloqueios e desbloqueios) e deve conter a chave única de identificação do sistema de origem. É por meio deste id que a plataforma decide a ação a ser tomada:

• IDs novos: O registro será inserido (INSERT).

• IDs já existentes: O registro será atualizado (UPDATE).

Para as entidades de aplicações, contratos, notas fiscais e saldos, também é possível realizar a exclusão de registros (DELETE). Para isso, devem ser utilizados os parâmetros opcionais full e comparador na URL da chamada:

• O parâmetro full (booleano) define se a importação é "completa". Se definido como true, todos os registros do arquivo serão inseridos ou atualizados, e qualquer registro que já esteja na base de dados, mas que não conste no arquivo, será excluído (desde que o seu id atenda ao critério do comparador).

• Se o parâmetro full for true, o uso do comparador torna-se obrigatório. Caso não seja informado, o sistema retornará um Erro 400.

• Exemplos do comparador: CC_% exclui IDs que começam com "CC_"; %_CC exclui IDs que terminam com "_CC"; e %CC% exclui qualquer ID que contenha "CC" em qualquer posição.

Ao iniciar uma importação com sucesso, a API retornará o status 200 (OK). O retorno incluirá o id (identificador do processo batch), a dataCriacao e a situacao (que inicialmente será "INICIANDO"). Como os métodos são assíncronos, você deve utilizar o id recebido para acompanhar o andamento e a conclusão do processamento, conforme as orientações de monitoramento da documentação.

Exemplos práticos de chamadas e arquivos de importação estão disponíveis nos anexos Processos Batch.postman_collection.json e Processos Batch.Importação.zip.