logo
APIIntegrações•

Crie links e QR codes em massa a partir de uma planilha

Um link curto ou QR code dinâmico por linha da planilha — importação CSV, os endpoints em massa da API ou um cenário no Make, Zapier ou n8n — sem duplicar.

Avatar for undefined
CodeQR Team
Equipe de Conteúdo

Você tem uma planilha — produtos, mesas, notas fiscais, assentos de um evento — e quer um link curto ou um QR code dinâmico por linha, com a URL curta de volta na planilha. Este guia compara os três caminhos que a CodeQR oferece e depois percorre os dois que rodam sozinhos: os endpoints em massa e uma automação por linha.

Disponibilidade

  • Plano: todos os planos. Cada link ou QR code criado conta na cota mensal do workspace, e cada chamada de API conta no limite por minuto da chave (Free 60, Starter 100, Pro 500, Business 1.000, Scale 10.000). Importações de 50 linhas ou mais numa janela curta exigem um workspace verificado (plano pago com forma de pagamento, ou histórico consolidado).
  • Onde: importação CSV em Links e QR Codes; POST https://api.codeqr.io/links/bulk e POST https://api.codeqr.io/qrcodes/bulk; Make, Zapier, n8n e IFTTT em Configurações → Integrações.

Antes de começar

  • Limpe a planilha: uma linha por item, uma coluna com a URL de destino (começando com https://) e uma coluna com um identificador estável (SKU, número da mesa, id da linha). Linhas sem URL válida são rejeitadas uma a uma — as demais passam.
  • Decida o domínio e se quer uma key personalizada por linha (go.example.com/mesa-12) ou aleatória.
  • Acrescente uma coluna vazia para o resultado (shortLink) e, se usar QR codes, outra para a URL da imagem.
  • Chaves são únicas por domínio: uma segunda linha com a mesma key falha com Duplicate key: this short link already exists. — é isso que impede reexecuções acidentais de criar gêmeos.

Escolha um caminho

  • Importação CSV no painel — melhor para um lote único, sem chave nem ferramenta. Envie o arquivo, mapeie as colunas, receba um e-mail quando a fila terminar: Importe links em massa de um arquivo CSV e Importe QR Codes em massa de um arquivo CSV.
  • Endpoints em massa — melhor quando um script ou backend é dono da planilha: até 100 itens por requisição, uma resposta listando o que foi criado e o que falhou.
  • Automação por linha (Make, Zapier, n8n, IFTTT) — melhor quando a planilha continua crescendo e uma pessoa acrescenta linhas: um gatilho de "nova linha" roda um passo Create a Link ou Create a QR Code por linha e escreve o resultado de volta.

Passos: os endpoints em massa

  1. Monte um array de objetos de link, no máximo 100 por requisição. url é obrigatório; domain, key, externalId, tagIds, comments são opcionais e por item.
curl -X POST https://api.codeqr.io/links/bulk \
  -H "Authorization: Bearer codeqr_••••••••••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '[
    {"url":"https://example.com/products/1","domain":"go.example.com","key":"docs-bulk-1"},
    {"url":"https://example.com/products/2","domain":"go.example.com","key":"docs-bulk-2"},
    {"url":"https://example.com/products/3","domain":"go.example.com","key":"docs-summer"},
    {"url":"nope","domain":"go.example.com","key":"docs-bulk-4"}
  ]'
  1. Leia a resposta. Ela é 200 mesmo quando algumas linhas falham: um array plano na mesma ordem, em que cada elemento é o link criado (com id e shortLink) ou um objeto com a sua entrada em link mais error e code:
[
  { "id": "cmsxh5cex000iwu8tnt5u72o3", "domain": "go.example.com", "key": "docs-bulk-1", "shortLink": "https://go.example.com/docs-bulk-1", "url": "https://example.com/products/1", "clicks": 0 },
  { "id": "cmsxh5ci5000kwu8t6qn2pgam", "domain": "go.example.com", "key": "docs-bulk-2", "shortLink": "https://go.example.com/docs-bulk-2", "url": "https://example.com/products/2", "clicks": 0 },
  { "link": { "url": "https://example.com/products/3", "domain": "go.example.com", "key": "docs-summer" }, "error": "Duplicate key: this short link already exists.", "code": "conflict" },
  { "link": { "url": "nope", "domain": "go.example.com", "key": "docs-bulk-4" }, "error": "Invalid destination URL", "code": "unprocessable_entity" }
]

Escreva shortLink na coluna de resultado das linhas que têm id; registre o error das outras ao lado da linha e corrija a planilha.

  1. QR codes usam a mesma forma em POST /qrcodes/bulk — cada item precisa de type (url para um código do tipo link) e url, mais title, cores e tamanho opcionais:
curl -X POST https://api.codeqr.io/qrcodes/bulk \
  -H "Authorization: Bearer codeqr_••••••••••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '[{"type":"url","url":"https://example.com/table/1","title":"Table 1"}]'

A resposta é um array de objetos de QR code (id, domain, key, shortLink, title, image). Códigos criados em massa não têm miniatura armazenada — image vem null e assim fica — mas a imagem está sempre disponível em https://api.codeqr.io/qr?url=<shortLink>?qr=1 (PNG de 1024 px). Detalhes dos campos em Crie QR Codes com a API, o MCP e automações.

  1. Dose as requisições. Com 100 itens por chamada, 1.000 linhas são 10 chamadas — bem dentro do limite por minuto de qualquer plano. Se você também cria tags ou lê links de volta por linha, conte essas chamadas, e durma até o próximo minuto ao receber 429.
  2. Torne reexecuções seguras. Coloque o id da linha em externalId (ou uma key determinística): a segunda execução responde 409 para as linhas que já existem e cria só as novas. Consulte uma linha a qualquer momento com GET /links/info?externalId=ext_<seu id>.

Passos: uma linha, um link, no Make, Zapier ou n8n

  1. Ative a integração em Configurações → Integrações (Make e Zapier autorizam com um clique; n8n usa uma chave de API). Detalhes por plataforma em Conecte a CodeQR ao Zapier, Make, n8n e IFTTT.
  2. Comece o cenário com o gatilho de "nova linha" da sua planilha (Google Sheets, Excel, Airtable, Notion — o que guardar as linhas).
  3. Acrescente o passo da CodeQR: Create a Link (mapeie a coluna da URL em URL e, se quiser, Key, Domain, External ID, Tag IDs, Title) ou Create a QR Code (mapeie URL; escolha o tipo de QR e as cores uma vez).
  4. Acrescente um passo de "atualizar linha" que escreva o link curto devolvido (shortLink) — e, para QR codes, a URL da imagem — na coluna de resultado.
  5. Rode uma vez com uma única linha nova, confira o link em Links ou QR Codes e então ligue o cenário.

Verifique se funcionou

  • Depois de uma requisição em massa, GET /links/count cresceu na quantidade de itens criados, e as linhas novas aparecem em Links com as chaves que você enviou.
  • Numa automação, acrescente uma linha e observe o histórico do cenário: uma execução, um link, uma URL curta escrita de volta. Duas execuções para uma linha significam que o gatilho está disparando na sua própria escrita de volta — veja Solução de problemas.
  • Abra um link curto: dois a três minutos depois ele mostra um clique em Análise.

Solução de problemas

Toda linha foi criada duas vezes

O passo de "atualizar linha" alterou a linha que o gatilho de "nova linha" observa, e o cenário rodou de novo. Escreva o resultado numa outra aba ou numa coluna que o gatilho ignore, ou filtre o gatilho por "coluna de resultado vazia". No n8n e no Make, um item por linha de entrada é o esperado — conte os itens de entrada antes de assumir duplicação.

Algumas linhas voltaram com conflict

Aquela key já existe naquele domínio (ou o externalId já foi usado). Ou a linha foi processada numa execução anterior — nada a fazer — ou duas linhas compartilham a mesma chave: torne as chaves únicas ou deixe a CodeQR gerar omitindo key.

Invalid destination URL

A célula não contém uma URL completa. Acrescente https:// e remova espaços ou quebras de linha; o endpoint em massa valida cada linha isoladamente, então o resto do lote passou.

A API diz "Creating N links at once requires a verified workspace"

Lotes de 50 linhas ou mais numa janela curta ficam retidos para workspaces sem plano pago com forma de pagamento ou sem histórico consolidado. A mensagem diz o que libera (assinar com forma de pagamento, ou concluir o checkout), ou envie menos de 50 por vez.

429 no meio do lote

Você bateu no limite por minuto da chave (veja Disponibilidade). Espere o próximo minuto e reenvie só as linhas que ainda não têm id — com externalId em cada linha, reenviar tudo também é seguro.

As imagens dos QR codes vêm null

Códigos criados por POST /qrcodes/bulk não recebem miniatura armazenada. Use https://api.codeqr.io/qr?url=<shortLink>?qr=1 na planilha, ou crie os códigos um a um com POST /qrcodes quando precisar do campo image preenchido.

Artigos relacionados