Por que o lifecycleState do LinkedIn só aceita PUBLISHED na criação

O que o lifecycleState do LinkedIn faz na Posts API?

O campo lifecycleState do LinkedIn define o estado de um post e, na criação, aceita um único valor: PUBLISHED. O schema da Post API no Microsoft Learn diz isso em uma linha: "PUBLISHED is the only accepted field during creation." O schema marca o campo como Enum string e required, então você também não pode deixá-lo de fora.

Toda requisição de exemplo na página da Posts API traz a mesma linha:

{
  "author": "urn:li:organization:5515715",
  "commentary": "Sample text Post",
  "visibility": "PUBLIC",
  "distribution": {
    "feedDistribution": "MAIN_FEED",
    "targetEntities": [],
    "thirdPartyDistributionChannels": []
  },
  "lifecycleState": "PUBLISHED",
  "isReshareDisabledByAuthor": false
}

Uma criação bem-sucedida devolve 201, e o LinkedIn coloca o ID do novo post no header de resposta x-restli-id como urn:li:share:{id} ou urn:li:ugcPost:{id}.

Quais valores o lifecycleState pode devolver?

O LinkedIn documenta quatro valores, e três deles você só vai ler, nunca enviar.

O schema apresenta os três últimos com uma ressalva simples: "The following values can be returned in responses." Eles descrevem posts, não são instruções para o LinkedIn.

PUBLISH_REQUESTED é o que confunde as integrações. O LinkedIn diz que o conteúdo nesse estado "will be published asynchronously once the processing has successfully completed." Um 201 na criação diz que o LinkedIn aceitou a requisição. O estado diz se o post está no ar, e esses são dois fatos diferentes.

PUBLISH_FAILED tem uma regra de recuperação específica: "An edit is required in order to re-attempt publishing." Enviar a mesma requisição de criação de novo gera um segundo post, não uma nova tentativa do primeiro.

Dá para criar um rascunho no LinkedIn pela API?

Não. A Posts API não documenta nenhuma forma de criar um post em DRAFT, e a regra de criação não deixa espaço para isso. DRAFT aparece nas respostas para conteúdo que existe só para o seu autor, mas o LinkedIn não diz como esse conteúdo passa a existir nem como um desenvolvedor o criaria.

O LinkedIn também não documenta a resposta exata que você recebe ao enviar "lifecycleState": "DRAFT" na criação. O que mais se aproxima na tabela de erros é esta linha:

Então um agendador que quer segurar um post até um horário definido precisa segurá-lo do próprio lado e enviar a chamada de criação naquele momento. A API do LinkedIn não oferece um estado de espera em que se apoiar. É por isso que posts agendados no LinkedIn param de funcionar quando a ferramenta que os segura perde o token: nada fica do lado do LinkedIn esperando para ir ao ar.

Onde a documentação do LinkedIn se contradiz?

Três pontos nas mesmas duas páginas não batem com o enum.

O primeiro é a nota sobre viewContext na página da Posts API. Ela diz que a visualização AUTHOR "can be used to retrieve the latest version of a post, which has not yet been published; it can be in a number of possible states such as: PUBLISHED, DRAFT or PROCESSING." PROCESSING não é um valor da Posts API. Ele pertence à antiga API ugcPosts, e o enum da Posts API tem PUBLISH_REQUESTED no lugar dele.

O segundo está na tabela lifecycleStateInfo da página do schema. O campo reviewStatus é "Applicable for lifecycle state values of PUBLISH_REQUESTED and PUBLISHED_FAILED only." Não existe PUBLISHED_FAILED. O enum escreve PUBLISH_FAILED. Se você está gerando tipos a partir da documentação, use a grafia do enum.

O terceiro é a seção de atualização. O LinkedIn lista lifecycleState entre os únicos campos que você pode alterar com um PARTIAL_UPDATE, ao lado de commentary, contentCallToActionLabel, contentLandingPage e adContext. A página não dá nenhum exemplo de como alterá-lo e não diz quais transições são permitidas. A atualização de exemplo só mexe em commentary e contentCallToActionLabel.

Como os estados da Posts API correspondem aos antigos estados de ugcPosts?

A Posts API substituiu ugcPosts, e a migração do LinkedIn reduziu o enum de sete valores para quatro. O schema de ugcPosts no Microsoft Learn ainda lista os sete.

As descrições batem quase palavra por palavra. ugcPosts define PROCESSING como conteúdo "submitted for publish but is not yet ready for rendering," que é a definição de PUBLISH_REQUESTED da Posts API com uma palavra trocada.

Dois dos valores removidos foram para outro lugar. A exclusão agora é uma requisição DELETE com X-RestLi-Method: DELETE, e o LinkedIn diz "Post deletions are idempotent," devolvendo 204 mesmo para um post que já tinha sumido. Edições aparecem como um booleano, lifecycleStateInfo.isEditedByAuthor, que o LinkedIn diz ser "Applicable for UserGeneratedContentLifecycleState value of PUBLISHED only."

O que é lifecycleStateInfo?

É o objeto que acompanha e explica um estado, e o LinkedIn o devolve na leitura. Ele tem três campos:

• contentStatus: "Status for post content," com os valores PENDING, PROCESSING e FAILED. "If processing completes UGC transitions to PUBLISHED and the contentStatus is null."
• reviewStatus: "Review status of the post," com os mesmos três valores, nulo quando o post chega a PUBLISHED.
• isEditedByAuthor: o padrão é false.

É aqui que PROCESSING existe de forma legítima na Posts API. Ele é um valor de contentStatus e reviewStatus, não de lifecycleState. Código que faz switch em lifecycleState nunca deve esperar esse valor.

Quais headers uma chamada de criação precisa?

Quatro, e o LinkedIn declara dois deles no topo da página da Posts API: "All APIs require the request header Linkedin-Version: {Version in YYYYMM format}" e "All APIs require the request header X-Restli-Protocol-Version: 2.0.0".

curl -X POST 'https://api.linkedin.com/rest/posts' \
  -H 'Authorization: Bearer {INSERT_TOKEN}' \
  -H 'X-Restli-Protocol-Version: 2.0.0' \
  -H 'Linkedin-Version: 202608' \
  -H 'Content-Type: application/json' \
  --data '{ ...body with "lifecycleState": "PUBLISHED"... }'

O header de versão é o que quebra builds, porque precisa ter seis dígitos e a versão ainda precisa estar ativa. As regras para esse valor estão na nota sobre por que o header LinkedIn-Version precisa estar no formato YYYYMM. A página da Posts API traz atualmente um aviso de que a Marketing Version 202510 "will be sunset on October 15, 2026."

O token também precisa de uma permissão de publicação. w_member_social publica pelo membro autenticado. w_organization_social publica por uma página de empresa e é "Restricted to organizations where the authenticated member has one of the following company page roles: ADMINISTRATOR, DIRECT_SPONSORED_CONTENT_POSTER, CONTENT_ADMIN."

Como ler o estado atual de um post?

Envie um GET para https://api.linkedin.com/rest/posts/{encoded ugcPostUrn|shareUrn} e adicione viewContext=AUTHOR se quiser ver estados não publicados. O LinkedIn explica que o padrão, READER, "specifies the version of the post that has been published and is viewable to a general audience." Um post ainda em PUBLISH_REQUESTED é exatamente o tipo de coisa que a visualização READER não vai mostrar.

Posts com mídia passam antes por uma etapa de upload separada. O LinkedIn diz que um post com imagem "requires uploading an image asset to obtain an Image URN (urn:li:image:{id}) for use in the post," e a chamada de criação então referencia esse URN. A nota sobre o image URN do initializeUpload do LinkedIn cobre essa parte do fluxo.

Perguntas frequentes

O lifecycleState é obrigatório na Posts API do LinkedIn?

Sim. O schema o marca como required, e a descrição do erro MISSING_FIELD o cita como um dos campos que precisam estar presentes, ao lado de author, visibility e distribution.

Posso agendar um post no LinkedIn criando-o como DRAFT?

Não. PUBLISHED é o único valor que o LinkedIn aceita na criação, então um post agendado precisa esperar no seu próprio sistema até o momento em que você envia a chamada de criação.

O que significa PUBLISH_REQUESTED?

O LinkedIn aceitou o post, mas ainda não terminou de processá-lo. O LinkedIn diz que o conteúdo "will be published asynchronously once the processing has successfully completed."

Como tentar de novo um post travado em PUBLISH_FAILED?

Edite o post. A definição do LinkedIn diz "An edit is required in order to re-attempt publishing." Criar o post de novo gera um post novo.

Por que a documentação do LinkedIn menciona PROCESSING e PUBLISHED_FAILED?

Os dois são deslizes da documentação. PROCESSING é um valor de ugcPosts e um valor de contentStatus, e PUBLISHED_FAILED é um erro de grafia de PUBLISH_FAILED. Nenhum dos dois aparece no enum lifecycleState da Posts API.

Um post excluído volta com o estado DELETED?

Não. A Posts API não tem o valor DELETED. Uma requisição DELETE devolve 204, e o LinkedIn diz que exclusões repetidas do mesmo post também devolvem 204.

Que erro o LinkedIn devolve se eu enviar DRAFT como lifecycleState?

O LinkedIn não documenta a resposta exata para esse caso. O erro documentado mais próximo é 400 INVALID_VALUE_FOR_FIELD, com a mensagem "{field} cannot be set to {value}." O LinkedIn recomenda verificar se os valores de enum como lifecycleState são válidos, e na criação o único válido é PUBLISHED.

Como ver um post do LinkedIn que ainda não foi publicado?

Envie um GET para https://api.linkedin.com/rest/posts/{encoded ugcPostUrn|shareUrn} com viewContext=AUTHOR. A visualização padrão, READER, mostra só a versão publicada e visível ao público geral. Um post em PUBLISH_REQUESTED não aparece ali.

Quais headers uma chamada de criação da Posts API do LinkedIn exige?

São obrigatórios Linkedin-Version no formato YYYYMM e X-Restli-Protocol-Version: 2.0.0. A requisição de exemplo envia também Authorization com um token Bearer e Content-Type: application/json. A versão precisa estar ativa, porque o LinkedIn avisa que a Marketing Version 202510 "will be sunset on October 15, 2026."

Qual permissão preciso para postar em uma página de empresa do LinkedIn?

Você precisa de w_organization_social. O LinkedIn a descreve como "Restricted to organizations where the authenticated member has one of the following company page roles: ADMINISTRATOR, DIRECT_SPONSORED_CONTENT_POSTER, CONTENT_ADMIN." Para postar em nome do membro autenticado, use w_member_social.