Quickstart

A Ticto API v2 é uma API REST que permite a produtores digitais criar e gerenciar produtos e ofertas de forma programática, integrando o ecossistema Ticto diretamente às suas ferramentas e fluxos de trabalho. Este guia mostra, passo a passo, como obter suas credenciais, autenticar suas requisições e criar seu primeiro produto com uma oferta associada, tudo em menos de 5 minutos.

Gere seu token de API

Acesse o painel da Ticto e navegue até Integrações → API v2. Clique em Novo Token, dê um nome descritivo e selecione os escopos necessários para este guia:

Escopo	O que permite
`products:read`	Listar e consultar produtos
`products:write`	Criar produtos
`offers:read`	Listar e consultar ofertas
`offers:write`	Criar ofertas

Após confirmar, o token será exibido uma única vez em texto simples. Copie-o imediatamente e armazene em um local seguro (por exemplo, um gerenciador de segredos ou variável de ambiente). Tokens de produção começam com o prefixo ticto_live_; tokens de sandbox começam com ticto_test_.

Por segurança, o valor completo do token não é exibido novamente após esta tela. Se perdê-lo, será necessário revogar e criar um novo.

Faça sua primeira requisição

Com o token em mãos, valide sua configuração listando os produtos da sua conta. Substitua o valor do cabeçalho Authorization pelo seu token real.

curl --request GET \
  --url https://api.ticto.cloud/api/v2/products \
  --header "Authorization: Bearer ticto_live_VIHfM4Ynb0J8kQ2rXXXXXXXXXXXXXXXXXXXXXXXX" \
  --header "Accept: application/json"

Uma resposta 200 OK com a lista de produtos confirma que a autenticação está funcionando corretamente:

{
  "object": "list",
  "data": [
    {
      "object": "product",
      "id": "PABC123",
      "reference_id": 42,
      "name": "Meu Curso Online",
      "type": "course",
      "status": "approved",
      "is_active": true,
      "created_at": "2024-07-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 30,
    "total": 1
  }
}

Crie um produto

Para criar um produto, envie uma requisição POST /products. Todas as requisições POST exigem o cabeçalho Idempotency-Key com um UUID v4 único. Isso garante que requisições repetidas (por exemplo, após uma falha de rede) não criem duplicatas.

curl --request POST \
  --url https://api.ticto.cloud/api/v2/products \
  --header "Authorization: Bearer ticto_live_VIHfM4Ynb0J8kQ2rXXXXXXXXXXXXXXXXXXXXXXXX" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: e4d909c2-90d4-4809-b3f4-1c3f3e4a1234" \
  --data '{
    "name": "Curso de Marketing Digital",
    "type": "course",
    "description": "Aprenda estratégias avançadas de marketing digital do zero ao avançado."
  }'

Em caso de sucesso, a API retorna 201 Created com os dados do produto recém-criado:

{
  "object": "product",
  "id": "PMKT2024",
  "reference_id": 101,
  "name": "Curso de Marketing Digital",
  "type": "course",
  "status": "approved",
  "is_active": true,
  "created_at": "2024-07-15T10:30:00Z"
}

O id (PMKT2024) é o identificador canônico da API, o mesmo que você usa na URL para criar ofertas. O reference_id é o ID numérico legado que reconcilia com o painel.

O produto nasce aprovado e ativo, pronto para vender. O status é gerido pela plataforma e não pode ser enviado nem alterado pela API. Se quiser criar o produto indisponível, envie "is_active": false e ative depois pelo painel.

Crie uma oferta

Com o hash do produto criado no passo anterior, adicione uma oferta a ele. Preços são informados em centavos. Por exemplo, 19700 equivale a R$ 197,00.

curl --request POST \
  --url https://api.ticto.cloud/api/v2/products/PMKT2024/offers \
  --header "Authorization: Bearer ticto_live_VIHfM4Ynb0J8kQ2rXXXXXXXXXXXXXXXXXXXXXXXX" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: b7f3a1e2-55c8-4d12-9e6b-8a2f1d0c5e78" \
  --data '{
    "name": "Acesso Completo",
    "price": 19700,
    "charge_type": "one_time"
  }'

A resposta 201 Created traz o id da oferta (o code) e a checkout_url pronta para compartilhar com seus clientes:

{
  "object": "offer",
  "id": "O709D4B48",
  "reference_id": 55,
  "product_id": "PMKT2024",
  "price": 19700,
  "is_active": true,
  "checkout_url": "https://checkout.ticto.app/O709D4B48",
  "created_at": "2024-07-15T10:35:00Z"
}

A checkout_url é a base de checkout da Ticto seguida do code da oferta. Compartilhe esse link e comece a vender.

Disponibilidade do produto

O produto nasce aprovado e ativo (is_active: true), então a checkout_url da oferta já fica acessível ao público para receber pagamentos reais.Se você criou o produto com "is_active": false (para configurar as ofertas antes de divulgar), ele fica indisponível para compra até você ativá-lo no painel, em Produtos → Meus Produtos → Ativar.

Tokens com prefixo ticto_test_ apontam para o ambiente sandbox (https://sandbox.ticto.cloud/api/v2). Produtos e ofertas criados no sandbox são descartáveis e nunca geram cobranças reais. Use-os à vontade para testar integrações, validar payloads e simular fluxos sem nenhum risco financeiro.

Autenticação

Entenda os tipos de token, escopos disponíveis e boas práticas para proteger suas credenciais.

Criar Produto

Guia detalhado sobre todos os campos, tipos de produto e opções de configuração disponíveis.

Produtos

Referência completa do endpoint de listagem e criação de produtos.

Ofertas

Referência completa do endpoint de listagem e criação de ofertas vinculadas a produtos.

Introdução

Autenticação

Conceitos

Guias

Autenticação

Criar Produto

Produtos

Ofertas