Criar Assinatura com ou sem plano

Este endpoint deve ser utilizado para a criação de assinaturas ou contratos recorrentes no sistema. A API oferece flexibilidade total, permitindo que as recorrências sejam geradas de duas maneiras distintas:

Com Plano Atrelado: Utiliza um plano como um template pré-definido, facilitando a padronização das cobranças. Nesse modelo, características fundamentais como a duração (determinada ou indeterminada) e a periodicidade já vêm configuradas de fábrica.
Sem Plano Atrelado (Manual): Permite a criação de uma recorrência customizada diretamente na requisição, sem a necessidade de ter um plano previamente cadastrado no sistema.

Para criar uma assinatura com ou sem plano, é necessário ter um token válido e utilizar o endpoint Criar Assinatura com ou sem plano.

1. Parâmetros de URL

Campo	Tipo	Obrigatório	Descrição
`account`	`integer`	Sim	Identificação numérica da Conta Digital BaaS no ecossistema Celcoin onde a assinatura será gerenciada.

2. Parâmetros do Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`planGalaxPayId`	`integer`	Não	ID único do plano cadastrado. Nota: Para criar uma assinatura personalizada sem plano, não informe esse campo.
`firstPayDayDate`	`string (date)`	Sim	Data prevista para a realização do primeiro pagamento da assinatura (Formato: `YYYY-MM-DD`).
`additionalInfo`	`string`	Não	Campo de texto livre dedicado ao preenchimento de observações ou informações adicionais de controle interno.
`mainPaymentMethodid`	`string`	Sim	Identificador do meio de pagamento principal considerado para a geração de cobranças. Valores válidos: `creditcard` (Cartão de Crédito), `boleto` (Boleto Bancário), `pix` (Pix).
`Customer`	`object`	Sim	Objeto contendo o agrupamento dos dados cadastrais e fiscais do cliente.

3. Objeto Customer (Informações do Cliente)

Campo	Tipo	Obrigatório	Descrição
`Customer.myId`	`string`	Sim	Identificador de referência única do cliente dentro do seu próprio sistema de controle (máx. 255 caracteres).
`Customer.galaxPayId`	`integer`	Não	ID exclusivo do cliente existente no banco de dados. Atenção: Para cadastrar um cliente novo, este campo NÃO deve ser passado.
`Customer.name`	`string`	Sim	Nome completo ou razão social do cliente pagador (máx. 255 caracteres).
`Customer.document`	`string`	Sim	Documento de identificação oficial do cliente (CPF ou CNPJ). Enviar estritamente apenas números (máx. 14 caracteres).
`Customer.emails`	`array of strings`	Sim	Lista de e-mails para contato e envio de notificações ao cliente (máx. 255 caracteres por string).
`Customer.phones`	`array of integers`	Não	Lista contendo os telefones de contato cadastrados para o cliente (máx. 11 dígitos por número).
`Customer.invoiceHoldiss`	`boolean`	Não	Flag indicativo utilizado para definir se haverá a retenção do imposto ISS na geração da nota fiscal.
`Customer.municipalDocument`	`string`	Não	Número de inscrição municipal do cliente associado (máx. 255 caracteres).
`Customer.password`	`string`	Não	Código de segurança/senha dedicado para o acesso externo ao painel de pagamentos (máx. 255 caracteres).
`Customer.Address`	`object`	Condicional	Estrutura de endereço do cliente. > Regra de Validação: Torna-se obrigatória caso o `mainPaymentMethodid` selecionado seja `boleto`.

4. Objeto Customer.Address (Endereço do Cliente)

Campo	Tipo	Obrigatório	Descrição
`Customer.Address.zipCode`	`string`	Sim	Código de Endereçamento Postal (CEP). Preencher obrigatoriamente apenas com números (8 caracteres).
`Customer.Address.street`	`string`	Sim	Nome do logradouro público ou rua do endereço fornecido (máx. 255 caracteres).
`Customer.Address.number`	`string`	Sim	Número físico correspondente ao imóvel do cliente (máx. 255 caracteres).
`Customer.Address.complement`	`string`	Não	Dados complementares associados ao local (ex: número do apartamento, bloco, andar; máx. 255 caracteres).
`Customer.Address.neighborhood`	`string`	Sim	Nome do bairro de localização do endereço informado (máx. 255 caracteres).
`Customer.Address.city`	`string`	Sim	Nome do município do endereço do cliente (máx. 255 caracteres).
`Customer.Address.state`	`string`	Sim	Código de sigla padrão da Unidade Federativa correspondente ao Estado (2 caracteres).

5. Objeto PaymentMethodCreditCard & Card (Dados de Cartão)

Campo	Tipo	Obrigatório	Descrição
`PaymentMethodCreditCard`	`object`	Condicional	Configurações do meio de pagamento por cartão. > Regra de Validação: Obrigatório se o `mainPaymentMethodid` for `creditcard`.
`PaymentMethodCreditCard.Card`	`object`	Não	Estrutura contendo as especificações do cartão de crédito. Nota: Se o objetivo for gerar um link de pagamento externo, não preencha este nó.
`PaymentMethodCreditCard.Card.myId`	`string`	Não	ID interno do cartão de crédito mapeado dentro do seu sistema próprio (máx. 255 caracteres).
`PaymentMethodCreditCard.Card.galaxPayId`	`integer`	Não	ID numérico identificador do cartão já existente salvo no banco de dados.
`PaymentMethodCreditCard.Card.hash`	`string`	Não	Hash seguro gerado a partir do processo de tokenização do cartão via Javascript. Nota: Se informado, os demais campos abertos de dados do cartão serão ignorados.
`PaymentMethodCreditCard.Card.number`	`string`	Sim	Número sequencial impresso no cartão de crédito físico (máx. 30 caracteres).
`PaymentMethodCreditCard.Card.holder`	`string`	Sim	Nome completo impresso do titular do cartão de crédito. Não aceita o envio de acentuações ou caracteres especiais (máx. 30 caracteres).
`PaymentMethodCreditCard.Card.expiresAt`	`string`	Sim	Mês e ano indicativos de expiração da validade do cartão de crédito (Formato obrigatório: `YYYY-MM`).
`PaymentMethodCreditCard.Card.CVV`	`string`	Sim	Código de Verificação do Cartão (CVV) ou código impresso de segurança (máx. 4 caracteres).

6. Objeto Antifraud (Configurações de Antifraude)

Campo	Tipo	Obrigatório	Descrição
`Antifraud`	`object`	Não	Agrupamento de dados de hardware e rastreamento de rede usados para a análise securitária do antifraude.
`Antifraud.ip`	`string`	Sim	Endereço de protocolo de internet IP (IPv4 ou IPv6) associado ao cliente originador (máx. 40 caracteres).
`Antifraud.sessionId`	`string`	Não	String de identificação única gerada para controle da sessão ativa de navegação do usuário (máx. 255 caracteres).
`Antifraud.Device`	`object`	Não	Objeto de propriedades técnicas que detalham o dispositivo físico/máquina do cliente comprador.
`Antifraud.Device.fingerprint`	`string`	Sim	Impressão digital (fingerprint) do navegador utilizada para detecção (mín. 3 e máx. 255 caracteres).
`Antifraud.Device.provider`	`string`	Não	Nome do provedor ou operadora de serviços de rede fornecedora do acesso (mín. 2 e máx. 255 caracteres).
`Antifraud.Device.model`	`string`	Não	Modelo nominal de fábrica do aparelho comercial empregado (máx. 255 caracteres).
`Antifraud.Device.platform`	`string`	Não	Especificação da plataforma operacional de sistema ativa utilizada pelo cliente pagador.
`Antifraud.Device.manufacturer`	`string`	Não	Empresa fabricante original do hardware do equipamento (mín. 2 e máx. 255 caracteres).
`Antifraud.Device.OS`	`string`	Não	Sistema operacional nativo instalado (ex: `Windows`; mín. 2 e máx. 255 caracteres).
`Antifraud.Device.colorDepth`	`string`	Sim	Valor da profundidade estimada da paleta de cores de exibição de tela informada em bits por pixel.
`Antifraud.Device.deviceType3ds`	`string`	Sim	Indica a tipologia do canal de dispositivo no qual a validação ocorrerá (ex: `BROWSER`).
`Antifraud.Device.javaEnabled`	`boolean`	Sim	Resposta booleana indicativa se o navegador atual do cliente possui suporte e execução de Java ativos.
`Antifraud.Device.language`	`string`	Sim	Idioma padrão configurado no browser do cliente seguindo o formato de especificação IETF BCP47.
`Antifraud.Device.screenHeight`	`string`	Sim	Dimensão de altura total da resolução de tela do dispositivo medida em pixels (`screen.height`).
`Antifraud.Device.screenWidth`	`string`	Sim	Dimensão de largura total da resolução de tela do dispositivo medida em pixels (`screen.width`).
`Antifraud.Device.timeZoneOffset`	`string`	Sim	Valor de diferença de fuso horário expressada em horas computadas entre a hora local do browser e o UTC.
`Antifraud.Device.redirectUrl3ds`	`string (uri)`	Sim	Endereço URL absoluto de redirecionamento para onde o cliente retornará pós-desafio de autenticação.

7. Objeto Payment (Informações de Resposta do Gateway)

Campo	Tipo	Obrigatório	Descrição
`Payment`	`object`	Não	Nó contendo informações complementares e respostas transacionais detalhadas oriundas do gateway de pagamento.
`Payment.browser`	`string`	Não	Identificação nominal e versão do software de navegação utilizado no momento exato do envio.
`Payment.bin`	`string`	Não	Identificação inicial da numeração — corresponde aos primeiros 6 a 10 caracteres numéricos do cartão.
`Payment.last4`	`string`	Não	Sequência composta estritamente pelos 4 últimos dígitos finais identificadores do cartão de crédito.
`Payment.amount`	`number`	Não	Valor monetário nominal total cobrado na respectiva transação gerada.
`Payment.expirationDate`	`string`	Não	Data de expiração da validade atribuída ao cartão informada no formato estrito `MMAAAA`.
`Payment.description`	`string`	Não	Histórico descritivo complementar de informações associadas à concessão de descontos aplicáveis.
`Payment.taxId`	`string`	Não	CPF atribuído ao portador legítimo do cartão de crédito enviado nas etapas de processamento (máx. 11 dígitos).
`Payment.cvvResult`	`string`	Não	String com o código de resultado obtido na verificação de integridade dos dígitos de segurança CVV.
`Payment.avsResult`	`string`	Não	Código obtido no retorno do procedimento de checagem do Address Verification Service (AVS).
`Payment.sha1`	`string`	Não	Token de validação de integridade composto por assinatura HMAC-SHA-256 dos dados da notificação.
`Payment.name`	`string`	Não	Identificação nominal do comprador informada nas etapas do fluxo do gateway de processamento.
`Payment.holder`	`string`	Não	Nome impresso do portador titular do cartão enviado nas mensagens de liquidação (máx. 100 caracteres).
`Payment.cardOperatorId`	`string`	Não	Operadora/Adquirente financeira responsável direta pelo tráfego de dados do cartão (ex: `cielo`, `rede`, `getnet`).
`Payment.useBackupCard`	`boolean`	Não	Resposta lógica sobre a autorização de uso do cartão reserva em caso de falha de cobrança.
`Payment.preAuthorize`	`boolean`	Não	Se configurado como `true`, indica que o valor da transação será somente autorizado, sem captura automática.
`Payment.embedded`	`boolean`	Não	Especifica se o componente MPI de autenticação é nativo da adquirente Rede (`true`) ou externo (`false`).
`Payment.threeDIndicator`	`string`	Sim	Versão da plataforma de segurança e autenticação 3DS operacionalizada no fluxo MPI.
`Payment.cavv`	`string`	Sim	Cardholder Authentication Verification Value. Código criptográfico de autenticação enviado pelo MPI.
`Payment.eci`	`string`	Sim	Electronic Commerce Indicator. Parâmetro informando o status final do processo de autenticação junto ao emissor.
`Payment.xid`	`string`	Sim	Identificador exclusivo da transação de autenticação fornecido pelo MPI (específico para bandeiras Visa).
`Payment.directoryServerTransactionId`	`string`	Sim	ID transacional gerado pelo servidor do ecossistema de segurança do cartão no processamento do 3DS.

8. Objeto Split (Divisão de Recebíveis)

Campo	Tipo	Obrigatório	Descrição
`Split`	`object`	Não	Configurações dedicadas à divisão de liquidações (Split) entre contas do ecossistema.
`Split.creditcard`	`object`	Não	Regras e direcionamentos de split para pagamentos processados via Cartão de Crédito.
`Split.pix`	`object`	Não	Regras e direcionamentos de split para pagamentos processados via Pix.
`Split.boleto`	`object`	Não	Regras e direcionamentos de split para pagamentos processados via Boleto Bancário.
`Split.all`	`object`	Não	Regras gerais de split unificadas aplicadas de forma padrão a todas as modalidades aceitas.
`Split.[meio].type`	`string`	Sim	Metodologia de cálculo para a divisão de valores. Opções suportadas: `percent` (porcentagem) ou `fixed` (valor fixo).
`Split.[meio].Companies`	`array of objects`	Sim	Lista de parceiros ou subcontas configuradas para o recebimento do split de pagamento.
`Split.[meio].Companies.[i].numberAccount`	`integer`	Sim	ID numérico da conta digital parceira cadastrada para o recebimento do split.
`Split.[meio].Companies.[i].value`	`integer`	Sim	Fração financeira destinada. Enviar valor em centavos (se `fixed`) ou em formato percentual com duas casas decimais sem separador (se `percent`).

9. Objeto InvoiceConfig (Configuração de Nota Fiscal Eletrônica)

Campo	Tipo	Obrigatório	Descrição
`InvoiceConfig`	`object`	Não	Estrutura de configuração para automatização das emissões fiscais de Notas Fiscais de Serviço.
`InvoiceConfig.description`	`string`	Sim	Descrição textual e detalhada da natureza da prestação do serviço que constará no documento impresso.
`InvoiceConfig.smu`	`integer`	Não	Código SMU correspondente à atividade do serviço prestado segundo a regulamentação municipal aplicável.
`InvoiceConfig.type`	`string`	Sim	Periodicidade das emissões. O valor obrigatório aceito é `onePerTransaction` (uma Nota Fiscal por transação).
`InvoiceConfig.createOn`	`string`	Sim	Evento gatilho determinante da emissão (`daysBeforePayDay`, `payment`, `creation`, `notificationSend`, `daysAfterPayment`).
`InvoiceConfig.qtdDaysBeforePayDay`	`integer`	Sim	Janela de dias prévios ao vencimento para a geração da nota. Obrigatório caso `createOn` seja igual a `daysBeforePayDay` (1 a 30).
`InvoiceConfig.qtdDaysAfterPay`	`integer`	Sim	Janela de dias após a liquidação do pagamento para a emissão. Obrigatório caso `createOn` seja igual a `daysAfterPayment` (1 a 30).
`InvoiceConfig.galaxPaySubAccount`	`integer`	Não	Identificação de conta do estabelecimento filial para faturamento. Utilizado em estruturas Matriz/Filial.