Guias

Saldo

Pode consultar o saldo, o histórico de movimentos e os documentos fiscais tanto pela API como pelo MCP. O pagamento por cartão - pontual ou automático - passa sempre por uma ligação do Stripe Checkout que uma pessoa conclui; a própria API nunca debita um cartão por iniciativa própria. O mesmo se aplica ao plano mensal opcional.

Dinheiro sem IVA, hellers, o idioma das descrições

Todos os montantes desta API são números inteiros em HELLERS (centésimos de coroa checa) e sem IVA - a volai é sujeito passivo de IVA, mas o IVA só é calculado quando carrega o saldo por cartão (ver /cenik). As descrições dos movimentos (GET /v1/credit/ledger) são compostas pela API em português a partir do tipo de movimento - a nota checa guardada nunca sai, em nenhum campo.

Saldo, autonomia e avisos

GET /v1/balance devolve o saldo atual e, ADICIONALMENTE, dois cálculos extra (os clientes existentes que só leem balanceHal/balanceCzk/currency não são afetados): runway (dailyAverageHal - a média diária de gasto recente, runwayDays - durante quantos dias o saldo dura a este ritmo, null quando não é possível calcular) e notice - o mesmo aviso que vê na página de visão geral do portal, null quando não existe nenhum. Oito formatos possíveis de notice: {kind:"unknown"} (dados insuficientes para estimar), {kind:"empty"} (saldo zero), {kind:"number_fee",feeHal,dueAt} (uma mensalidade de números de voz ou números de telemóvel vence nos próximos 3 dias e o saldo não a cobre; feeHal é a soma de todas essas mensalidades, dueAt o vencimento mais próximo; não é devolvido enquanto o carregamento automático estiver ativo), {kind:"runway",days} (o saldo esgota-se dentro de days dias ao ritmo atual) e quatro formatos apenas numa conta com plano mensal: {kind:"subscription_exhausted_topup",renewsAt} (o saldo mensal deste período está esgotado e o plano funciona em modo de carregamento, pelo que o consumo seguinte é pago com saldo carregado; renewsAt é o fim do período em ms, quando chega o saldo mensal seguinte), {kind:"subscription_cap_reached",renewsAt} (o saldo mensal está esgotado, o plano funciona com limite e o saldo carregado não cobre nada, pelo que as ações pagas param até renewsAt ou até carregar manualmente) e {kind:"subscription_past_due"} (a renovação do plano falhou, não foi possível debitar o cartão guardado; pague a renovação no portal ou substitua o cartão) e {kind:"subscription_runway",renewsAt,runsOutAt} (o saldo esgota-se antes de chegar o saldo mensal seguinte em renewsAt; runsOutAt é a estimativa em ms, feita ao ritmo prudente do plano, o mesmo da previsão do saldo mensal no cartão do plano no portal: o mais alto entre a média de 28 dias (apenas com histórico de saldo completo), a utilização média nos últimos 7 dias de Praga sem mensalidades de números e a média desde o início do período (após a sua primeira semana); runway mantém a média de 28 dias; um subscritor recebe este formato em vez de runway, e nada enquanto o carregamento automático estiver ativo). renewsAt está em ms (epoch), o mesmo momento que subscription.periodEnd na mesma resposta, onde é uma string ISO 8601; o formato de nenhum dos campos muda. Num plano definido para terminar após o período pago, subscription_exhausted_topup, subscription_cap_reached e subscription_runway trazem também cancelAtPeriodEnd: true: não se segue renovação, renewsAt é o fim do plano e não é adicionado novo saldo mensal (com limite só pode continuar carregando); sem o cancelamento o campo não consta do aviso. Numa conta com plano mensal, a resposta traz ainda subscription (o estado do plano, caso contrário null) e topupBalanceHal (apenas o saldo carregado); balanceHal continua a ser a soma do saldo mensal e do saldo carregado, ver o capítulo Plano mensal.

Histórico de movimentos

GET /v1/credit/ledger?limit - do mais recente para o mais antigo, SEM cursor (apenas limit, 1-200, por omissão 50) - não existe cursor, pelo que só os 200 movimentos mais recentes são acessíveis pela API; a página /kredit do portal e os documentos fiscais têm o histórico completo. Cada entrada traz type (bonus, topup, call_out, call_in, sms, number_fee, agent, refund, admin, setup_revision - uma ronda de revisão adicional numa encomenda de configuração chave na mão além do que o pacote inclui, subscription_grant - o crédito do saldo mensal do plano e subscription_expire - o fim da validade do seu resto por utilizar), amountHal (positivo para um crédito, negativo para um débito), grossHal (o montante com IVA num carregamento por cartão, null nos restantes casos) e uma description em português composta a partir do tipo - em number_fee, também com o número a que a mensalidade se refere. Um débito coberto pelo saldo mensal traz ainda fromSubscriptionHal - a parte do débito paga pelo saldo mensal; os outros movimentos não têm este campo. O complemento número de telemóvel aparece no histórico como number_fee (o primeiro período na compra do número e cada renovação passados 30 dias) e sms (uma mensagem enviada de um número de telemóvel, à tarifa por segmento da página de preços); quando o operador rejeita mais tarde um SMS enviado de um número de telemóvel, o saldo regressa como uma entrada refund.

Carregamento por cartão

POST /v1/credit/topup {amountCzk} devolve {checkoutUrl} - uma ligação do Stripe Checkout que uma PESSOA abre num navegador. Nada é debitado até ela concluir o pagamento. É necessário um endereço de faturação completo (PUT /v1/account/billing) ANTES da chamada - sem ele não é possível emitir um documento fiscal válido (billing_address_required). Suporta Idempotency-Key - é seguro repetir após um timeout sem criar dois pagamentos.

Carregamento automático

Pela API, o carregamento automático só pode ser LIDO, DESATIVADO e ter o seu LIMIAR alterado - ativá-lo e alterar o MONTANTE passam exclusivamente pelo Stripe Checkout, nunca por escrita direta.

Leitura e desativação

GET /v1/credit/auto-topup devolve {enabled, thresholdHal, amountHal, card: {brand, last4} | null, spentThisMonthHal, monthlyCapHal, disabledReason} - SEM o número do cartão, apenas a marca e os últimos quatro dígitos. PATCH {enabled: false} desativa-o de imediato, PATCH {thresholdHal} só altera o limiar (tem de ser um dos valores oferecidos e inferior ao montante guardado, caso contrário o saldo voltaria a cair abaixo do limiar logo após um carregamento).

Ativação e alteração do montante

POST /v1/credit/auto-topup/setup {thresholdHal, amountHal} devolve {checkoutUrl} - concluir o Checkout debita DE IMEDIATO amountHal como primeiro carregamento, e só isso guarda o cartão para futuros carregamentos automáticos. Funciona mesmo com um cartão já guardado anteriormente - é a única forma de ativar o carregamento automático ou de alterar o seu montante. Após o Checkout, o navegador regressa à página CHECA do portal (/kredit?automat=zapnuto) mesmo para um cliente que usa português - uma lacuna conhecida, não um erro da sua integração.

Cartão

POST /v1/credit/auto-topup/card devolve uma ligação do Checkout (modo de configuração, nada é debitado) para substituir o cartão guardado. DELETE /v1/credit/auto-topup/card desassocia o cartão DE IMEDIATO - toda a configuração é eliminada (limiar e montante incluídos), não apenas o cartão; voltar a ativar só funciona através de .../setup, que debita logo um primeiro carregamento. Após o Checkout, o navegador regressa à página CHECA do portal (/kredit?karta=zmenena), independentemente do idioma da conta - a mesma lacuna conhecida que acima.

Limites

Dois limites INDEPENDENTES: no máximo 10 000 CZK de montante creditado por mês civil e no máximo 4 carregamentos por DIA civil - independentemente de quantas vezes o saldo desça abaixo do limiar. Exceder qualquer um deles desativa automaticamente o carregamento automático (disabledReason monthly_cap ou daily_cap); spentThisMonthHal/monthlyCapHal na resposta mostram quanto resta do limite mensal.

MCP: get_auto_topup (leitura) e disable_auto_topup (desativar) - ativar, alterar o montante e o cartão não estão no MCP, pelo mesmo motivo de enabled: true no REST acima.

Limite mensal de despesa

Uma salvaguarda opcional contra uma fatura inesperadamente elevada: define quanto podem custar as chamadas, os SMS e o agente de voz num mês civil (hora de Praga). A funcionalidade só está ativa numa conta que definiu um limite; sem ele nada muda e a despesa do mês é apenas contabilizada.

GET /v1/account/spend-cap devolve {spendCap: {enabled, capHal, warnShare, inboundAboveCap, month, monthSpendHal, remainingHal, reached, updatedAt}}. Sem limite, enabled é false e os campos do limite são null, mas recebe sempre monthSpendHal. Os montantes estão em hellers inteiros sem IVA.

PUT /v1/account/spend-cap {capHal, warnShare?, inboundAboveCap?} define ou altera o limite: capHal é em hellers inteiros de 5 000 (50 CZK) a 100 000 000 (1 000 000 CZK), warnShare é a fração do limite de 0,5 a 0,99 (por omissão 0,8) em que é enviado o e-mail de aviso, e inboundAboveCap: true mantém os agentes a atender chamadas recebidas acima do limite (por omissão false; numa alteração sem o campo mantém-se o valor guardado). DELETE /v1/account/spend-cap remove o limite; remover um limite que não está definido não é problema.

Quando o limite é atingido, as novas chamadas efetuadas, toques, chamadas de teste e SMS são recusados com spend_cap_reached (HTTP 402), nada é debitado e repetir não ajuda até o mês terminar ou até aumentar ou remover o limite. Uma chamada recebida por um agente termina após uma frase e não custa nada, a menos que inboundAboveCap seja true. É enviado um e-mail quando warnShare é atingido e quando o limite é atingido, cada um no máximo uma vez por mês.

O que o limite NÃO impede: chamadas já em curso (o preço é debitado após a chamada, pelo que o mês pode terminar acima do limite pelo preço delas, bem como por chamadas agendadas após a meia-noite), o reencaminhamento sem agente, e as mensalidades de números, a ronda Chave na mão e o plano mensal, que não contam para o limite. Numa conta com plano mensal, a despesa coberta pelo saldo mensal também conta. Um número no modo de central SIP própria com inboundAboveCap: true permanece no proxy SIP, pelo que o limite não impede as chamadas efetuadas a partir da central.

MCP: get_spend_cap, set_spend_cap e clear_spend_cap chamam o mesmo serviço que o REST e o portal (a secção Limite mensal de despesa em Saldo). set_spend_cap faz o agente repetir o montante ao cliente antes e depois de guardar.

Plano mensal

Uma subscrição opcional: todos os meses o preço do nível escolhido é debitado do cartão guardado e é creditado um saldo mensal em CZK, que se gasta segundo a tabela de preços normal. As tarifas e a faturação por segundo não mudam, o plano é uma camada por cima delas. Existem três níveis e tier é o seu preço em CZK sem IVA: "490", "990" e "1990"; o preço e o saldo de cada nível são devolvidos por GET /v1/subscription no campo tiers.

Dois tipos de saldo

O saldo mensal provém do plano, expira no fim do período e não é reembolsável. O saldo carregado (carregamentos, bónus de boas-vindas, ajustes) não expira e é reembolsável como antes. O saldo da conta - balanceHal em GET /v1/balance, no portal e em todas as verificações (mínimo para uma chamada, limite de dívida, avisos) - é a soma dos dois tipos. O saldo carregado isolado está em topupBalanceHal, o saldo mensal restante em subscription.monthlyRemainingHal. Só pode surgir dívida no saldo carregado.

Ordem de consumo

Cada débito é pago primeiro com o saldo mensal e o restante com o saldo carregado - chamadas por segundo, o agente, as mensalidades de números e de números de telemóvel, SMS, toques de portão e chamadas efetuadas de tarefas. A repartição é atómica e fica registada no histórico: um débito coberto pelo saldo mensal traz fromSubscriptionHal (a parte paga pelo saldo mensal). Os ajustes do proprietário (admin, incluindo os negativos) e o reembolso de um SMS não enviado (refund) afetam apenas o saldo carregado.

Período e crédito

Um período dura um mês a partir do débito bem-sucedido (31 de janeiro dá 28 de fevereiro). O saldo mensal só é creditado depois de o pagamento ser confirmado, com uma entrada subscription_grant, e o crédito é idempotente pelo identificador do pagamento. Se nesse momento a conta tiver uma dívida no saldo carregado, esta é primeiro liquidada com o novo saldo mensal, para que o saldo carregado não fique negativo.

Expiração

O resto por utilizar do saldo mensal expira no dia da renovação (uma entrada subscription_expire com montante negativo), quando a subscrição termina, ou por uma verificação de segurança automática quando um período terminou há mais de 36 horas sem renovação. Se o débito falhar, o resto já expirou e não é adicionado novo saldo; até ser pago, a conta funciona apenas com saldo carregado.

Escolha após o esgotamento

A ativação do plano exige um exhaustionMode, sem valor por omissão. topup: quando o saldo mensal se esgota, é comprado saldo carregado a partir do cartão guardado - é o carregamento automático de hoje, com os mesmos limites e e-mails. cap: nada é comprado, as chamadas efetuadas, os SMS e as compras de números são recusados com subscription_cap_reached (HTTP 402) e, com o saldo abaixo de zero, param também as chamadas recebidas, o reencaminhamento e o acesso SIP (paragem a zero; retoma depois de carregar o saldo ou com o novo saldo mensal). O carregamento automático não pode ser ativado com limite (subscription_cap_active); mudar para o limite desativa-o. O máximo que paga num mês com limite é o preço do plano.

Mudar de nível, cancelar, renovar

Uma mudança de nível (para cima ou para baixo) tem efeito a partir do período seguinte, sem ajuste. Cancelar é cancelAtPeriodEnd: true: o saldo mantém-se válido até ao fim do período, depois expira e o estado passa a canceled; um cancelamento pode ser anulado até ao fim do período. Por REST e MCP não pode subir de nível, renovar um plano cancelado nem passar à compra a partir do cartão - esses passos aumentam ou reiniciam débitos recorrentes, pelo que devolvem subscription_confirmation_required com um confirmUrl que uma pessoa abre e confirma no portal (válido durante 24 horas).

Aviso antes da renovação

Três dias antes da renovação (o mais tardar um dia antes) chega um e-mail, mas só quando pagar ao segundo ou um nível inferior custaria menos com a sua despesa até ao momento. Aplica-se a mesma regra que para o aviso no e-mail de renovação e no portal: outra opção tem de ser mais barata em pelo menos 50 CZK e 5 %. A estimativa para todo o período usa o mais alto entre o ritmo desde o início do período e nos últimos 7 dias, e nunca é inferior aos últimos 30 dias de despesa a partir dos quais o portal aconselha, pelo que, após o clique, as linhas Nível do plano e Cancelar plano nunca respondem que o seu nível é adequado. O e-mail indica a data e a hora exatas da renovação e chega no máximo uma vez por período, nunca para um plano cancelado no fim do período, com uma mudança de nível agendada, sem cartão guardado ou a aguardar pagamento. O seu botão abre a linha Cancelar plano (/kredit?pausal=zrusit) ou a linha Nível do plano (/kredit?pausal=stupen) no portal. O e-mail de renovação volta então a aconselhar com base na despesa real de todo o período, pelo que o conselho pode diferir.

Renovação não paga

O débito no cartão guardado é tentado no dia da renovação, após 2 dias e após 4 dias. Após a primeira falha, o estado é past_due, um e-mail traz uma ligação para pagar manualmente e alterar o cartão, e o saldo mensal é 0; POST /v1/subscription/pay devolve a ligação de pagamento manual. Após a terceira falha, o plano termina (canceled) e o saldo carregado e a conta continuam a funcionar.

IVA e documentos fiscais

Os preços não incluem IVA. O regime de IVA é lido antes de cada débito, pelo que um pagador de outro país da UE com um NIF-IVA verificado paga sem IVA checo (autoliquidação) e o documento reflete-o. A própria volai emite um documento fiscal por cada período pago (a base tributável é o preço do nível, não o saldo adicionado) e encontra-o em GET /v1/billing/documents.

Relação com o bónus e o primeiro carregamento

Ativar o plano conta como primeiro pagamento: desbloqueia o SMS a partir do remetente partilhado, o reencaminhamento, um segundo número, um número de telemóvel e o cartão de carregamento automático, tal como um carregamento. O bónus de boas-vindas continua a ser saldo carregado.

Reembolsos

O saldo mensal não é reembolsável e expira; o saldo carregado é reembolsável como antes. Cancelar o plano não dá direito a uma parte proporcional do período pago. O reembolso de um pagamento do plano (uma reclamação, um erro) é tratado manualmente pelo proprietário da volai, não pela API nem pelo MCP.

O plano por REST e MCP

O dinheiro só se move com uma pessoa junto ao cartão. Ativar o plano e pagar manualmente apenas devolvem uma ligação do Stripe Checkout e nunca debitam o cartão diretamente; subir de nível, retomar um plano definido para terminar e passar a carregamentos a partir do cartão precisam da confirmação de uma pessoa com sessão iniciada no portal.

• GET /v1/subscription - o estado do plano (subscription ou null), o catálogo de níveis tiers (id, priceHal, creditHal), topupBalanceHal, available (é possível iniciar um novo plano: a oferta está ativa e não há nenhum plano em curso), recommendation (a forma mais barata de pagar pelos últimos 30 dias de despesa e steady, se a despesa é contínua e não um pico pontual; null sem oferta ou sem 30 dias de histórico) e previousPeriod (o último período com os mesmos valores que o e-mail de renovação: usedHal de creditHal, usedPercent, a despesa além do saldo mensal overHal e o que expirou expiredHal; apenas enquanto o plano está ativo, null no primeiro período e quando o histórico de saldo não consegue comprovar a utilização).
• POST /v1/subscription/checkout {tier, exhaustionMode, consumerConsent?} - devolve um {checkoutUrl} para o Stripe Checkout; o plano começa quando este é concluído. exhaustionMode (topup ou cap) é obrigatório; um consumidor sem número de empresa tem de enviar consumerConsent: true (caso contrário consumer_consent_required). O endereço de faturação tem de estar completo (billing_address_required). Suporta Idempotency-Key.
• PATCH /v1/subscription {tier?, cancelAtPeriodEnd?, exhaustionMode?} - descer de nível, cancelar (cancelAtPeriodEnd: true) e passar ao limite (exhaustionMode: "cap") são aplicados e devolvem {subscription}. Subir de nível, retomar um plano definido para terminar (cancelAtPeriodEnd: false) e exhaustionMode: "topup" não alteram nada e devolvem 409 subscription_confirmation_required com um confirmUrl.
• POST /v1/subscription/pay - apenas no estado past_due; devolve um {checkoutUrl} para pagar a renovação manualmente. Suporta Idempotency-Key.
• POST /v1/subscription/card - devolve um {checkoutUrl} para substituir o cartão guardado do plano, nada é debitado. Suporta Idempotency-Key.
• GET /v1/balance traz também subscription (o mesmo formato que acima, caso contrário null) e topupBalanceHal.

MCP: get_subscription (leitura), create_subscription_link (uma ligação para ativar), update_subscription e cancel_subscription (descer de nível, cancelar, limite; subir, renovar e comprar a partir do cartão devolvem um confirmUrl com uma frase a dizer que uma pessoa tem de o confirmar no portal) e create_subscription_payment_link (pagamento manual). Não existe substituição de cartão no MCP, pelo mesmo motivo que no carregamento automático: daqui nada é debitado.

Documentos fiscais

Um documento é emitido automaticamente num carregamento de saldo por cartão (pontual ou automático), no pagamento de uma configuração chave na mão e como documento retificativo num reembolso de configuração - sem passo manual, sem emissão pela API.

GET /v1/billing/documents?limit&before - do mais recente para o mais antigo, o cursor before (Unix ms, exclusivo) é o nextBefore da página anterior. O armazenamento subjacente nunca devolve mais de 100 registos por chamada, mesmo que limit peça mais.

GET /v1/billing/documents/{id} devolve {id, number, issuedAt, taxableAt, netHal, vatHal, grossHal, vatRatePercent, reverseCharge, description, customer, paymentRef, pdfUrl} - reverseCharge: true para pagadores de outro país da UE com um NIF-IVA verificado no VIES, que pagam sem IVA checo. O campo kind está sempre preenchido - "invoice" para um documento normal (incluindo os emitidos antes de o campo existir), "credit_note" para um documento retificativo - emitido automaticamente quando o fundador reembolsa a taxa de uma encomenda de configuração chave na mão cancelada, numerado na sua própria série OD..., com correctsNumber (o número do documento original) e correctionReason (porque foi reembolsado) adicionados; netHal/vatHal/grossHal são POSITIVOS mesmo numa nota de crédito, o sinal de menos só é acrescentado no PDF.

GET /v1/billing/documents/{id}/pdf descarrega o mesmo documento como application/pdf - é gerado de novo em cada descarga, não é guardado. Um id alheio ou inexistente comunica o mesmo erro (invoice_not_found) nos dois endpoints, pelo que a resposta não pode revelar que existe um documento de outra pessoa.

MCP: list_billing_documents e get_billing_document têm o mesmo formato que o REST. O PDF existe apenas no REST - o MCP não tem canal binário para transferir um ficheiro.

Erros

• ledger_unavailable - Não foi possível ler agora o histórico de movimentos ou o saldo - tente novamente dentro de instantes.
• invalid_amount - O montante do carregamento, do limiar ou do carregamento automático não é um dos valores fixos oferecidos.
• billing_address_required - O endereço de faturação falta ou está incompleto - adicione-o no portal (/nastaveni) antes de carregar, caso contrário não é possível emitir um documento válido.
• stripe_not_configured - Os pagamentos estão desativados nesta instalação da volai - não é específico do seu pedido.
• stripe_error - O Stripe recusou criar uma sessão de pagamento - tente novamente dentro de instantes.
• autotopup_not_configured - O carregamento automático nunca passou por .../setup - não há nada para desativar, alterar ou cujo cartão substituir.
• invoice_not_found - Não existe nenhum documento com este id na conta (ou pertence a outra conta - a resposta é a mesma).
• spend_cap_reached - O limite mensal de despesa que definiu foi atingido: as novas chamadas efetuadas e os SMS são recusados e nada é debitado. Aumente ou remova o limite com PUT ou DELETE /v1/account/spend-cap, caso contrário mantém-se até ao fim do mês (meia-noite em Praga).
• subscription_cap_reached - O limite do plano: o saldo mensal e o saldo carregado estão ambos esgotados e a conta escolheu o limite. As chamadas efetuadas, os SMS e as compras de números são recusados (HTTP 402) até à próxima renovação ou a um carregamento manual.
• subscription_exists - A conta já tem um plano; a mudança de nível, o cancelamento e a escolha após o esgotamento passam por PATCH /v1/subscription.
• subscription_missing - A conta não tem nenhum plano ativo que possa ser alterado, cancelado ou pago manualmente.
• subscription_canceled - O plano já terminou (estado canceled): já não pode ser alterado, cancelado nem pago manualmente. Inicie um novo com POST /v1/subscription/checkout.
• subscription_confirmation_required - Subir de nível, retomar um plano definido para terminar e comprar a partir do cartão só são confirmados por uma pessoa no portal - a resposta traz um confirmUrl e nada foi alterado.
• consumer_consent_required - Um consumidor sem número de empresa tem de confirmar, ao ativar o plano, um pedido expresso de início do serviço antes de expirar o prazo de livre resolução (consumerConsent: true).
• pausal_unavailable - A oferta do plano está atualmente desativada para esta conta.
• invalid_tier - O nível que o plano já tem quando não há outro nível agendado (um nível para o qual já está a mudar não é um erro e conta como concluído, pelo que o mesmo PATCH /v1/subscription pode ser enviado de novo após uma falha; a exceção é voltar ao nível atual, o que cancela a mudança agendada: uma repetição já não tem nada para cancelar); um valor desconhecido fora de "490", "990", "1990" termina como validation.
• subscription_cap_active - O carregamento automático não pode ser ativado com limite; primeiro mude a escolha após o esgotamento para topup no portal.
• validation - Especificamente em PATCH /v1/credit/auto-topup: uma tentativa de o ativar (enabled: true) ou de alterar amountHal diretamente - use antes POST .../setup.

A tabela completa de erros de todos os endpoints está na secção Saldo da referência da API REST.