API REST pública

Use a API REST pública do cside para criar ou excluir equipes, gerenciar domínios e adicionar seletores de página de checkout em um fluxo de backend. A API usa JSON por HTTPS e um token bearer no nível da organização.

URL base: https://api.cside.com

Fluxo de provisionamento

A criação de equipes e o registro de domínios são operações separadas:

1. Crie um token de API da organização com as permissões necessárias
2. Chame POST /v1/teams/ e salve o teamId retornado
3. Chame POST /v1/domains/ com esse teamId e até 100 nomes de host
4. Chame POST /v1/payment-pages/ para adicionar seletores de página de checkout à equipe
5. Verifique cada resposta antes de considerar o provisionamento concluído

Se o registro de domínios falhar, a equipe continuará disponível. A API não reverte uma criação de equipe bem-sucedida.

Disponibilidade e autenticação

Um administrador da organização pode gerar um token em Configurações da organização > Geral no dashboard do cside. Selecione Generate token, dê um nome ao token (por exemplo, o da integração à qual ele pertence) e escolha apenas as permissões necessárias para a integração:

teams:create ou teams:delete também permite consultar com um filtro name não vazio. domains:create ou domains:delete permite consultar com um filtro domain não vazio. Listas sem filtro exigem teams:read ou domains:read; integrações somente de leitura podem usar essas permissões sem acesso de escrita. Leituras compartilham com escritas o limite de 60 requisições por minuto por organização.

O dashboard mostra cada token apenas uma vez. Armazene-o em um gerenciador de segredos do servidor antes de fechar a caixa de diálogo. Não o exponha no código do navegador, não o envie ao controle de versão, e não o grave em logs da aplicação.

Os tokens têm o formato cside_oatv2_<id>_<secret>. A parte <id> identifica o token na lista do dashboard e nos logs de auditoria; o restante é o segredo.

Envie o token em todas as requisições:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Gerenciar e revogar tokens

Configurações da organização > Geral lista todos os tokens ativos com seu Name, o prefixo mascarado do Token, os Scopes, a data de Created e a data de Last used. Uma organização pode ter até 50 tokens ativos. Quando o limite é atingido, revogue um token sem uso antes de gerar um novo.

Um token permanece válido até ser revogado. Você pode revogar tokens de duas formas:

• Revoke: revoga um único token da lista. Somente esse token deixa de funcionar, e as outras integrações continuam operando.
• Revoke all tokens: invalida de uma só vez todos os tokens de API da organização, incluindo os que não aparecem na lista.

Tokens gerados antes de a lista de tokens existir não aparecem na lista. Eles continuam funcionando, mas Revoke all tokens é a única forma de revogá-los.

A criação de tokens, a revogação individual e Revoke all tokens são registradas no log de auditoria da organização como org.api_token.create, org.api_token.revoke e org.api_secret.rotate.

Limite de requisições

A API aceita 60 requisições por organização a cada minuto. Esse limite é compartilhado entre os endpoints de equipe, domínio e página de pagamento. Uma requisição acima do limite retorna 429 com o código de erro rate_limited. Tente novamente com backoff depois que o próximo minuto começar.

Criar uma equipe

Use POST /v1/teams/ para criar uma equipe na organização à qual o token pertence.

curl --request POST \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Acme Production"
  }'

O nome da equipe deve:

• Conter de 3 a 32 caracteres
• Usar letras, números, sublinhados, espaços, ou apóstrofos
• Ser exclusivo dentro da organização

Hífens não são aceitos em nomes de equipe.

Uma requisição bem-sucedida retorna 201 Created:

{
  "data": {
    "teamId": "1897425263682514944"
  }
}

Salve data.teamId. Você precisará dele para registrar ou excluir domínios da equipe.

Um conflito retorna 409 team_name_exists com a equipe existente, então repetir a chamada é seguro e ainda devolve um ID com que trabalhar:

{
  "error": "team_name_exists",
  "message": "Team with name `Acme Production` already exists in this organization.",
  "data": {
    "teamId": "1897425263682514944"
  }
}

Criar uma equipe não habilita o onboarding automático de domínios. Esse recurso é configurado separadamente para cada equipe e fica desabilitado por padrão.

Registrar domínios

Use POST /v1/domains/ para registrar de 1 a 100 nomes de host como domínios gerenciados de uma equipe. team_id é obrigatório ao usar um token de API da organização.

curl --request POST \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "checkout.example.com",
      "app.example.com"
    ]
  }'

Envie nomes de host sem protocolo, porta, caminho, string de consulta, ou fragmento. O cside remove os espaços em branco e normaliza os nomes de host aceitos para letras minúsculas.

Cada item registra exatamente o nome de host enviado. A API não cria um domínio wildcard. Portanto, inclua todos os nomes de host necessários, como example.com e www.example.com.

O endpoint retorna 200 OK com um resultado para cada entrada, na mesma ordem:

{
  "data": {
    "results": [
      {
        "status": "created",
        "input": "checkout.example.com",
        "domain": "checkout.example.com",
        "domainId": "1897425263682514945"
      },
      {
        "status": "existing",
        "input": "app.example.com",
        "domain": "app.example.com",
        "domainId": "1897425263682514946"
      },
      {
        "status": "invalid",
        "input": "not a hostname",
        "code": "invalid_domain",
        "message": "Domain is invalid."
      }
    ],
    "totals": {
      "created": 1,
      "existing": 1,
      "invalid": 1
    }
  }
}

A requisição pode conter resultados bem-sucedidos e inválidos e ainda retornar 200 OK. Verifique cada resultado:

É seguro repetir requisições para domínios que já foram criados para a mesma equipe. Elas retornam existing em vez de criar uma duplicata. Um nome de host gerenciado por outra equipe retorna invalid com domain_already_licensed.

Se os domínios foram salvos, mas o cside não conseguiu concluir o envio da configuração para a rede de distribuição, a requisição retorna 503 domain_registration_unavailable com a mensagem “Domains saved, but synchronization is incomplete. Retry to synchronize them.” Envie a mesma requisição novamente: os nomes de host salvos retornam como existing e a sincronização é repetida.

Novos domínios passam a contar automaticamente com proteção gerenciada. Não é necessária uma chamada separada à API para ativação. A configuração pode levar algum tempo para chegar à rede de distribuição.

Códigos de validação de domínio

Um resultado invalid pode incluir um destes códigos:

Adicionar páginas de pagamento

Use POST /v1/payment-pages/ para adicionar um seletor de página de checkout a uma equipe existente. team_id é obrigatório ao usar um token de API da organização. Ele é opcional para um token limitado a uma equipe e, se for informado, deve corresponder à equipe do token.

curl --request POST \
  --url https://api.cside.com/v1/payment-pages/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "payment_page": "checkout.example.com/checkout"
  }'

Envie payment_page como um seletor canônico de host/caminho, sem https://, porta, ou URL completa. Por exemplo, use checkout.example.com/checkout, e não https://checkout.example.com/checkout. O cside remove os espaços em branco ao redor, as strings de consulta e as barras finais antes de armazenar o seletor. Um fragmento # é mantido como enviado, para que aplicações de página única que roteiam a página de pagamento por fragmento possam corresponder a ele. Um seletor que contenha espaços em branco, como checkout.example.com/check out, é rejeitado com 400 invalid_payment_page.

O seletor usa o mesmo formato de padrão do dashboard. Uma equipe pode ter até 500 seletores de página de checkout. O endpoint não registra um domínio. Portanto, registre o nome de host primeiro com POST /v1/domains/ quando ele ainda não for gerenciado pela equipe.

O endpoint retorna 200 OK:

{
  "data": {
    "status": "created",
    "teamId": "1897425263682514944",
    "paymentPage": "checkout.example.com/checkout"
  }
}

É seguro adicionar o mesmo seletor novamente: a resposta retorna status: "existing". Um seletor novo retorna status: "created". Quando a equipe possui domínios correspondentes, o cside atualiza as projeções de página de checkout desses domínios e a configuração relacionada depois que o seletor no nível da equipe é armazenado.

Carregar o cside para a equipe

Use o teamId retornado pela criação da equipe na URL padrão do script do cside. Não use um domainId no lugar dele.

<script
  src="https://[your-team-id].csidetm.com/client.js"
  referrerpolicy="origin">
</script>

O nome de host da página deve estar registrado no mesmo ID de equipe usado na URL do script. A ausência do registro ou uma incompatibilidade de equipe retorna 403. Se isso ocorrer logo após o registro, tente novamente em alguns instantes. Entre em contato com o suporte do cside se o problema continuar.

O monitoramento padrão não exige um CNAME do cliente nem redirecionamento de tráfego. Se o seu site tiver uma Content Security Policy restritiva, siga o guia de configuração da CSP para permitir *.csidetm.com.

Onboarding automático de domínios

O onboarding automático de domínios é um recurso opcional da equipe para implantações que carregam o script de bootstrap padrão do cside. Ele fica desabilitado por padrão para novas equipes. Entre em contato com seu representante do cside se precisar habilitá-lo.

Quando o recurso está habilitado e um nome de host não registrado carrega o bootstrap específico da equipe em /client.js ou /script.js, o cside envia o nome de host de referência pelo mesmo fluxo de validação e registro de domínio. Mantenha o atributo padrão referrerpolicy="origin" para que a origem da página fique disponível sem expor seu caminho ou sua string de consulta.

A requisição que detecta o nome de host não registrado não é repetida. O registro afeta uma requisição de script posterior, depois que a configuração é propagada. Domínios registrados automaticamente aparecem no inventário de domínios da equipe da mesma forma que os domínios registrados pela API.

O onboarding automático não cria equipes, e requisições a outros endpoints do cside não registram um nome de host. Use o fluxo explícito da API quando precisar de um resultado para cada domínio antes de implantar o script. O onboarding automático se aplica ao script de monitoramento padrão e não habilita a coleta de Device Intelligence.

Listar equipes

Use GET /v1/teams/ com um token de organização. Tokens restritos a uma equipe não podem chamar este endpoint. Omita name para listar equipes ou informe um nome exato, diferenciando maiúsculas de minúsculas. Espaços nas extremidades são removidos, como na criação. Equipes renomeadas podem compartilhar o nome; sempre trate o resultado como um array. Equipes suspensas são incluídas. Sem correspondência, a resposta é 200 OK com data vazio.

curl --get \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --data-urlencode "name=Acme Production"

{
  "data": [
    {
      "id": "1897425263682514944",
      "name": "Acme Production",
      "createdAt": "2026-07-07T10:00:00Z",
      "suspended": false
    }
  ],
  "next_cursor": null
}

Listar domínios

Use GET /v1/domains/ para listar domínios. Com um token de organização, omita team_id para consultar toda a organização ou informe uma equipe. Um token de equipe só pode consultar sua própria equipe, mesmo sem team_id. Uma equipe desconhecida ou inacessível retorna 404 team_not_found. O filtro opcional domain corresponde a um hostname exato.

curl --get \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --data-urlencode "team_id=1897425263682514944"

{
  "data": [
    {
      "id": "1897425263682514945",
      "domain": "checkout.acme.com",
      "teamId": "1897425263682514944",
      "managed": true,
      "wildcard": false,
      "suspended": false,
      "createdAt": "2026-07-07T10:00:00Z"
    }
  ],
  "next_cursor": null
}

Os resultados incluem domínios gerenciados e não gerenciados. id é o domainId retornado no registro. Verifique managed antes de usar esse ID com DELETE /v1/domains/: somente domínios gerenciados podem ser excluídos por esta API. Sem hostname correspondente, o array data fica vazio.

Percorrer os resultados

Ambos os endpoints aceitam limit (1 a 100, padrão 50) e um cursor opcional. Os resultados são ordenados por criação, do mais antigo ao mais recente, com o ID como desempate. Cada resposta 200 OK contém um array data e next_cursor. Continue até next_cursor ser null.

Trate o cursor como opaco e codifique-o para URL ao reenviá-lo. Mantenha o mesmo escopo de token e os mesmos filtros entre páginas. Um cursor malformado ou de outra consulta ou conta retorna 400 invalid_cursor; reinicie a consulta sem cursor.

curl --get \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --data-urlencode "team_id=1897425263682514944" \
  --data-urlencode "cursor=NEXT_CURSOR"

Excluir domínios

Use DELETE /v1/domains/ com os valores domainId retornados pelo registro de domínios. Não envie nomes de host para esse endpoint.

curl --request DELETE \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "1897425263682514945",
      "1897425263682514946"
    ]
  }'

Você pode enviar de 1 a 100 IDs de domínio. Uma requisição bem-sucedida retorna resultados parciais ordenados:

{
  "data": {
    "results": [
      {
        "status": "deleted",
        "domainId": "1897425263682514945",
        "domain": "checkout.example.com"
      },
      {
        "status": "not_found",
        "domainId": "1897425263682514999"
      }
    ],
    "totals": {
      "deleted": 1,
      "not_found": 1
    }
  }
}

A exclusão é idempotente. Um ID desconhecido, um domínio já excluído, ou um domínio fora da equipe de destino retorna not_found sem expor informações sobre outra equipe.

Excluir uma equipe

Use DELETE /v1/teams/ para excluir permanentemente uma equipe e todos os seus domínios. A requisição exige um token de organização com Excluir equipes (teams:delete). Essa permissão inclui a exclusão de domínios; domains:delete isoladamente não permite excluir uma equipe. Gere um novo token para adicionar essa permissão a uma integração existente. Tokens limitados a uma equipe não são aceitos.

Envie o teamId recebido ao criar a equipe como team_id, uma string decimal entre aspas. Não é necessário listar os domínios nem excluí-los separadamente.

curl --request DELETE \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944"
  }'

Uma requisição bem-sucedida retorna 200 OK. deletedDomains indica o número de domínios excluídos:

{
  "data": {
    "status": "deleted",
    "teamId": "1897425263682514944",
    "deletedDomains": 2
  }
}

Uma equipe com uma assinatura Stripe vinculada retorna 409 team_subscription_attached. Cancele a assinatura antes de excluir a equipe. Se ela já estiver cancelada e o erro persistir, entre em contato com o suporte do cside.

Uma equipe desconhecida, fora da organização do token ou já excluída retorna 404 team_not_found. Repetir uma exclusão bem-sucedida não exclui mais nada. Uma falha na limpeza retorna 503 team_deletion_unavailable. Tente novamente mais tarde e entre em contato com o suporte se o erro continuar.

O acesso Enterprise é verificado em cada requisição. Se você excluir a última equipe Enterprise ativa da organização, as próximas requisições à API pública, incluindo novas tentativas, retornarão 403 enterprise_required.

Erros no nível da requisição

As falhas no nível da requisição usam este formato:

{
  "error": "insufficient_scope",
  "message": "Token is missing the domains:create scope."
}

Checklist de segurança

• Gere um token separado e nomeado para cada integração de backend
• Conceda apenas as permissões necessárias para essa integração
• Armazene os tokens em um gerenciador de segredos do servidor
• Nunca exponha tokens no código do navegador, em URLs, no controle de versão, ou em logs
• Revogue um token imediatamente se ele for exposto; use Revoke all tokens quando não souber qual token vazou ou quando o token for anterior à lista de tokens
• Revise a coluna Last used e revogue os tokens que não estão mais em uso
• Trate os IDs de equipe e domínio retornados como strings

Documentação relacionada

• Referência interativa da API
• Adicionar seu domínio
• Adicionar o script do cside
• Configurações do dashboard