Arquivo de cobranças em lote

Introdução

Este documento tem como objetivo especificar os modelos e campos dos arquivos.csv enviados para o gs-charge com a finalidade de cadastro/edição em lote de cobranças.
Os tópicos abaixo descrevem a estrutura do arquivo de cadastro e de atualização de cobranças em lote.

1 - Nomenclatura e Convenções

O arquivo possui formato .CSV, não deve conter espaçamento entre campos, o seprador entre cada campo será 'ponto e vírgula' e caso o campo seja múltiplos valores, utiliza como separador interno 'vírgula'.
O arquivo não conterá header ou trailer e o seu processamento deve ser considerado linha a linha até o final do arquivo. Cada linha contém exclusivamente dados de uma cobrança.
O arquivo pode ser composto de linhas de cadastro de cobranças e de edição de cobranças.
Os retornos de erros de processamento de arquivo e status do processamento estão listados nas tabelas nº 4 e 5.

2 - Modelo de cadastro de cobranças

O modelo descrito nos itens abaixo é referente ao cadastro de cobranças.

2.1 - Descrição dos Campos Contidos no Arquivo

Para todas as cobranças a serem criadas via arquivo, devem seguir o seguinte formato abaixo. Em caso de campos não obrigatórios, deve ser enviado o campo vazio ou escrito 'nulo', visando sempre ter 12(doze) campos por cobrança.

⚠️⚠️ATENÇÃO⚠️⚠️: Os campos abaixo expressados como não obrigatórios é devido os seguintes cenários:

O campo 05 é opcional, não é necessário o vínculo de um perfil a uma cobrança;
O campo 08 somente deve ser preenchido caso cobrança seja do tipo Charge;
Os campos 06, 07, 09 e 10 somente são opcionais caso esses valores já se encontrem cadastrados dentro do perfil encontrado pelo Identificador único no campo 05;
O dado do campo 06 faz-se necessário o envio mesmo em cobranças 007, 008, 009 e 010, nesses casos deve ser enviado zerado.
Caso os campos 05, 06, 07, 09 e 10 forem passados juntos, ao criar a cobrança será dado prioridade aos valores fora do perfil.
Os campos 11 e 12 somente devem ser utilizados no caso de edição de cobranças!

ID	NOME DO CAMPO	Obrigatório	DESCRIÇÃO
01	Tipo de cobrança	✅	Conforme tabela nº1
02	Descrição	✅	Descrição da cobrança, máximo 50 caracteres
03	Dados da loja	✅	Documento e Descrição da loja
04	Dados do Desconto	✅	tipo do desconto(Conforme tabela nº2) e valor do desconto
05	ID do perfil	❌	Identificador único do perfil de cobrança
06	Meta de vendas do terminal	❌	Meta de vendas do terminal para isenção
07	Tipo de recorrêcia	❌	Conforme tabela nº3
08	Dados do terminal	❌	código do terminal, gsurf terminal id, número de série e modelo (consultar documentação MTM)
09	Tempo de carência	❌	Número de dias de carência onde não será cobrado o uso do terminal
10	Valor da cobrança	❌	Valor da cobrança em centavos
11	ID da cobrança	❌	Identificador único da cobrança a ser editada
12	Status da cobrança	❌	Status da cobrança

Nota: Em valores expressando grandezas monetárias ou percentuais, faz-se necessário o envio do campo no formato RealCentavo. Exemplo de 10(dez) reais, os centavos devem vir juntos, sem pontuação sendo 1000.
Já no caso de 10(dez) reais e 50(cinquenta) centavos espera-se 1050 e no caso de 10(dez) centavos basta 10. No caso das porcentagens, 10% (dez porcento) deve vir 1000, se fossem 10,5% seriam 1050 e meio porcento apenas 50.

Nota 2: Quaisquer campo descritivo, não deve utilizar acentuação e 'Ç' (cedilha);

2.2 - Exemplo de arquivo:

Dados para exemplo arquivo csv.

Exemplo cobrança de terminal com todos os campos:

`csv`

csv 006;descricao da cobranca;0123456789,descricao da loja;NOMINAL,1000;0a22e7b0-2601-4d0a-a381-3eddbefcc485;10099;RECURRENCE;123,456,789,modelo terminal;10;20000;;
Nota: Neste caso os dados dos campos 06, 07, 09 e 10 serão prioritários ao encontrar o perfil(campo 05) e os campos 11 e 12 não são utilizados pois são para edição de cobranças.

Exemplo cobrança de terminal apenas com perfil:

`csv`

csv 006;descricao da cobranca;0123456789,descricao da loja;NOMINAL,1000;0a22e7b0-2601-4d0a-a381-3eddbefcc485;;;123,456,789,modelo terminal;;;;
Nota: Neste caso foram passados apenas os valores obrigatórios, tendo como premissa que os demais dados estão corretamente cadastrados dentro do perfil informado. Os campos que não foram preenchidos ainda são enviados, porém vazios e separados por 'ponto e vírgula'.

Exemplo cobrança sem terminal:

`csv`

csv 007;descricao da cobranca;0123456789,descricao da loja;NOMINAL,1000;0a22e7b0-2601-4d0a-a381-3eddbefcc485;10099;RECURRENCE;;10;20000;;
Nota: Neste caso os dados do campo 08 (dados do terminal) não são enviados pois a cobrança foi do tipo 007(Pinpad).

Exemplo arquivo

3 - Modelo de atualização de cobranças

O modelo descrito nos itens abaixo é referente ao cadastro de cobranças.

Nota: Não é possível atualizar o cadastro de cobranças já com o status CANCELED!

3.1 - Descrição dos Campos Contidos no Arquivo

Para todas as cobranças a serem atualizadas via arquivo, devem seguir o seguinte formato abaixo. Em caso de campos não obrigatórios, deve ser enviado o campo vazio ou escrito 'nulo', visando sempre ter 12(doze) campos por cobrança. Como é utilizado a mesma estrutura de arquivo assim, como a de cadastro, alguns campos não devem ser enviados, conforme abaixo.

⚠️⚠️ATENÇÃO⚠️⚠️: Alguns campos abaixo expressados como não obrigatórios ou não enviar é devido os seguintes cenários:

O campo 05 é opcional, não é necessário o vínculo de um perfil a uma cobrança;
Os campos 01, 03, 07 e 08 não devem ser enviado para o cenário de atualização de cobranças;
Os campos 06, 09 e 10 somente são opcionais caso esses valores já se encontrem cadastrados dentro do perfil encontrado pelo Identificador único no campo 05;
Caso os campos 05, 06, 09 e 10 forem passados juntos, ao atualizar a cobrança será dado prioridade aos valores fora do perfil.

ID	NOME DO CAMPO	Obrigatório	DESCRIÇÃO
01	Tipo de cobrança	⚠️	Não enviar
02	Descrição	❌	Descrição da cobrança, máximo 50 caracteres
03	Dados da loja	⚠️	Não enviar
04	Dados do Desconto	❌	tipo do desconto(Conforme tabela nº2) e valor do desconto
05	ID do perfil	❌	Identificador único do perfil de cobrança
06	Meta de vendas do terminal	❌	Meta de vendas do terminal para isenção
07	Tipo de recorrêcia	⚠️	Não enviar
08	Dados do terminal	⚠️	Não enviar
09	Tempo de carência	❌	Número de dias de carência onde não será cobrado o uso do terminal
10	Valor da cobrança	❌	Valor da cobrança em centavos
11	ID da cobrança	✅	Identificador único da cobrança a ser editada
12	Status da cobrança	❌	Status da cobrança

Nota 2: Quaisquer campo descritivo, não deve utilizar acentuação e 'Ç' (cedilha);

3.2 - Exemplo de arquivo:

Dados para exemplo arquivo csv.

Exemplo cobrança de terminal com todos os campos:

`csv`

csv ;descricao da cobranca;;NOMINAL,1000;0a22e7b0-2601-4d0a-a381-3eddbefcc485;10099;;;10;20000;0a22e7b0-2601-4d0a-a381-3eddbefcc654;ACTIVE
Nota: Neste caso os dados dos campos 06, 09 e 10 serão prioritários ao encontrar o perfil(campo 05) e os campos 11 e 12 são utilizados para edição de cobranças.

Exemplo cobrança de terminal apenas com perfil:

`csv`

csv ;;;;0a22e7b0-2601-4d0a-a381-3eddbefcc485;;;;;;0a22e7b0-2601-4d0a-a381-3eddbefcc654;
Nota: Neste caso foram passados apenas os identificadores únicos, do perfil e da cobrança, tendo como premissa que os dados desejáveis a serem atualizados estão contidos dentro do perfil, já préviamente cadastrado de forma correta. Os campos que não foram preenchidos ainda são enviados, porém vazios e separados por 'ponto e vírgula'.

Exemplo arquivo

4 - Tabelas

Abaixo seguem tabelas referidas acima na documentação, contendo valores variantes de cada campo

Tabela 1 – Tipos de cobrança

Identificador	Descrição do tipo de cobrança
006	Charge: Cobrança normal, vinculada a um terminal.
007	Pinpad: Cobrança sem vínculo de terminal.
008	Smart POS: Cobrança sem vínculo de terminal.
009	Property Insurance: Cobrança sem vínculo de terminal.
010	Health Care: Cobrança sem vínculo de temrinal.

Tabela 2 – Tipos de Desconto

Identificador	Descrição do tipo de desconto
NOMINAL	Nominal, o valor real do desconto.
PERCENT	Percentual, o valor percentual do desconto.

Tabela 3 – Tipos de recorrência

Identificador	Descrição do tipo de recorrência
RECURRENCE	Recorrente, será recriada todo mês.
UNIQUE	Única, não será recriada.

Tabela 4 – Tipos de status de processamento

Identificador	Descrição do tipo de status
NEW	Novo, ainda não processado.
INVALID_TYPE	Tipo inválido.
INVALID_SIZE	Tamanho inválido.
INVALID_HASH	Hash inválido.
INTERNAL_ERROR	Erro interno do servidor.
INFECTED_FILE	Arquivo infectado.
INVALID_LAYOUT	Layout inválido.
PROCESSED	Processado.

Tabela 5 – Tipos de erros de processamento

Identificador	Descrição do tipo de erro de processamento
Failed to parse the row, expected 12 columns but received X.	linha com nº de colunas incorreto.
Failed to parse row, cannot receive charge_type with charge_id or status.	Recebido campos tipo de cobrança com identificador único da cobrança e/ou status da cobrança.
Discount value cannot be negative.	Valor do disconto negativo.
Merchant description is required.	Descrição de loja requerida.
The following fields are required when profile is not provided: waiting_period, amount, recurrence or habituality_amount	Campos período de carência, valor, recorrência ou valor de meta não foram providenciadas sem perfil.
Provided profile not found.	Perfil providenciado não encontrado.
X is required	Perfil encontrado, porém período de carência, valor, recorrência e/ou meta não encontrados.
Terminal data provided to charge type X	Dado de terminal provido para tipo de cobrança diferente de "006"(cobrança de terminal).
Terminal already in use by other merchant.	Terminal já cadastrado com cobrança ativa.
Discount Data cannot be null.	Dado de desconto não providenciado.
Invalid length for discount data.	Total de campos de dado de disconto diferente de dois.
Merchant Data cannot be null	Dados da loja nulo.
Invalid length for merchant data.	Total de cmapos de dado de loja diferente de dois.
Invalid merchant document	Documento de loja inválido.
Invalid length for terminal data.	Total de campos de dado de terminal diferente de quatro.
Failed to parse habituality_amount	Falha ao tratar valor fornecido de meta.
Habituality amount value cannot be negative.	Valor de meta negativo.
Failed to parse amount	Falha ao tratar valor fornecido de valor da cobrança.
Amount value cannot be negative.	Valor de cobrança negativo.
Failed to parse waiting_period	Falha ao tratar valor de período de carência.
Waiting period value cannot be negative.	Valor de período de carência negativo.
Provided charge not found.	Cobrança fornecida não encontrada.
Cannot edit CANCELED charge.	Não é possível editar cobrança CANCELADA.
The following provided field is invalid to update charge, field: charge_type.	Tipo de cobrança fornecido ao tentar atualizar cobrança.
The following provided field is invalid to update charge, field: terminal_data.	Dado de terminal fornecido ao tentar atualizar cobrança.
The following provided field is invalid to update charge, field: recurrence.	Recorrência fornecida ao tentar atualizar cobrança.
The following provided field is invalid to update charge, field: merchant_data.	Dado de loja fornecido ao tentar atualizar cobrança.