> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Importar assinaturas > Importe assinaturas existentes para a Chargefy preservando o período atual e a próxima cobrança, sem cobrar novamente o que já foi pago. Este guia mostra como importar assinaturas que já existem em outro sistema de cobrança — ativas, em período de teste ou canceladas. Assinaturas ativas entram com o período real preservado, **sem** cobrar novamente o período atual. A Chargefy assume a cobrança a partir do **próximo ciclo**. Para assinaturas ativas ou em período de teste, você não precisa do cartão do cliente para importar. Sem cartão, a assinatura fica em `send_invoice`: no próximo ciclo a Chargefy gera uma fatura em aberto, e o cartão pode ser coletado depois. Assinaturas canceladas entram apenas como histórico e não geram cobrança. A importação é acionada quando você envia `backdate_start_date` no `POST /v1/subscriptions`, sempre com `proration_behavior: "none"`. Isso é o que diz à Chargefy: "não cobre o período atual, só assuma daqui pra frente". ## As três formas de importar | O estado da assinatura na origem | Campo que você envia | Como ela nasce na Chargefy | | -------------------------------- | ----------------------------------------- | ---------------------------- | | Ativa | `billing_cycle_anchor` (próxima cobrança) | `active` | | Em período de teste | `trial_end` (fim do trial) | `trialing` | | Já cancelada (histórico) | `canceled_at` (data do cancelamento) | `canceled` (registro inerte) | ## Passo a passo Cada assinatura precisa de um customer. Se você ainda não trouxe seus clientes, crie-os primeiro e guarde no seu banco a relação entre o ID da origem e o `cus_*` retornado. ```bash theme={"theme":"css-variables"} curl -X POST "https://api.chargefy.io/v1/customers" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Idempotency-Key: cliente_legado_42" \ -H "Content-Type: application/json" \ -d '{ "email": "ana@exemplo.com", "name": "Ana Souza", "metadata": {} }' ``` A assinatura aponta para um `price` recorrente. Cadastre seus preços uma vez (ou envie `price_data` inline no item, se preferir não manter um catálogo). ```bash theme={"theme":"css-variables"} curl -X POST "https://api.chargefy.io/v1/prices" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "product": "prod_MR4Wsq1PN633CAEv", "currency": "brl", "unit_amount": 9900, "recurring": { "interval": "month" } }' ``` O preço precisa ter a mesma moeda e o mesmo ciclo da assinatura que você vai importar. Uma assinatura mensal em BRL só aceita um preço mensal em BRL. Envie a assinatura com as datas reais do seu sistema. Use o **id da assinatura na origem** como `Idempotency-Key`: assim, se você repetir a importação, a mesma assinatura nunca é duplicada. ```bash theme={"theme":"css-variables"} curl -X POST "https://api.chargefy.io/v1/subscriptions" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Idempotency-Key: assinatura_legada_987" \ -H "Content-Type: application/json" \ -d '{ "customer": "cus_GHvNJie3UpSB8a68", "items": [{ "price": "price_rb78CHEQPo13Gahd" }], "backdate_start_date": "2026-06-16T18:00:00Z", "billing_cycle_anchor": "2026-07-16T18:00:00Z", "proration_behavior": "none", "metadata": {} }' ``` A resposta volta com a assinatura já `active`, `latest_invoice` em `null` (nenhuma cobrança foi feita) e o período preservado. Para os outros estados, troque `billing_cycle_anchor` pelo campo correspondente: ```bash Em trial theme={"theme":"css-variables"} curl -X POST "https://api.chargefy.io/v1/subscriptions" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Idempotency-Key: assinatura_legada_988" \ -H "Content-Type: application/json" \ -d '{ "customer": "cus_GHvNJie3UpSB8a68", "items": [{ "price": "price_rb78CHEQPo13Gahd" }], "backdate_start_date": "2026-06-26T18:00:00Z", "trial_end": "2026-07-10T18:00:00Z", "proration_behavior": "none" }' ``` ```bash Já cancelada (histórico) theme={"theme":"css-variables"} curl -X POST "https://api.chargefy.io/v1/subscriptions" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Idempotency-Key: assinatura_legada_989" \ -H "Content-Type: application/json" \ -d '{ "customer": "cus_GHvNJie3UpSB8a68", "items": [{ "price": "price_rb78CHEQPo13Gahd" }], "backdate_start_date": "2026-05-02T18:00:00Z", "canceled_at": "2026-06-21T18:00:00Z", "proration_behavior": "none" }' ``` Nada é cobrado no momento da importação. Na data que você informou como âncora (`billing_cycle_anchor`, ou o fim do trial), a Chargefy gera a primeira fatura do novo ciclo automaticamente: * **Sem cartão** (`send_invoice`): a fatura nasce em aberto e cobrável. A assinatura continua `active`. Envie o link de pagamento ao cliente ou colete um cartão antes da próxima cobrança. * **Com cartão** (`charge_automatically`): a Chargefy cobra automaticamente. Assinaturas importadas como `canceled` são apenas histórico: não geram cobrança, job nem webhook. ## De-para das datas | No seu sistema atual | Campo na importação | Vira na Chargefy | | ----------------------------------- | ---------------------------------------------- | --------------------------------------- | | Início do período atual (já pago) | `backdate_start_date` | `current_period_start`, `start_date` | | Próxima cobrança | `billing_cycle_anchor` | `current_period_end`, `next_billing_at` | | Fim do trial (se em trial) | `trial_end` | `current_period_end` | | Data do cancelamento (se cancelada) | `canceled_at` | `canceled_at`, `ended_at` | | ID da assinatura na origem | `Idempotency-Key` + relação salva no seu banco | idempotência + correlação | ## Regras de validação A importação recusa datas incoerentes com um erro `400` claro, sem criar nada: | Regra | Motivo | | ------------------------------------------- | --------------------------------------------------- | | `backdate_start_date` deve estar no passado | É quando o período atual começou. | | `billing_cycle_anchor` deve estar no futuro | É a próxima cobrança. | | `trial_end` deve estar no futuro | O trial ainda está rodando. | | `canceled_at` deve estar no passado | A assinatura já foi cancelada. | | `proration_behavior` deve ser `none` | Confirma que o período atual não é cobrado de novo. | ## Boas práticas * Use o **id da assinatura na origem** como `Idempotency-Key`. A importação em lote pode ser repetida sem criar duplicatas. Veja [requisições idempotentes](/api-reference/idempotency). * Ao receber a resposta, guarde no seu banco a relação entre o ID da origem e o `sub_*` retornado pela Chargefy. * Importe com antecedência: evite importar muito perto da próxima cobrança, para ter tempo de coletar o cartão antes do primeiro ciclo na Chargefy. ## Próximos passos Contrato completo do `POST /v1/subscriptions`, incluindo os campos de importação. Como o header `Idempotency-Key` torna a importação em lote segura. Traga seus clientes antes de importar as assinaturas. Cadastre os preços recorrentes que as assinaturas vão usar.