Referência API

Criar campanha

Cria campanha na organização aprovada com dados validados e propriedade do Criador; rascunho não é publicação.

POSThttps://api.sparkglim.net/api/white-label/v1/campaigns

Modelo de acesso

Modelo de acesso: HMAC de Organização no servidor
Âmbito necessário: campaigns: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

Nome	Tipo	Validação
`x-white-label-domain`Obrigatório Domínio verificado que resolve a conta de Organização aprovada e vincula este pedido.	`string`	Validação: Nome de anfitrião HTTPS verificado.
`x-white-label-key-id`Obrigatório Identificador extraído da chave privada única; nunca envie o segredo neste cabeçalho.	`string`	Validação: Identificador interno da chave privada emitida.
`x-white-label-signature-version`Obrigatório Seleciona a assinatura vinculada ao domínio; as rotas API mantêm a Versão 1.	`string`	Validação: 2.
`x-white-label-timestamp`Obrigatório Instante da assinatura em milissegundos comparado com o relógio do servidor para rejeitar pedidos antigos.	`string`	Validação: Milissegundos com 13 dígitos; dentro de cinco minutos.
`x-white-label-nonce`Obrigatório Valor aleatório novo registado pelo servidor para impedir repetição de um pedido assinado.	`string`	Validação: Valor novo: 16–128 [A-Za-z0-9_-].
`x-white-label-signature`Obrigató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.	`string`	Validação: HMAC-SHA256 hexadecimal em minúsculas.
`x-white-label-campaign-key`Opcional Chave de campanha completa opcional que limita o pedido privado à mesma campanha autorizada.	`string`	Validação: Valor keyId:secret completo, opcional e limitado ao seu âmbito.

Pedido

Nome	Tipo	Validação
`title`Obrigatório Título público da campanha fornecido pelo organizador autorizado.	`string`	Validação: 3–255.
`description`Obrigatório Descrição do organizador que explica campanha ou bilhete.	`string`	Validação: 10–5000.
`campaign_type`Obrigatório Seleciona bilhetes, votação ou donativos; não concede módulos não autorizados.	`enum`	Validação: ticketing \| voting \| donation.
`start_date`Obrigatório Data de abertura da campanha em formato ISO.	`string`	Validação: Data e hora no formato ISO.
`end_date`Obrigatório Data de fecho da campanha em formato ISO.	`string`	Validação: Data e hora no formato ISO.
`country_code`Opcional Código do país de venda configurado; servidor verifica conta e mercado.	`string`	Validação: ISO2.
`currency_code`Opcional Moeda permitida da campanha; escolher país não autoriza moeda nova.	`string`	Validação: ISO3.
`slug`Opcional Identificador de URL da campanha ou artigo publicado existente.	`string`	Validação: Esquema configurado do identificador URL.
`status`Opcional Estado suportado pedido; aprovação controla publicação e acesso.	`enum`	Validação: draft \| pending_approval \| approved \| rejected \| archived.
`vote_price`Opcional Valor configurado do produto na moeda ou unidade de capacidade da campanha.	`number`	Validação: >=0.
`donation_goal`Opcional Valor configurado do produto na moeda ou unidade de capacidade da campanha.	`number`	Validação: >=0.
`ticket_price`Opcional Valor configurado do produto na moeda ou unidade de capacidade da campanha.	`number`	Validação: >=0.
`ticket_capacity`Opcional Valor configurado do produto na moeda ou unidade de capacidade da campanha.	`integer`	Validação: >0.
`image_url`Opcional URL da imagem fornecida; use media públicos autorizados.	`string\|null`	Validação: URL.
`banner_url`Opcional URL de capa fornecido pelo organizador.	`string\|null`	Validação: URL.
`category`Opcional Categoria de campanha ou definições aprovadas conforme recurso.	`string\|null`	Validação: <=120.
`location`Opcional Local público ou filtro; separado do país financeiro de venda.	`string\|null`	Validação: <=255.
`event_date`Opcional Data e hora do evento, distintas do período de venda.	`string\|null`	Validação: Data e hora no formato ISO.
`verification_required`Opcional Define verificação suportada sem contornar controlos do servidor.	`boolean`	Validação: Valor predefinido: true.
`metadata`Opcional Metadados JSON aceites; nunca substituem autorização, preços ou propriedade.	`object`	Validaçã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/campaigns

http

POST /api/white-label/v1/campaigns 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>
Content-Type: application/json

{
  "title": "Example campaign",
  "description": "An illustrative campaign description.",
  "campaign_type": "ticketing",
  "start_date": "2030-06-01T09:00:00.000Z",
  "end_date": "2030-06-02T18:00:00.000Z"
}

Resposta

Resposta de sucesso · HTTP 201

json

{
  "success": true,
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "draft"
  },
  "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

Modelo de acesso

Cabeçalhos

Pedido

Pedido

Resposta

Limites e novas tentativas

Compatibilidade do código

Continuar a desenvolver