Referência da API

API Post4me

A API que move o app da Post4me: marcas, posts, templates, artes e as IAs que escrevem e desenham. Esta é a documentação oficial, com exemplos prontos e teste ao vivo em cada endpoint.

URL base

Toda chamada é POST com corpo JSON (exceto a de saúde). As respostas são JSON.

Autenticação

Cada requisição leva dois cabeçalhos:

Cabeçalho	O que é
Authorization	Bearer <access_token>, o mesmo token que o login do app devolve. Vale até expirar ou até o logout.
X-Agency-Slug	O slug da agência (aparece no login e no endereço do app). A pessoa precisa ter vínculo ativo com ela.

Permissões

• Dono e admin: tudo.
• Editor: tudo do Estúdio, posts, marcas e planejamento; não gerencia equipe nem a agência.
• Modo suporte (só leitura): apenas consultas (list, imagem, pacote…).

Authorization: Bearer 8f3c…e21a
X-Agency-Slug: minha-agencia
Content-Type: application/json

Créditos de IA

Ações que usam IA (gerar template, escrever textos, foto com IA, ajuda do editor…) reservam créditos antes de rodar. Se a ação falhar, os créditos voltam sozinhos.

• Gemini é a base. ChatGPT conta 2× e Claude 4× quando usam a chave da Post4me.
• Com chave própria (BYOK), a ação não consome créditos.
• Sem saldo, a resposta é 402 com error: "sem_creditos", o saldo e o necessário.

{
  "success": false,
  "error": "sem_creditos",
  "message": "Seus créditos de IA acabaram…",
  "saldo": 2,
  "necessario": 5,
  "acao": "studio:post_foto_ia"
}

Erros

Status	error	Quando
401	unauthorized	Token ausente, expirado ou revogado. Faça login de novo.
402	sem_creditos	Créditos de IA insuficientes.
402	billing_blocked	Agência sem plano ou com pagamento pendente.
403	forbidden	Sem vínculo com a agência ou papel sem permissão.
404	agency_not_found	Slug de agência inexistente.
502/504	motor_indisponivel / motor_timeout	O motor de criativos não respondeu a tempo. Tente de novo.

{
  "success": false,
  "error": "unauthorized",
  "message": "Sessão inválida ou expirada."
}