Planilhas

Converta links em toda uma planilha do Google ou pasta de trabalho enviada usando o token bearer da sua conta. A saída é sempre .xlsx, inclusive para entradas CSV. Os links são substituídos no próprio lugar, com a atribuição da sua conta e os valores opcionais campaign e label descritos em Links.

Entrada do Google SheetsCopiar link da seção

Envie uma URL do Google Sheets que a NinjaBuy consiga ler. A conversão lê todas as abas, não apenas a prévia exibida, e fixa uma captura para este trabalho.

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://docs.google.com/spreadsheets/d/SHEET_ID/edit","campaign":"spring-haul","label":"finds"}'

Entrada XLSX ou CSVCopiar link da seção

Primeiro reserve um envio. filename deve terminar em .xlsx ou .csv e conter de 1 a 255 caracteres após remover os espaços nas extremidades. bytes é o tamanho exato do arquivo em bytes, de 1 a 20.971.520.

curl -sS https://www.ninjabuy.com/api/v1/uploads \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"filename":"finds.xlsx","bytes":12345}'

A resposta 201 contém upload_id, uma url assinada para PUT, expires_at (milissegundos desde o início da época Unix), max_bytes e request_id. A reserva expira após 15 minutos. Envie o arquivo bruto com PUT para a URL retornada e depois envie o identificador do upload:

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  --data-binary @finds.xlsx

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"upload_id":"UPLOAD_ID","campaign":"spring-haul","label":"finds"}'

O PUT direto usa o contrato de resposta do serviço de armazenamento. A NinjaBuy valida os bytes enviados quando você solicita a conversão. Identificadores de upload desconhecidos ou de outras contas retornam 404. O objeto armazenado deve corresponder à contagem de bytes declarada; um objeto maior que o tamanho declarado ou o máximo retorna 413 upload-too-large, e um objeto menor (truncado) retorna 422 invalid-workbook com a explicação da divergência na contagem de bytes. Essas verificações ocorrem antes do download e também se aplicam se os bytes mudarem após a verificação dos metadados. Os arquivos brutos dos uploads recusados são excluídos, e os dos uploads aceitos são excluídos assim que sua captura validada é registrada.

Envie exatamente uma origem: url ou upload_id. Ambas aceitam campaign e label opcionais; não é necessário um campo async. As duas rotas POST aceitam Idempotency-Key e cada uma consome uma vaga da janela compartilhada de criação de 30 chamadas por minuto. As conversões de links derivadas não consomem vagas adicionais.

Trabalho e downloadCopiar link da seção

O envio de uma planilha retorna 202 com Location: /api/v1/jobs/JOB_ID, Retry-After: 5 e este corpo:

{
  "job": {
    "id": "JOB_ID",
    "kind": "sheet_conversion",
    "status": "queued",
    "poll_after_seconds": 5
  },
  "request_id": "REQUEST_ID"
}

Consulte Tarefas com o token da mesma conta até chegar a done ou failed, respeitando poll_after_seconds. Um job.result concluído tem kind: "sheet_conversion", counts e uma download_url assinada válida por 15 minutos. Consulte novamente para obter uma nova assinatura de download. Um trabalho com falha tem error e não oferece download parcial.

Para uma planilha do Google, job.result também pode incluir copy_url, um link somente leitura para uma cópia exata no Google Planilhas com os seus links no lugar; quem tiver o link pode guardar a própria cópia em Arquivo → Fazer uma cópia. copy_notes informa o que quem ler essa cópia precisa saber, por exemplo que imagens criadas com =IMAGE() precisam de um clique em Permitir acesso na própria cópia. download_url continua retornando o XLSX. copy_counts traz as mesmas contagens para a cópia; quando o XLSX não pode ser gerado, o resultado mantém copy_url, não tem download_url e copy_notes explica o motivo. download_notes lista, linha por linha, o que o XLSX não consegue guardar da planilha, como gráficos ou um segundo link em uma célula.

As capturas e os arquivos de resultados são mantidos por sete dias após a conclusão ou falha do trabalho. Após a limpeza, o trabalho continua disponível para consulta com seu status e suas contagens, e job.result.download_url é omitido. As capturas compartilhadas são mantidas enquanto outro trabalho ainda precisar delas. Os arquivos brutos dos uploads abandonados são excluídos uma hora após a expiração da reserva de envio; um upload validado que nunca inicia um trabalho perde sua captura sete dias após a expiração da reserva. A limpeza é executada a cada hora.

A cobertura satisfaz links_found = converted + sum(left_by_host) + unresolved. Links sociais, do Google Sheets, de navegação dentro da mesma pasta de trabalho e links existentes da NinjaBuy permanecem sem alterações. Cada candidato à conversão deve receber uma resposta antes de gravar a saída; respostas ausentes fazem o trabalho falhar.

Preservação da pasta de trabalhoCopiar link da seção

A saída preserva estilos, células mescladas, tamanhos de linhas e colunas e imagens conforme representados pela grade analisada. Os trechos de texto formatado são preservados em células sem um hiperlink de célula; células com link usam um único rótulo de texto e um hiperlink. É uma pasta de trabalho serializada novamente: gráficos, macros e outros recursos fora dessa grade não são preservados.

XLSX aceita um hiperlink por célula. A conversão substitui os links no próprio lugar em vez de adicionar um segundo link ao lado. Uma célula com dois ou mais destinos de link diferentes que não sejam imagens mantém o primeiro como hiperlink e lista os demais na nota da célula, para que nenhum destino se perca.

LimitesCopiar link da seção

Ultrapassar um limite do analisador ou do gerador causa uma falha explícita. Consulte Erros para invalid-workbook, upload-expired e upload-too-large.