> ## Documentation Index > Fetch the complete documentation index at: https://docs.veepag.com/llms.txt > Use this file to discover all available pages before exploring further. # Adicionar uma nova assinatura > Cria uma assinatura, gera a cobranca e tenta o pagamento imediato. A resposta confirma a assinatura criada e traz o resultado da tentativa de pagamento dentro de charge. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/subscription openapi: 3.1.1 info: title: Veepag API description: >- API publica da Veepag para transacoes, clientes, assinaturas, produtos, cobrancas e alertas. Autentique as chamadas com o header `apiKey` no formato `keyId.secret` ou com o header `token` contendo um JWT valido. Use o ambiente de sandbox para testes e producao apenas depois da homologacao. version: 1.0.0 contact: {} servers: - url: https://sandbox.api.veepag.com description: Sandbox - url: https://api.veepag.com description: Produção security: - api_key: [] - token: [] tags: - name: Transaction description: >- Pagamentos avulsos, captura, cancelamento, consulta e exportacao de transacoes. - name: Client description: Cadastro, atualizacao e consulta de clientes. - name: Subscription description: Criacao, consulta, atualizacao e cancelamento de assinaturas. - name: Product description: Configuracao de produtos, precos e regras de cobranca. - name: Charge description: Criacao, pagamento, cancelamento e conciliacao de cobrancas. - name: Alert description: Consulta e tratamento de alertas Ethoca/Visa. paths: /v1/subscription: post: tags: - Subscription summary: Adicionar uma nova assinatura description: >- Cria uma assinatura, gera a cobranca e tenta o pagamento imediato. A resposta confirma a assinatura criada e traz o resultado da tentativa de pagamento dentro de charge. operationId: SubscriptionController_createV1 parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionV1Dto' example: companyId: company_id product: id: product_id paymentMethod: CREDIT_CARD installments: 1 client: name: Cliente Teste doc: '12345678909' email: cliente@example.com paymentProfile: holderName: CLIENTE TESTE cardNumber: '4111111111111111' cardExpiration: 10/2026 cardCvv: '123' metadata: externalOrderId: pedido_123 responses: '201': description: Assinatura criada e pagamento tentado. content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionV1Response' example: id: subscription_id transactionId: - transaction_id status: ACTIVE paymentMethod: CREDIT_CARD charge: statusCode: 200 amount: value: 9900 currency: BRL status: PAID message: Pagamento aprovado acquirer: {} qrCode: null boleto: null nextCharge: '2026-07-23T12:00:00.000Z' '400': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error_messages: - msg: Payload invalido. type: field path: companyId location: body code: ZodValidationException path: /v1/subscription metadata: {} '401': description: Credencial ausente ou invalida. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error_messages: - msg: Unauthorized. code: unauthorized path: /v1/subscription metadata: {} '403': description: Credencial sem acesso ao recurso ou empresa solicitada. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error_messages: - msg: Forbidden. code: forbidden path: /v1/subscription metadata: {} '500': description: Erro interno nao mapeado. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error_messages: - msg: Unknown server error. code: unknown_server_error path: /v1/subscription metadata: {} security: - api_key: [] - token: [] components: schemas: CreateSubscriptionV1Dto: type: object properties: referenceId: type: - string - 'null' description: Referencia externa da sua aplicacao para a assinatura. origin: type: string enum: - API - CHECKOUT - IMPORTED - AFFILIATE x-enumNames: - API - CHECKOUT - IMPORTED - AFFILIATE default: API description: Origem da criacao da assinatura, quando informada. captchaToken: type: string description: Token de captcha usado em fluxos que exigem captcha. companyId: type: string minLength: 1 description: ID da empresa da assinatura. metadata: type: object additionalProperties: {} description: Metadados livres para conciliacao e suporte. product: type: object properties: id: type: string minLength: 1 required: - id description: Objeto com o ID do produto usado na assinatura v1. paymentMethod: type: string enum: - CREDIT_CARD - DEBIT_CARD - BOLETO - PIX x-enumNames: - CREDIT_CARD - DEBIT_CARD - BOLETO - PIX description: Meio de pagamento usado na tentativa inicial. paymentProfile: type: object properties: holderName: type: string cardExpiration: type: string cardNumber: type: string cardCvv: type: string description: Dados de pagamento, obrigatorios para cartao. cardAuthId: type: - string - 'null' description: ID de autorizacao de cartao, quando usado no fluxo. client: type: object properties: referenceId: type: string name: type: string minLength: 1 doc: type: string minLength: 1 cpf: type: string minLength: 1 birth: type: string type: type: - string - 'null' enum: - INDIVIDUAL - COMPANY x-enumNames: - INDIVIDUAL - COMPANY email: type: string format: email phone: type: array items: type: string note: type: string address: type: object properties: street: type: string number: type: string additionalDetails: type: string complement: type: string zipcode: type: string neighborhood: type: string city: type: string state: type: string country: type: string device: type: object properties: colorDepth: type: number javaEnable: type: boolean language: type: string screenHeight: type: number screenWidth: type: number timezoneOffset: type: number userAgent: type: - string - 'null' javaEnabled: type: boolean ipAddress: type: string required: - name description: Dados do cliente enviados inline para criar a assinatura v1. installments: type: integer exclusiveMinimum: 0 default: 1 description: Quantidade de parcelas da assinatura. affiliateId: type: - string - 'null' description: ID do afiliado vinculado, quando houver. url: type: string description: URL relacionada ao fluxo, quando informada. required: - companyId - product - paymentMethod - installments CreateSubscriptionV1Response: type: object properties: id: type: string example: subscription_id description: Identificador da assinatura criada. transactionId: type: array items: type: string example: - transaction_id description: Lista de transacoes criadas durante a tentativa de pagamento. status: $ref: '#/components/schemas/SubscriptionStatus' description: Status atual da assinatura depois da tentativa de cobranca. nextCharge: type: string format: date-time description: Proxima data de cobranca da assinatura, quando disponivel. paymentMethod: $ref: '#/components/schemas/PaymentMethod' description: Meio de pagamento usado na tentativa. charge: type: object properties: statusCode: type: integer example: 200 description: >- Resultado da tentativa de pagamento: 200 para pagamento aprovado ou 402 para pagamento nao aprovado. amount: type: object properties: value: type: number example: 9900 currency: type: string example: BRL description: Valor processado na tentativa. status: $ref: '#/components/schemas/ChargeStatus' description: Status da cobranca depois da tentativa de pagamento. message: type: string description: Mensagem retornada pelo fluxo de pagamento ou pela adquirente. acquirer: type: object additionalProperties: true description: Dados retornados pela adquirente, quando disponiveis. qrCode: type: - string - 'null' description: Dados de Pix, quando o meio de pagamento gerar QR Code. boleto: type: - string - 'null' description: Dados de boleto, quando o meio de pagamento gerar boleto. description: >- Resultado da cobranca e da tentativa de pagamento feita pelo endpoint v1. ErrorResponse: type: object properties: error_messages: type: array items: $ref: '#/components/schemas/ErrorMessage' code: type: string example: unauthorized path: type: string example: /v1/transaction metadata: type: object additionalProperties: true SubscriptionStatus: type: string enum: - ACTIVE - ERROR_PAYMENT - NO_PAYMENT_ROUTE - CREATED - PENDING_PAYMENT - RECOVERED - NO_PAYMENT - CANCELED_ALERT_ETHOCA - BLOCKED - CANCELED_MANUAL - IMPORTED - STANDBY - OVERDUE PaymentMethod: type: string enum: - CREDIT_CARD - DEBIT_CARD - BOLETO - PIX ChargeStatus: type: string enum: - PAID - ACTIVE - ANTICIPATED - CANCELED - CANCELED_ALERT_ETHOCA - PENDING_PAYMENT - IMPORTED - ERROR_PAYMENT - ERROR_REFUNDED - OVERDUE - NO_PAYMENT_ROUTE - RECOVERED - BLOCKED - NO_PAYMENT - CANCELED_MANUAL - DISPUTE - CHARGEBACK - STANDBY - DISABLED ErrorMessage: type: object properties: msg: type: string example: Unauthorized. type: type: string example: field path: type: string example: companyId location: type: string example: body securitySchemes: api_key: type: apiKey in: header name: apiKey description: API key no formato keyId.secret. token: type: apiKey in: header name: token description: JWT valido. O token confirmado na codebase tem validade de 14 dias. ````