Peças, agenda e publicação
O ciclo de uma peça
rascunho (pico_studio) → compromisso no calendário (post: pendente) → publicada | falhou | cancelada
POST /v1/pecas POST /v1/pecas/{id}/agendar POST /v1/pecas/{id}/publicarGET /v1/pecas devolve os dois numa lista só: origem: "rascunho" (o que a IA gerou) e origem: "calendario" (o compromisso, com status, scheduledAt, publishedAt e metrics quando publicada). ?estado=rascunho|agendada|publicada|todas.
Criar (IA do Pico)
POST /v1/pecas
{ "kind": "script", "brief": "Gancho: 3 looks com a mesma calça. Oferta: frete grátis.", "titulo": "opcional", "provenance": { "hookText": "3 looks com a mesma calça", "nicheLabel": "moda casual" } }kind | O que sai em body |
|---|---|
script | roteiro de 30 s: HOOK (0–3 s), CORPO, CTA, com cortes |
brief | brief de 1 página: objetivo, público, ângulo, gancho, prova, CTA, o que não fazer |
hooks | 12 ganchos verbatim com o tipo entre colchetes |
carousel | JSON {"slides":[{"titulo":"…","texto":"…"}]} — o app desenha as lâminas |
O perfil do negócio (tom, o que não fazer, CTA) entra no prompt sozinho. provenance é de onde veio o gancho — é o que responde, semanas depois, "peça com gancho de outlier performou melhor?".
PUT /v1/pecas/{id} edita title/body de um rascunho. DELETE apaga rascunho; em compromisso pendente, cancela.
Agendar
POST /v1/pecas/{id}/agendar
{ "dia": "2026-09-15", "cta": "opcional", "clientId": "só em modo agência" }Vira compromisso (201, postId). Não publica. Brief e lista de ganchos não vão para o calendário (400 kind_nao_publica) — são matéria-prima para roteiro ou carrossel.
Publicar agora
Publicar é irreversível: a rede não guarda rascunho. Por isso exige o escopo
publicacaoe"confirmar": trueliteral.
POST /v1/pecas/{id}/publicar
{ "confirmar": true }Sem confirmar: 400 confirmacao_ausente com a explicação — o cliente mostra, a pessoa diz sim, repete. A resposta feliz:
{ "acao": "publicado", "permalink": "https://www.instagram.com/p/…", "socialapiPostId": "…", "statusPonte": "published" }Os outros desfechos são problem+json com o mesmo nome do acao do motor:
| Status | code | Quer dizer |
|---|---|---|
| 200 | ja_publicado | já tinha saído; nada feito de novo (resposta feliz, acao) |
| 409 | sem_midia | a peça não tem imagem/vídeo acessível pelo servidor — prepare pela tela (Conteúdo → peça) |
| 409 | sem_conta | nenhuma conta da rede conectada e ativa — POST /v1/conexoes/{rede} |
| 409 | em_andamento | outra chamada está publicando esta peça |
| 429 | adiado | teto de publicações da conta na rede; o cron diário tenta depois |
| 502 | falhou | a rede/ponte respondeu erro; detail traz o motivo |
Leads e respostas
GET /v1/leads lista comentários e DMs que pedem resposta, com windowEndsAt (7 dias para private reply de comentário; 24 h para DM) e public (se a resposta será um comentário público).
POST /v1/leads/{id}/responder
{ "texto": "Oi! Te chamei no direct com o link.", "confirmar": true }Escopo publicacao, confirmar: true. enviado traz canal (comment/dm) e ref. Desfechos: janela_fechada (409), ja_respondido (409, 1 private reply por comentário), cota_esgotada (429), nao_encontrado (404).
GET /v1/inbox?aba=mensagens|comentarios|avaliacoes mostra o inbox da ponte só das suas contas; ?conversa=ID abre uma conversa. Só leitura.
O que cada rede permite
GET /v1/conexoes diz, por rede: canPublish, canReadComments, canPrivateReply, canStartDm, dmAllowsLinks. Instagram fecha o ciclo comentário → DM com link; TikTok não tem comentário→DM e a DM não aceita link. A API diz isso antes, em vez de falhar depois.
Resultado
GET /v1/resultado?de=2026-09-01&ate=2026-09-30 — só publicadas, com métricas (curtidas, comentários, compartilhamentos, salvamentos) e os totais do período.