Idempotência e operações
Toda escrita vira uma operação assíncrona. A chave de idempotência garante que repetir o pedido não publica nem responde duas vezes.
Idempotency-Key
Publicações, respostas, moderação e criação de regras exigem o cabeçalho Idempotency-Key: de 1 a 100 caracteres [A-Za-z0-9_.:-], estável para aquela intenção.
- Mesma chave e mesmo corpo devolvem a mesma operação, sem nova reserva de franquia.
- Mesma chave com outro corpo devolve 409
chave_reutilizada. - Sem o cabeçalho, 428
idempotency_key_ausente. - Importação de mídia não tem chave: repetir pode criar outro arquivo. Guarde o resultado.
Gere a chave quando a intenção nasce no seu sistema (por exemplo, o ID do post aprovado) e reutilize em todas as tentativas.
# Mesma intenção = mesma chave. Gere uma vez e guarde junto do pedido.
curl -X POST "https://ig.keymatic.com.br/api/instagram/publicacoes" \
-H "Authorization: Bearer $KEYMATIC_API_KEY" \
-H "Idempotency-Key: lancamento-2026-11-10" \
-H "Content-Type: application/json" \
-d '{"formato":"imagem","arquivos":["<url-importada>"],"legenda":"Chegou","executar_em":"2026-11-10T12:00:00-03:00"}'
# 202
{"operacao_id":"<uuid>","estado":"agendada","executar_em":"2026-11-10 15:00:00+00:00","resultado":null,"erro":null}Estados (202)
Escritas devolvem 202 com operacao_id, estado, executar_em, resultado e erro. Consulte GET /operacoes/{operacao_id} até um estado final; a consulta não consome franquia.
| Estado | Significado |
|---|---|
reservada | Reserva interna. Ainda não houve efeito no Instagram. |
agendada | Aguardando o horário ou o worker. Só publicação pode ser cancelada neste estado. |
processando | Etapas de mídia em andamento. Continue consultando o mesmo ID. |
incerta | A intenção foi confirmada antes da rede, mas o resultado não. Pode ser passageira ou persistir após queda. |
publicada | Publicação confirmada. O permalink pode chegar depois. |
concluida | Ação concluída com resultado. |
erro | Falha definitiva. Leia o motivo antes de preparar outra intenção. |
cancelada | Agenda interrompida antes do envio. |
curl "https://ig.keymatic.com.br/api/instagram/operacoes/<operacao_id>" \
-H "Authorization: Bearer $KEYMATIC_API_KEY"Polling
Esta versão não envia webhooks de saída: acompanhe por consulta. Espaçe as consultas e respeite o seu limite por minuto; agendamentos podem ficar em agendada por até 30 dias. Para cancelar uma publicação ainda agendada, use POST /operacoes/{operacao_id}/cancelamento.
Reconciliar uma operação incerta
Em incerta, não repita com outra chave de idempotência nem com outra credencial. Isso pode duplicar a publicação ou a resposta.
- Se o POST original ainda está em andamento, aguarde e consulte de novo: a consulta pode ver a intenção antes do recibo.
- Se continuar
incerta, confira no Instagram se o efeito aconteceu (a publicação, a resposta, o comentário oculto). - Só prepare uma nova intenção, com nova chave, depois de confirmar que o efeito não ocorreu.
O worker não retoma incerta sozinho. Um resultado incerto conserva a reserva de franquia do que pode ter sido enviado; cancelamento e erro definitivo liberam a reserva de publicação.