Ir para o conteúdo
Estás a pré-visualizar o novo Puzzel.org Voltar ao site atual
API para programadores

Cria atividades a partir do teu próprio sistema

Um POST por tipo de atividade. Envia o teu conteúdo em JSON e recebes uma atividade na tua conta Puzzel.org e um URL que podes dar aos jogadores ou colocar num iframe.

URL base
https://puzzel.org/api/public/v1
Autenticação
Chave + e-mail no corpo
Endpoints
20 tipos de atividade
Quota
10 atividades por dia

O teu primeiro pedido

Não há nada para instalar nem qualquer negociação prévia: envia um corpo em JSON com a tua chave, o teu e-mail e o teu conteúdo. A resposta traz a chave da nova atividade e o URL onde se joga.

POST crossword 
curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "pt",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

Todos os exemplos desta página são pedidos completos e prontos a executar. Troca a chave e o conteúdo pelos teus e funcionam tal como estão.

Autenticação

Não há cabeçalhos nem bearer token. As duas credenciais viajam no corpo JSON de cada pedido e a chave só é aceite para a conta a que esse e-mail pertence.

CampoTipoO que faz
account_api_key
obrigatório
string
stringA chave de API da tua conta. Vai no corpo, não num cabeçalho.
email
obrigatório
string
stringO endereço com que a tua conta Puzzel.org inicia sessão. A chave só é válida em conjunto com ele.

A tua chave está na secção da conta, no painel, atrás de Mostrar.

Iniciar sessão

As chaves de API são atribuídas quando começa uma subscrição, por isso uma conta gratuita ainda não tem nenhuma.

Ver os planos

Trata a chave como uma palavra-passe. Cria e substitui atividades na tua conta, por isso guarda-a no servidor e fora de tudo o que um navegador possa ler.

O corpo do pedido

Todos os endpoints recebem os mesmos cinco campos. O que muda é o campo de conteúdo por baixo deles: a maioria recebe um array de itens, alguns recebem uma frase ou uma imagem, e o sudoku não recebe nada.

CampoTipoO que faz
account_api_key
obrigatório
string
stringA chave de API da tua conta. Vai no corpo, não num cabeçalho.
email
obrigatório
string
stringO endereço com que a tua conta Puzzel.org inicia sessão. A chave só é válida em conjunto com ele.
title
opcional
string
stringO nome que a atividade recebe no teu painel. Se o deixares de fora, o endpoint usa o nome alternativo dele.
language
opcional
string
stringSó define o idioma no URL que recebes de volta — não traduz nada do que envias. A sopa de letras também o lê para mudar as letras de preenchimento para árabe quando é "ar".
Predefinição: "en"
activity_key
opcional
string
stringDeixa-o de fora para criar uma atividade nova. Se enviares a chave de uma que já te pertence, essa atividade é reconstruída.

settings é um objeto com opções específicas de cada endpoint. As que cada endpoint lê estão listadas com ele mais abaixo; tudo o resto que lá puseres é ignorado.

O que recebes de volta

Uma chamada bem-sucedida responde 200 com a chave da nova atividade e o URL onde se joga. Tudo o resto responde com success a false e uma única string error.

Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Falha 
{
  "success": false,
  "error": "Invalid Email or API Key"
}

O url que recebes de volta é a vista de incorporação. Troca embed por play para a abrir em página inteira, ou por build para a abrir no editor — a chave depois de p= mantém-se igual.

Criar vs. atualizar

Envia activity_key e a atividade correspondente é reconstruída no lugar: o conteúdo é substituído, o nome e a marca de versão são atualizados e a chave em si mantém-se — por isso as ligações e as incorporações que já partilhaste continuam a funcionar. Os resultados, a pasta onde está e todas as definições que o endpoint não escreve ficam como estavam.

activity_key 
{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "activity_key": "-Nq8sample_activity_key",
  "title": "Fruit crossword, week 2",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}
  • title é aplicado em todas as atualizações, incluindo a predefinição — se o deixares de fora, a atividade passa a ter o nome alternativo desse endpoint.
  • Os blocos de definições que um endpoint escreve são reescritos de raiz, por isso uma atualização também os repõe nos valores que enviares, ou nas predefinições do endpoint.
  • Só podes atualizar atividades da tua própria conta. A chave de outra pessoa responde 403.
  • Uma atualização custa o mesmo que uma criação: uma chamada retirada à quota de hoje.

Limite de pedidos

10
10 atividades por conta por dia

Todas as chamadas bem-sucedidas contam, tanto criações como atualizações. Se passares do limite, o pedido seguinte responde 429 até o contador ser reposto.

O contador é limpo uma vez por dia por uma tarefa agendada, não numa janela móvel de 24 horas.

Erros

Os erros chegam sempre em JSON com os mesmos dois campos, nunca como uma página HTML. A string error está escrita para ser lida por uma pessoa — indica o campo ou o limite que falhou.

EstadoO que significa
400
Bad Request
Falta algo no corpo, está malformado ou fora do intervalo. A mensagem indica o campo.
401
Unauthorized
O e-mail é desconhecido, ou a chave não pertence a essa conta.
403
Forbidden
O activity_key que enviaste pertence a outra conta.
429
Too Many Requests
A quota de hoje está esgotada. É reposta uma vez por dia.
500
Server Error
O gerador não conseguiu criar um quebra-cabeças com o que enviaste — normalmente por serem poucas palavras, ou palavras que não encaixam umas nas outras.

Endpoints

Um caminho por tipo de atividade, todos POST, todos sob o mesmo URL base. Cada um indica o conteúdo de que precisa, as definições que lê e um pedido que podes executar.

Palavras e letras

Palavras cruzadas

Encaixa as tuas respostas numa grelha e numera as definições por ti.

#
POST /api/public/v1/crossword Pelo menos 2 em items
Conteúdo

Um array de palavras. Cada entrada junta a resposta à definição que lhe aponta.

Por omissão, fica com o nome “Crossword API”

Vale a pena saber
  • As respostas com menos de dois carateres são descartadas antes de a grelha ser criada, e pelo menos duas têm de sobreviver a isso.
  • As respostas passam a maiúsculas e o gerador tem vinte tentativas para as encaixar. Se não conseguir colocar uma única palavra, a chamada responde 500.
Pedido de exemplo
POST crossword 
curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "pt",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Abrir o editor Voltar ao topo

Sopa de letras

Esconde as tuas palavras numa grelha de letras, nas direções e na forma que escolheres.

#
POST /api/public/v1/wordseeker Pelo menos 2 em items
Conteúdo

Um array de palavras. O texto da definição passa a ser a lista de palavras com que os jogadores trabalham.

Por omissão, fica com o nome “Wordseeker API”

Vale a pena saber
  • As respostas com menos de dois carateres são descartadas, e todas as respostas passam a maiúsculas antes de entrarem na grelha.
  • A grelha é preenchida com letras latinas, a não ser que language seja "ar", o que muda o preenchimento para árabe.
Definições que lê
CampoTipoO que faz
hidden_solution
opcional em settings
string
stringAs letras que sobram formam isto. Defini-lo também diz ao gerador para encaixar primeiro a solução, em vez de meter o máximo de palavras que conseguir.
directions
opcional em settings
string[]
string[]As direções em que uma palavra pode seguir. Se o deixares de fora, as palavras seguem apenas para leste, sudeste e sul.
Um de westeastnorthsouthnorthwestnortheastsouthwestsoutheast
Predefinição: ["east", "southeast", "south"]
template
opcional em settings
string
stringRecorta a grelha numa forma, em vez de a deixar quadrada.
Um de squarecirclecrossdiamondpyramidsmileystarcross_plus
Pedido de exemplo
POST wordseeker 
curl -X POST https://puzzel.org/api/public/v1/wordseeker \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wordseeker",
  "language": "pt",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "FRUIT",
    "directions": [
      "east",
      "south",
      "southeast"
    ],
    "template": "square"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}
Abrir o editor Voltar ao topo

Acróstico

Empilha as tuas respostas para que uma coluna forme uma palavra escondida.

#
POST /api/public/v1/acrostic Pelo menos 1 em items
Conteúdo

Um array de palavras. Entre elas têm de fornecer todas as letras da palavra escondida.

Por omissão, fica com o nome “Acrostic API”

Vale a pena saber
  • Se as respostas não conseguirem fornecer as letras de que a solução precisa, a chamada responde 500 em vez de guardar uma grelha meio construída.
  • O gerador reordena as tuas respostas para a coluna funcionar, por isso a ordem que envias não é a ordem que os jogadores veem.
Definições que lê
CampoTipoO que faz
hidden_solution
obrigatório em settings
string
stringA palavra que a coluna destacada forma. Este endpoint não funciona sem ela.
Pedido de exemplo
POST acrostic 
curl -X POST https://puzzel.org/api/public/v1/acrostic \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Acrostic",
  "language": "pt",
  "items": [
    {
      "answer": "PEACH",
      "description": "Fuzzy skin, sweet flesh",
      "type": "text"
    },
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "PLUM"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}
Abrir o editor Voltar ao topo

Letras baralhadas

api_e_word_scramble

#
POST /api/public/v1/word-scramble Pelo menos 1 em items
Conteúdo

api_c_word_scramble

Por omissão, fica com o nome “Word Scramble API”

Vale a pena saber
  • As atividades criadas através da API têm sempre a definição de baralhar a ordem ativa, por isso a ordem que envias não é a ordem que os jogadores recebem.
Definições que lê
CampoTipoO que faz
hidden_solution
opcional em settings
string
stringUma palavra bónus opcional que os jogadores escrevem depois de resolverem o resto.
Pedido de exemplo
POST word-scramble 
curl -X POST https://puzzel.org/api/public/v1/word-scramble \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Word Scramble",
  "language": "pt",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "FRUIT"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}
Abrir o editor Voltar ao topo

Jogo da forca

Transforma as tuas palavras ou frases em rondas de adivinhar a letra.

#
POST /api/public/v1/hangman Pelo menos 1 em items
Conteúdo

Um array de palavras ou frases curtas. A pista é a dica que os jogadores veem.

Por omissão, fica com o nome “Hangman API”

Pedido de exemplo
POST hangman 
curl -X POST https://puzzel.org/api/public/v1/hangman \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Hangman",
  "language": "pt",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}
Abrir o editor Voltar ao topo

Wordle

Cria um jogo de adivinhar a palavra a partir de cada palavra que envias.

#
POST /api/public/v1/wordle Pelo menos 1 em items
Conteúdo

Um array de palavras. Os jogadores têm uma ronda por palavra.

Por omissão, fica com o nome “Wordle API”

Vale a pena saber
  • Criado com a definição de verificar se as tentativas são palavras reais ativa. Desliga-a no editor se as tuas palavras forem nomes ou inventadas.
Pedido de exemplo
POST wordle 
curl -X POST https://puzzel.org/api/public/v1/wordle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wordle",
  "language": "pt",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}
Abrir o editor Voltar ao topo

Treino de teclado

api_e_typing_practice

#
POST /api/public/v1/typing-practice Pelo menos 1 em items
Conteúdo

api_c_typing_practice

Por omissão, fica com o nome “Typing Practice API”

Pedido de exemplo
POST typing-practice 
curl -X POST https://puzzel.org/api/public/v1/typing-practice \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Typing Practice",
  "language": "pt",
  "items": [
    {
      "answer": "The quick brown fox jumps over the lazy dog",
      "description": "Every letter of the alphabet",
      "type": "text"
    },
    {
      "answer": "Pack my box with five dozen liquor jugs",
      "description": "Another pangram",
      "type": "text"
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
  "message": "Typing Practice created successfully"
}
Abrir o editor Voltar ao topo

Roda da sorte

api_e_wheel_of_fortune

#
POST /api/public/v1/wheel-of-fortune Pelo menos 1 em items
Conteúdo

api_c_wheel_of_fortune

Por omissão, fica com o nome “Wheel of Fortune API”

Vale a pena saber
  • Criado com “mostrar o resultado apenas na roda”, por isso o resultado lê-se na roda em vez de aparecer ao lado dela.
Pedido de exemplo
POST wheel-of-fortune 
curl -X POST https://puzzel.org/api/public/v1/wheel-of-fortune \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wheel of Fortune",
  "language": "pt",
  "items": [
    {
      "answer": "Read a page aloud",
      "description": "Segment 1",
      "type": "text"
    },
    {
      "answer": "Name three fruits",
      "description": "Segment 2",
      "type": "text"
    },
    {
      "answer": "Spell it backwards",
      "description": "Segment 3",
      "type": "text"
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wheel-of-fortune/embed?p=-Nq8sample_activity_key",
  "message": "Wheel of Fortune created successfully"
}
Abrir o editor Voltar ao topo
Cartões e pares

Memory

Cartões virados para baixo para revelar e juntar em pares.

#
POST /api/public/v1/memory Pelo menos 2 em items
Conteúdo

Um array de pares. Cada par contém os dois cartões que pertencem um ao outro.

Por omissão, fica com o nome “Memory Game API”

Vale a pena saber
  • Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
Pedido de exemplo
POST memory 
curl -X POST https://puzzel.org/api/public/v1/memory \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Memory Game",
  "language": "pt",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}
Abrir o editor Voltar ao topo

Jogo de correspondências

api_e_matching_pairs

#
POST /api/public/v1/matching-pairs Pelo menos 2 em items
Conteúdo

api_c_matching_pairs

Por omissão, fica com o nome “Matching Game API”

Vale a pena saber
  • Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
Pedido de exemplo
POST matching-pairs 
curl -X POST https://puzzel.org/api/public/v1/matching-pairs \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Matching Game",
  "language": "pt",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}
Abrir o editor Voltar ao topo

Cartões de estudo

api_e_flash_cards

#
POST /api/public/v1/flash-cards Pelo menos 1 em items
Conteúdo

api_c_flash_cards

Por omissão, fica com o nome “Flash Cards API”

Vale a pena saber
  • O endpoint guarda tantos cartões quantos enviares, por isso envia exatamente dois por entrada — primeiro a frente, depois o verso.
  • Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
Pedido de exemplo
POST flash-cards 
curl -X POST https://puzzel.org/api/public/v1/flash-cards \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Flash Cards",
  "language": "pt",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}
Abrir o editor Voltar ao topo

Jogo de categorias

Cartões para arrumar na categoria a que pertencem.

#
POST /api/public/v1/categorize Pelo menos 2 em items
Conteúdo

Um array de categorias, cada uma com um nome e os cartões que lhe pertencem.

Por omissão, fica com o nome “Categorize Game API”

Vale a pena saber
  • Uma categoria enviada sem nome é guardada como “Untitled Category”, por isso envia sempre um.
  • Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
Pedido de exemplo
POST categorize 
curl -X POST https://puzzel.org/api/public/v1/categorize \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Categorize Game",
  "language": "pt",
  "items": [
    {
      "name": "Red fruits",
      "cards": [
        {
          "type": "text",
          "value": "Strawberry"
        },
        {
          "type": "text",
          "value": "Cherry"
        }
      ]
    },
    {
      "name": "Yellow fruits",
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "Lemon"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}
Abrir o editor Voltar ao topo

Sequência

Uma sequência que os jogadores têm de voltar a pôr por ordem.

#
POST /api/public/v1/reorder Pelo menos 1 em items
Conteúdo

Um array de sequências. Cada uma contém os cartões pela ordem correta.

Por omissão, fica com o nome “Reorder Game API”

Vale a pena saber
  • A ordem que envias é guardada como a ordem correta — o número um primeiro.
  • Um cartão é um objeto com um type e um value. Usa "text" para palavras, ou "image", "audio", "youtube" ou "link" com um URL em value, e acrescenta alt para uma descrição.
Pedido de exemplo
POST reorder 
curl -X POST https://puzzel.org/api/public/v1/reorder \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Reorder Game",
  "language": "pt",
  "items": [
    {
      "name": "From seed to fruit",
      "cards": [
        {
          "type": "text",
          "value": "Plant the seed"
        },
        {
          "type": "text",
          "value": "Water it"
        },
        {
          "type": "text",
          "value": "Watch it grow"
        },
        {
          "type": "text",
          "value": "Pick the fruit"
        }
      ]
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}
Abrir o editor Voltar ao topo
Perguntas e respostas

Quiz

Perguntas de escolha múltipla e de resposta aberta, pontuadas à medida que os jogadores avançam.

#
POST /api/public/v1/quiz Pelo menos 1 em items
Conteúdo

Um array de perguntas. As perguntas de escolha múltipla levam as respetivas respostas; as de resposta aberta levam a resposta que aceitas.

Por omissão, fica com o nome “Quiz API”

Vale a pena saber
  • question_type é "multiple_choice", em que a opção certa leva isCorrect a true, ou "open_answer", que usa antes correct_answer. Se for deixado de fora, é tratado como escolha múltipla.
  • O endpoint do quiz passa settings diretamente como blocos de definições da atividade, por isso não é sítio para opções soltas — ajusta o quiz no editor depois.
Pedido de exemplo
POST quiz 
curl -X POST https://puzzel.org/api/public/v1/quiz \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Quiz",
  "language": "pt",
  "items": [
    {
      "question_type": "multiple_choice",
      "description": "Which fruit is yellow?",
      "answers": [
        {
          "type": "text",
          "description": "Banana",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Cherry",
          "isCorrect": false
        }
      ]
    },
    {
      "question_type": "open_answer",
      "description": "What colour is a lemon?",
      "correct_answer": "Yellow",
      "explanation": "Lemons ripen from green to yellow."
    }
  ]
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}
Abrir o editor Voltar ao topo

Jogo de tabuleiro

api_e_board_game

#
POST /api/public/v1/board-game Pelo menos 1 em items
Conteúdo

api_c_board_game

Por omissão, fica com o nome “Board Game API”

Vale a pena saber
  • question_type é "multiple_choice", em que a opção certa leva isCorrect a true, ou "open_answer", que usa antes correct_answer. Se for deixado de fora, é tratado como escolha múltipla.
Definições que lê
CampoTipoO que faz
number_of_tiles
opcional em settings
number
numberQuantas casas tem o tabuleiro. Entre 10 e 75.
Predefinição: 30
game_mode
opcional em settings
string
stringSe os jogadores correm até à meta ou recolhem itens pelo caminho.
Um de race_to_finishcollect_items
Predefinição: "race_to_finish"
Pedido de exemplo
POST board-game 
curl -X POST https://puzzel.org/api/public/v1/board-game \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Board Game",
  "language": "pt",
  "items": [
    {
      "question_type": "multiple_choice",
      "description": "Which fruit is yellow?",
      "answers": [
        {
          "type": "text",
          "description": "Banana",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Cherry",
          "isCorrect": false
        }
      ]
    },
    {
      "question_type": "open_answer",
      "description": "What colour is a lemon?",
      "correct_answer": "Yellow",
      "explanation": "Lemons ripen from green to yellow."
    }
  ],
  "settings": {
    "number_of_tiles": 30,
    "game_mode": "race_to_finish"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
  "message": "Board Game created successfully"
}
Abrir o editor Voltar ao topo
Frases e números

Criptograma

Transforma uma frase num código para decifrar, um caráter de cada vez.

#
POST /api/public/v1/cryptogram Não recebe items
Conteúdo

Uma frase, no campo sentence. Este endpoint não recebe items.

Por omissão, fica com o nome “Cryptogram API”

Vale a pena saber
  • Tudo o que enviares em items é ignorado — o quebra-cabeças é criado apenas a partir da frase.
Definições que lê
CampoTipoO que faz
sentence
obrigatório
string
stringA frase a encriptar. Os jogadores descodificam-na caráter a caráter.
helpers
opcional em settings
string
stringQue carateres são revelados à partida como entrada: nenhuns, os mais comuns, as vogais, ou os que indicares.
Um de nonemost_commonvowelscustom
Predefinição: "none"
character_list
opcional em settings
string
stringO alfabeto com que a cifra é construída. Se ficar vazio, a encriptação escolhe o dela.
extra_letters
opcional em settings
string
stringOs carateres revelados quando helpers é "custom". Ignorado nos outros modos de ajuda.
hide_unused_characters
opcional em settings
boolean
booleanDeixa de fora da chave os carateres que a frase nunca usa.
Predefinição: false
Pedido de exemplo
POST cryptogram 
curl -X POST https://puzzel.org/api/public/v1/cryptogram \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Cryptogram",
  "language": "pt",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}
Abrir o editor Voltar ao topo

Exercício de cálculo

Esconde uma frase por trás de contas — resolve a conta, revela a letra.

#
POST /api/public/v1/calculation Não recebe items
Conteúdo

Uma frase, no campo sentence. Este endpoint não recebe items.

Por omissão, fica com o nome “Calculation Game API”

Vale a pena saber
  • Se as restrições forem demasiado apertadas para codificar a frase, a chamada responde 400 a pedir que as alargues, em vez de guardar um quebra-cabeças incompleto.
Definições que lê
CampoTipoO que faz
sentence
obrigatório
string
stringA frase que os jogadores descobrem ao resolver as contas.
difficulty_level
opcional em settings
number
numberO resultado mais alto que uma conta pode ter.
Um de 20501001000
Predefinição: "100"
operators
opcional em settings
string[]
string[]Que operações podem aparecer. x é multiplicar, : é dividir.
Um de +-x:
Predefinição: ["+", "-", "x", ":"]
max_operations
opcional em settings
number
numberQuantas operações uma conta pode encadear.
Um de 123
Predefinição: 1
number_difficulty
opcional em settings
number
numberLimita os números individuais dentro de uma conta. De 5 a 1000.
Predefinição: 100
Pedido de exemplo
POST calculation 
curl -X POST https://puzzel.org/api/public/v1/calculation \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Calculation Game",
  "language": "pt",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}
Abrir o editor Voltar ao topo

Sudoku

Gera uma grelha resolvida e depois volta a retirar números.

#
POST /api/public/v1/sudoku Não recebe items
Conteúdo

Nada. O quebra-cabeças inteiro sai das duas definições dele.

Por omissão, fica com o nome “Sudoku API”

Vale a pena saber
  • Não envies items nem sentence — size e difficulty são toda a entrada.
  • O editor só oferece a dificuldade para 2x3, 3x3 e 3x4. A API aplica-a a todos os tamanhos, incluindo 2x2 e 4x4.
Definições que lê
CampoTipoO que faz
size
opcional em settings
string
stringO tamanho de um bloco, escrito como linhas por colunas — 3x3 dá a grelha clássica de 9x9. O endpoint só verifica se é interpretável como dois números, por isso fica-te pelos tamanhos que o editor oferece.
Um de 2x22x33x33x44x4
Predefinição: "3x3"
difficulty_level
opcional em settings
string
stringQuantos números ficam no tabuleiro para começar.
Um de easynormalhard
Predefinição: "normal"
Pedido de exemplo
POST sudoku 
curl -X POST https://puzzel.org/api/public/v1/sudoku \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sudoku",
  "language": "pt",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}
Abrir o editor Voltar ao topo
Imagens

Puzzle

Corta uma imagem em peças para voltar a juntar arrastando.

#
POST /api/public/v1/jigsaw Não recebe items
Conteúdo

Um URL de imagem, no campo image. Este endpoint não recebe items.

Por omissão, fica com o nome “Jigsaw Game API”

Vale a pena saber
  • A API cria sempre um puzzle de 4 por 4. O número de peças, as peças irregulares e os bordos direitos são definições do editor — enviar rows ou columns aqui não faz nada.
  • O URL é guardado tal como o enviaste e o ficheiro nunca é copiado, por isso tem de continuar publicamente acessível enquanto a atividade for jogada.
Definições que lê
CampoTipoO que faz
image
obrigatório
string
stringURL absoluto da imagem a cortar. Enviado no nível superior, não dentro de settings.
Pedido de exemplo
POST jigsaw 
curl -X POST https://puzzel.org/api/public/v1/jigsaw \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Jigsaw Game",
  "language": "pt",
  "image": "https://example.com/orchard.jpg"
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}
Abrir o editor Voltar ao topo

Puzzle deslizante

Baralha uma imagem em peças que deslizam para o lugar.

#
POST /api/public/v1/slidingpuzzle Não recebe items
Conteúdo

Um URL de imagem, dentro de settings. Este endpoint não recebe items.

Por omissão, fica com o nome “Sliding Puzzle API”

Vale a pena saber
  • Ao contrário do puzzle, este endpoint lê a imagem de settings.image. Um campo image no nível superior é ignorado e a chamada responde 400.
  • O URL é guardado tal como o enviaste e o ficheiro nunca é copiado, por isso tem de continuar publicamente acessível enquanto a atividade for jogada.
Definições que lê
CampoTipoO que faz
image
obrigatório em settings
string
stringURL absoluto da imagem a baralhar. Ao contrário da do puzzle, esta fica dentro de settings.
Pedido de exemplo
POST slidingpuzzle 
curl -X POST https://puzzel.org/api/public/v1/slidingpuzzle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sliding Puzzle",
  "language": "pt",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
Sucesso 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}
Abrir o editor Voltar ao topo

Algo não está a funcionar bem?

Envia o pedido que tentaste e o erro que recebeste e terás uma resposta a sério, de quem escreveu o endpoint.

Enviar e-mail ao suporte