Automação e integração

Chaves de API, uploads em lote e callbacks sem adivinhar as regras do runtime.

Esta página descreve a superfície de integração que já está ativa: como autenticar, preparar uploads, consultar jobs individuais ou batches e anexar callbacks terminais dentro do caminho Pro API atual.

Última atualização: 6 de abril de 2026

Início rápido

O fluxo operacional é propositalmente estreito: primeiro prepare o job, depois envie o arquivo para o destino retornado e então faça polling ou espere o callback.

1Crie uma chave de API na área da conta com um plano Pro.
2Envie POST /uploads/prepare ou POST /uploads/batch/prepare apenas com metadados.
3Envie o binário exatamente para o upload target retornado na resposta.
4Faça polling em GET /jobs/:jobId ou GET /job-batches/:batchId até o resultado ficar ready.
5Adicione callbackUrl e callbackSecret se quiser um evento terminal por push.

Autenticação e modelo de acesso

Requisições server-to-server podem autenticar com X-API-Key. Os fluxos do navegador usam o token de sessão da conta, mas o modelo de integração é centrado nas chaves de API.

- As chaves de API são criadas na conta e o token completo aparece só uma vez.
- A preparação em lote e os webhook callbacks ficam limitados ao caminho Pro API.
- Jobs pesados de audio e video continuam consumindo créditos de mídia da conta proprietária.
- O status de um job individual pode ser consultado com a auth da conta proprietária ou com o status token assinado retornado no prepare.
- O status de batch exige autenticação da conta proprietária e não expõe um caminho público com token.

Headers para polling autenticado

bash

curl https://your-swapmyfile-host.example/jobs/job_123 \
  -H "X-API-Key: smf_live_your_key"

curl https://your-swapmyfile-host.example/jobs/job_123?token=job_status_token

Fluxo individual de prepare-upload-poll

Um job individual começa apenas com metadados. A API devolve o registro do job, o upload target, um status token assinado e a lista de checks que entram depois que o upload é recebido.

- POST /uploads/prepare valida a solicitação antes da transferência do corpo do arquivo.
- A resposta pode devolver um destino API multipart ou um destino direct PUT com completeUrl.
- Depois de concluir o upload, faça polling em GET /jobs/:jobId até o status ficar ready ou failed.
- Quando o status estiver ready, use job.downloadUrl como signed result link.
- callbackUrl e callbackSecret são opcionais por job e podem ser enviados já no prepare.

Preparar um job individual

bash

curl -X POST https://your-swapmyfile-host.example/uploads/prepare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smf_live_your_key" \
  -d '{
    "converterSlug": "jpg-to-png",
    "inputFilename": "hero.jpg",
    "inputMime": "image/jpeg",
    "inputSize": 245001
  }'

Preparação em lote e status agregado

A preparação em lote permite abrir vários upload targets com uma única requisição de API. O backend atual aceita até 25 itens por batch e devolve o batch record junto com as entradas de upload por job.

- POST /uploads/batch/prepare aceita um label opcional e um array jobs.
- Cada job continua enviando converterSlug, filename, mime type, size e callbacks opcionais quando necessário.
- O batch label é limitado a 80 caracteres.
- A UI pública de batch mantém um único conversor por página, mas o payload da API continua job por job.
- Faça polling em GET /job-batches/:batchId com a mesma autenticação da conta proprietária para acompanhar o status agregado.

Preparar uma requisição em lote

bash

curl -X POST https://your-swapmyfile-host.example/uploads/batch/prepare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smf_live_your_key" \
  -d '{
    "label": "April content refresh",
    "jobs": [
      {
        "converterSlug": "jpg-to-png",
        "inputFilename": "hero-01.jpg",
        "inputMime": "image/jpeg",
        "inputSize": 245001
      },
      {
        "converterSlug": "webp-to-png",
        "inputFilename": "hero-02.webp",
        "inputMime": "image/webp",
        "inputSize": 198221
      }
    ]
  }'

Callbacks terminais

Callbacks foram desenhados para a borda terminal do pipeline, não para cada estado intermediário. Hoje o SwapMyFile envia callbacks apenas quando o job termina em ready ou failed.

- Os eventos suportados são job.ready e job.failed.
- callbackUrl deve ser uma URL absoluta http ou https e callbackSecret é opcional.
- Quando callbackSecret está presente, a requisição inclui x-swapmyfile-signature com sha256=<hmac> sobre o body JSON bruto.
- A entrega também inclui os headers x-swapmyfile-event e x-swapmyfile-job-id.
- Uma resposta 2xx marca a entrega como bem-sucedida. Entregas com falha são repetidas até 3 vezes em uma janela curta.

Payload representativo de callback

json

{
  "event": "job.ready",
  "deliveredAt": "2026-04-06T12:00:00.000Z",
  "job": {
    "jobId": "job_123",
    "converterSlug": "jpg-to-png",
    "status": "ready",
    "inputFilename": "hero.jpg",
    "outputFilename": "hero.png",
    "downloadUrl": "/downloads/signed/example",
    "callback": {
      "url": "https://client.example/hooks/swapmyfile",
      "status": "pending",
      "attempts": 0
    }
  }
}

FAQ de integração

Uma sessão guest pode usar o caminho da API?

Não. Usuários guest ainda podem usar o fluxo do navegador, mas chaves de API, callbacks e preparação em lote ficam ligados a uma conta Pro autenticada.

Callbacks substituem totalmente o polling?

Nem sempre. Callbacks ajudam na entrega do estado terminal, mas o polling continua sendo o caminho mais simples para acompanhar jobs em andamento, progresso do batch e disponibilidade de download.

Posso consultar um job individual sem guardar credenciais da conta?

Sim. A resposta de prepare de um job individual inclui um status token assinado que pode ser usado em GET /jobs/:jobId?token=... para acesso apenas ao status.

Abra a conta antes de automatizar contra produção.

Crie a chave de API, confirme os limites do plano da conta proprietária e recarregue créditos de mídia antes se o fluxo incluir jobs pesados de audio ou video.

Abrir conta Rever preços