Ir para a documentação
SparkGlimDeveloper
Centro de integração com IA
SparkGlimSparkGlim Programadores
Pesquisar em toda a documentação

Experimente um tema na sua língua ou um caminho API exato.

    Navegação da documentação

    Referência API

    Iniciar pagamento de votos

    Valida campanha e nomeado, inicia pagamento existente e reutiliza operação em repetições; o servidor regista votos concluídos.

    POSThttps://api.sparkglim.net/api/white-label/v1/votes/initialize

    Modelo de acesso

    Modelo de acesso
    HMAC de Organização no servidor
    Âmbito necessário
    payments:write
    Disponibilidade documentada
    Implementado no código

    Disponibilidade verificada no código, sem garantia de produção.

    A assinatura privada fica no servidor. A API Versão 1 usa assinatura v2; não é uma API v2.

    Cabeçalhos

    NomeTipoValidação
    x-white-label-domainObrigatório

    Domínio verificado que resolve a conta de Organização aprovada e vincula este pedido.

    		stringValidação: Nome de anfitrião HTTPS verificado.
    x-white-label-key-idObrigatório

    Identificador extraído da chave privada única; nunca envie o segredo neste cabeçalho.

    		stringValidação: Identificador interno da chave privada emitida.
    x-white-label-signature-versionObrigatório

    Seleciona a assinatura vinculada ao domínio; as rotas API mantêm a Versão 1.

    		stringValidação: 2.
    x-white-label-timestampObrigatório

    Instante da assinatura em milissegundos comparado com o relógio do servidor para rejeitar pedidos antigos.

    		stringValidação: Milissegundos com 13 dígitos; dentro de cinco minutos.
    x-white-label-nonceObrigatório

    Valor aleatório novo registado pelo servidor para impedir repetição de um pedido assinado.

    		stringValidação: Valor novo: 16–128 [A-Za-z0-9_-].
    x-white-label-signatureObrigatório

    HMAC-SHA256 de domínio, chave de idempotência, credencial de campanha, instante, nonce, método, caminho, consulta ordenada e hash exato do corpo.

    		stringValidação: HMAC-SHA256 hexadecimal em minúsculas.
    x-white-label-campaign-keyOpcional

    Chave de campanha completa opcional que limita o pedido privado à mesma campanha autorizada.

    		stringValidação: Valor keyId:secret completo, opcional e limitado ao seu âmbito.
    X-Idempotency-KeyObrigatório

    Identidade estável de operação reutilizada com os mesmos detalhes; detalhes diferentes com a mesma chave são rejeitados.

    		stringValidação: 16–128 [A-Za-z0-9_-].

    Pedido

    NomeTipoValidação
    campaignIdObrigatório

    Campanha existente na conta e no âmbito mais limitado de qualquer credencial de campanha.

    		stringValidação: UUID.
    participantIdObrigatório

    Nomeado escolhido nesta campanha; o servidor verifica aprovação e regras.

    		stringValidação: UUID.
    voteCountObrigatório

    Número de votos para o nomeado; o servidor determina o preço válido e regista votos concluídos.

    		integerValidação: 1–100.
    phoneNumberObrigatório

    Telefone do participante; métodos e regras podem exigir número internacional válido.

    		stringValidação: 8–32.
    callbackUrlObrigatório

    Destino de regresso aceite pelo contrato; nunca prova sucesso do pagamento.

    		stringValidação: URL.
    emailOpcional

    Email de contacto usado pelo fluxo configurado; por si só não concede acesso.

    		string|nullValidação: Endereço de e-mail.
    channelOpcional

    Canal de entrega ou integração suportado pela operação e configuração ativa.

    		enumValidação: web | ussd | telegram | whatsapp.
    payment_channelOpcional

    Preferência opcional; só se usam métodos ativos para país de venda, moeda e comerciante reais.

    		enumValidação: Método de pagamento ativado.
    metadataOpcional

    Metadados JSON aceites; nunca substituem autorização, preços ou propriedade.

    		objectValidação: Objeto JSON.

    Pedido

    Os exemplos descrevem o contrato e não são executados. Use registos de teste autorizados; nunca cole segredos reais aqui.

    POST /api/white-label/v1/votes/initialize
    http
    POST /api/white-label/v1/votes/initialize HTTP/1.1
Host: api.sparkglim.net
x-white-label-domain: events.example.com
x-white-label-key-id: <ISSUED_KEY_ID>
x-white-label-signature-version: 2
x-white-label-timestamp: <FRESH_MILLISECONDS>
x-white-label-nonce: <FRESH_SIGNING_NONCE>
x-white-label-signature: <SERVER_GENERATED_SIGNATURE>
X-Idempotency-Key: example_stable_operation_0001
Content-Type: application/json

{
  "campaignId": "11111111-1111-4111-8111-111111111111",
  "participantId": "33333333-3333-4333-8333-333333333333",
  "voteCount": 1,
  "phoneNumber": "+233200000000",
  "callbackUrl": "https://events.example.com/payment-return"
}

    Resposta

    Resposta de sucesso · HTTP 200
    json
    {
  "success": true,
  "data": {
    "authorization_url": "https://checkout.sparkglim.net/gh/<SERVER_REFERENCE>",
    "reference": "<SERVER_REFERENCE>"
  },
  "requestId": "wlapi_example"
}
    Resposta de erro · HTTP 400
    json
    {
  "success": false,
  "error": "<ERROR_MESSAGE>",
  "requestId": "wlapi_example"
}

    Validação, permissões, registos indisponíveis e falhas usam estado HTTP e erro do controlador.

    Limites e novas tentativas

    Organização: 120 pedidos por chave e 300 por IP por janela; respeite Retry-After e X-RateLimit.

    Compatibilidade do código

    As operações autorizadas exigem testes específicos da conta.

    • server/src/api/router.ts
    • server/src/api/routes/white-label.ts
    • server/src/white-label/auth.ts
    • server/src/white-label/schemas.ts
    • server/src/white-label/organization-service.ts
    • server/src/white-label/service.ts

    Continuar a desenvolver