Guia de programação

Autenticação

Cria uma chave de API no painel em Definições, API e webhooks. As chaves começam por ss_live_, pertencem a um espaço de trabalho e podem ser limitadas a determinados projetos. Envia a chave como token bearer em cada pedido:

curl https://www.amaposta.com/api/v1/me \
  -H "Authorization: Bearer ss_live_…"

A resposta indica o nome da chave, as suas permissões e o espaço de trabalho. Cada chave tem uma ou mais permissões:

Cada chave pode fazer 120 pedidos por minuto. Acima desse limite, recebes 429 com o código rate_limited; espera um momento e tenta novamente.

Projetos e canais

As publicações pertencem a um projeto. Lista os projetos que a tua chave pode ver e depois os canais de um deles. Precisas do ID de um canal para o selecionar ou substituir o respetivo texto.

curl https://www.amaposta.com/api/v1/projects \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/channels \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Um canal tem um provider (youtube, instagram, tiktok, x, facebook, custom ou sandbox), um status (active, expiring, needs_reconnect, error ou disabled) e os tipos de publicação que supports.

Carregar ficheiros multimédia

As imagens e os vídeos são carregados uma vez por projeto e podem ser usados em qualquer número de publicações. Há três formas de os adicionar.

Carregamento direto

Envia o ficheiro como dados de formulário multipart num campo chamado file. Ideal para ficheiros até algumas centenas de MB.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -F "[email protected]"

Carregamento pré-assinado para ficheiros grandes

Pede um URL de carregamento, envia os bytes diretamente para o armazenamento com PUT e informa Amaposta de que terminaste.

# 1. Ask for an upload URL. The response is {"media": { … }, "upload_url": "…"}
curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media/uploads \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "batch-142.mp4", "content_type": "video/mp4", "size_bytes": 48213844}'

# 2. Upload the bytes to upload_url
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --upload-file batch-142.mp4

# 3. Finish the upload
curl -X POST https://www.amaposta.com/api/v1/media/$MEDIA_ID/complete \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Importar de um URL

Dá a Amaposta um URL público para descarregar o ficheiro em segundo plano. Também podes ignorar este passo e passar media_url ao criar a publicação.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media/import \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://cdn.example.com/batch-142.mp4"}'

Cada carregamento devolve um objeto multimédia. O seu status passa de pending para processing e para ready (ou failed, com um error). Depois de processado, inclui width, height, duration_ms e uma miniatura. Consulta periodicamente GET /api/v1/media/{id} ou escuta o webhook media.ready. O url devolvido é assinado e válido durante 12 horas.

Criar uma publicação

POST /api/v1/projects/{project_id}/posts cria uma publicação com uma entrega por canal. Amaposta adapta-a a cada plataforma: os títulos só são enviados quando existe um campo de título, as hashtags tornam-se etiquetas no YouTube e texto integrado nas restantes.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/posts \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: episode-142" \
  -d @- <<'JSON'
{
  "kind": "video",
  "title": "How we roast a batch in 12 minutes",
  "description": "From green beans to first crack. We filmed one batch start to finish.",
  "hashtags": ["coffee", "behindthescenes"],
  "media_url": "https://cdn.example.com/batch-142.mp4",
  "cover_url": "https://cdn.example.com/batch-142-cover.jpg",
  "overrides": {
    "<x-channel-id>": {
      "description": "Batch 142 is out: green beans to first crack in 12 minutes."
    },
    "<youtube-channel-id>": {
      "options": { "privacy": "unlisted" }
    }
  },
  "schedule": { "mode": "queue" },
  "external_ref": "episode-142",
  "metadata": {
    "pipeline": { "name": "nightly-cut", "run": "2026-10-17" }
  }
}
JSON

Campos

A resposta é a publicação, incluindo uma entrada em deliveries por canal.

Novas tentativas seguras

As redes perdem pedidos. Envia um cabeçalho Idempotency-Key ao criar uma publicação e uma nova tentativa com a mesma chave devolve a publicação da primeira tentativa em vez de criar outra. Usa um valor estável do teu lado, como um ID de tarefa ou episódio. As chaves são truncadas a 200 carateres.

Agendar e publicar

Agenda um rascunho, publica-o agora, adiciona-o à fila ou retira-o do calendário com POST /api/v1/posts/{post_id}/schedule.

curl https://www.amaposta.com/api/v1/posts/$POST_ID/schedule \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "at", "at": "2026-10-20T07:00:00Z"}'

• atPublica à hora indicada, com até dois anos de antecedência.
• nowPublica de imediato.
• queueUsa o próximo horário de publicação livre dos canais da publicação nas próximas 12 semanas.
• unscheduleMove a publicação de volta para os rascunhos.

Antes de qualquer agendamento, são executadas as mesmas verificações do editor. Se alguma falhar, o pedido devolve 400 com uma mensagem como Corrige isto antes de agendar: o YouTube precisa de um título. O agendamento exige a permissão posts:publish ou um projeto com aprovações ativadas; nesse caso, a publicação aguarda na caixa de revisão.

Ler publicações e entregas

Lista as publicações de um projeto, filtradas por status (estados separados por vírgulas ou inbox, queue ou history), um intervalo from/to, limit e offset. A resposta é {"items": […], "total": n}.

curl "https://www.amaposta.com/api/v1/projects/$PROJECT_ID/posts?status=queue" \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

curl https://www.amaposta.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Uma publicação tem um status global (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial ou failed) e uma entrega por canal:

"deliveries": [
  {
    "id": "0192b7d4-…",
    "channel_id": "0192b7a1-…",
    "status": "published",
    "url": "https://www.youtube.com/watch?v=…",
    "error": null,
    "published_at": "2026-10-20T07:00:41Z"
  },
  {
    "id": "0192b7d4-…",
    "channel_id": "0192b7a9-…",
    "status": "failed",
    "url": null,
    "error": {
      "code": "endpoint_unavailable",
      "message": "Your endpoint returned 503 Service Unavailable",
      "hint": "Amaposta will retry with backoff."
    },
    "published_at": null
  }
]

Os estados de entrega são pending, scheduled, publishing, processing, published, failed e cancelled. DELETE /api/v1/posts/{post_id} remove uma publicação.

Erros

Todos os erros têm a mesma estrutura: um objeto error com um code estável, uma message que podes mostrar às pessoas e, por vezes, fields (mensagens por campo) e uma hint.

{
  "error": {
    "code": "validation",
    "message": "Please fix the highlighted fields.",
    "fields": {
      "kind": "Use text, image or video."
    }
  }
}

Webhooks

Adiciona um endpoint em Definições, API e webhooks, escolhe os eventos e copia o segredo de assinatura. Amaposta envia JSON por POST para o teu URL para cada evento. Qualquer resposta diferente de 2xx ou a ausência de resposta em 15 segundos origina novas tentativas com intervalos crescentes; os endpoints que continuam a falhar são desativados com um aviso aos administradores.

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Amaposta-Webhooks/1.0
X-Amaposta-Event: post.published
X-Amaposta-Event-Id: 0192b7e0-…
X-Amaposta-Signature: t=1792479641,v1=5f2b0c…

{
  "id": "0192b7e0-…",
  "type": "post.published",
  "created_at": "2026-10-20T07:00:41Z",
  "project_id": "0192a3f1-…",
  "data": {
    "post_id": "0192b7c8-…",
    "delivery_id": "0192b7d4-…",
    "channel_id": "0192b7a1-…",
    "provider": "youtube",
    "external_id": "…",
    "url": "https://www.youtube.com/watch?v=…"
  }
}

Verificar a assinatura

X-Amaposta-Signature é t=<unix seconds>,v1=<hex>, em que v1 é HMAC_SHA256(secret, t + "." + body) calculado sobre o corpo original do pedido. Calcula-o, compara em tempo constante e rejeita carimbos de data/hora antigos para impedir repetições.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (string or Buffer).
export function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

import hashlib
import hmac
import time


def verify_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Um canal de API personalizada publica num endpoint HTTPS que geres: o teu CMS, uma ferramenta de newsletters, uma plataforma que Amaposta ainda não abrange. Aparece no calendário e tem verificações, aprovações e novas tentativas como qualquer outro canal. Quando uma publicação sai, Amaposta envia um POST por entrega:

POST /amaposta/publish HTTP/1.1
Authorization: Bearer <your API key>
Content-Type: application/json
Idempotency-Key: 0192b7d4-…
X-Amaposta-Delivery: 0192b7d4-…
X-Amaposta-Signature: t=1792479600,v1=9ac41e…

{
  "id": "0192b7d4-…",
  "type": "post.publish",
  "created_at": "2026-10-20T07:00:00Z",
  "content": {
    "kind": "video",
    "title": "How we roast a batch in 12 minutes",
    "text": "From green beans to first crack. We filmed one batch start to finish.",
    "hashtags": ["coffee", "behindthescenes"],
    "media": {
      "url": "https://…",
      "content_type": "video/mp4",
      "size_bytes": 48213844,
      "width": 1080,
      "height": 1920,
      "duration_ms": 58000,
      "filename": "batch-142.mp4"
    },
    "cover": null,
    "options": {}
  },
  "post": {
    "id": "0192b7c8-…",
    "external_ref": "episode-142",
    "scheduled_at": "2026-10-20T07:00:00Z",
    "metadata": {
      "pipeline": { "name": "nightly-cut" }
    }
  },
  "project": { "id": "0192a3f1-…", "name": "Spring launch" },
  "channel": { "id": "0192b7a9-…", "name": "api.example.com" }
}

Authorization

A tua chave de API. O nome do cabeçalho e o prefixo (Bearer por predefinição) são definidos no canal.

Idempotency-Key

O ID da entrega. Uma nova tentativa da mesma entrega envia a mesma chave, para poderes ignorar trabalho já realizado.

X-Amaposta-Delivery

O ID da entrega novamente, para os teus registos.

X-Amaposta-Signature

Assinados como os webhooks, com o segredo de assinatura do próprio canal.

Como responder

• 2xxPublicada. Podes devolver {"id": "…", "url": "…"} e a ligação aparece na publicação.
• 401, 403A chave foi rejeitada. O canal é assinalado para voltar a ligar e os administradores são informados. Não uses estes códigos para uma assinatura inválida.
• 5xx, 408, 429Temporário. Amaposta tenta novamente com intervalos crescentes.
• Outros 4xxA publicação é marcada como falhada com a tua mensagem e alguém pode corrigi-la e premir Tentar novamente.

app.post("/amaposta/publish", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.get("X-Amaposta-Signature") ?? "";
  if (!verifySignature(req.body, signature, process.env.AMAPOSTA_SIGNING_SECRET)) {
    return res.status(400).json({ message: "Bad signature" });
  }
  const delivery = JSON.parse(req.body);
  const item = await publishToYourSystem(delivery.content, req.get("Idempotency-Key"));
  res.json({ id: item.id, url: item.url });
});

O teu endpoint tem de estar acessível pela Internet; os redirecionamentos não são seguidos. Ao ligares o canal, Amaposta verifica-o com GET para o teu URL de funcionamento, se o definires, ou com um pedido OPTIONS para o endpoint.

Um canal Sandbox comporta-se como um canal real, mas nada sai de Amaposta. Usa-o para criar e testar a tua integração de ponta a ponta: as publicações são agendadas, entram no ar, são publicadas ou falham e acionam os mesmos webhooks. Os canais Sandbox são gratuitos em todos os planos e não contam para os limites de canais.

Escolhe como se comporta ao adicioná-lo:

• Ter sempre sucessoTodas as publicações são publicadas.
• Falhar de vez em quandoVê as falhas e as novas tentativas sem esperar por uma interrupção real.
• Falhar sempreTesta o teu tratamento de post.failed.
• Ligação expiradaVê os alertas e as ligações para restabelecer o acesso quando este expira.