Pular para o conteúdo principal

Scoutello API

A API do Scoutello é uma API servidor a servidor para sincronizar, nos dois sentidos, os contatos, as tarefas, os protocolos, as oportunidades, os projetos, os marcos e os eventos de uma organização. Ela também disponibiliza o histórico de e-mails enviados somente para leitura, a consulta de membros atribuíveis e a descoberta de etiquetas com reconhecimento de entidade. As rotas incrementais GET/list e as operações de upsert em lote idempotentes são os mecanismos de sincronização desta versão. A API não disponibiliza operações de exclusão nem webhooks.

A URL base da API é:

https://admin.scoutello.com/api/v1

Ela também é exibida em Configurações da organização → Desenvolvedor/API. O documento OpenAPI está disponível em:

https://admin.scoutello.com/api/v1/openapi.json

Criar e proteger uma chave​

Para organizações modulares, o módulo de CRM precisa estar ativo além dos escopos exigidos pela chave. Uma chave válida não pode ativar um módulo ausente. As solicitações retornam HTTP 403 com o código de erro module_not_active quando o acesso ao CRM não está disponível. Uma pessoa com permissões de administração da organização pode consultar ou ativar o CRM em Assinatura; tentar novamente depois que o acesso estiver ativo.

Uma pessoa com permissões de administração da organização pode criar uma integração e uma chave de API em Configurações da organização → Desenvolvedor/API. A chave completa é exibida uma única vez. Copiar a chave para um gerenciador de segredos antes de fechar a caixa de diálogo; o Scoutello não poderá exibir a chave completa novamente.

  • Usar uma integração e uma chave separadas para cada sistema externo e ambiente.
  • Conceder somente os escopos necessários para o sistema.
  • Nunca inserir uma chave em código do navegador, URL, controle de versão, registros, mensagens de suporte ou armazenamento no lado do cliente.
  • Alternar as chaves periodicamente. Quando uma integração ativa tem a chave alternada, a chave substituta funciona imediatamente e a chave anterior continua válida por no máximo 15 minutos, permitindo a troca do sistema externo sem indisponibilidade. Um prazo de expiração anterior continua valendo; por isso, a chave anterior pode deixar de funcionar antes.
  • Se uma chave puder ter sido exposta, pausar a integração antes de alterná-la. A pausa rejeita temporariamente todas as chaves da integração. Uma alternância durante a pausa não tem período de sobreposição: a chave anterior permanece desativada e a chave substituta continua desativada até a retomada da integração.
  • Revogar permanentemente toda a integração ao desconectar um sistema externo. A revogação desativa todas as chaves da integração e não pode ser desfeita.

Enviar a chave em todas as solicitações autenticadas:

Authorization: Bearer YOUR_API_KEY

A autenticação Bearer é preferencial. Clientes que não podem definir Authorization podem usar x-api-key. Não enviar os dois cabeçalhos; solicitações com valores diferentes nos dois cabeçalhos são rejeitadas.

A API foi desenvolvida para clientes de backend e não habilita acesso de navegador entre origens.

Usar GET /whoami depois de configurar uma chave para verificar a integração, a organização, os escopos e os limites da chave sem obter dados pessoais de pessoas usuárias.

Escopos​

EscopoPermite
contacts.readListar e recuperar contactos. Os contactos da conta da organização e os contactos de membros com acesso são excluídos.
contacts.writeValidar e aplicar upserts de contactos.
tasks.readListar e recuperar tarefas não privadas.
tasks.writeValidar e aplicar upserts de tarefas.
protocols.readListar e recuperar protocolos não privados.
protocols.writeValidar e aplicar upserts de protocolos.
opportunities.readListar e recuperar oportunidades.
opportunities.writeValidar e aplicar upserts de oportunidades.
projects.readListar e recuperar projetos.
projects.writeValidar e aplicar upserts de projetos e participantes.
milestones.readListar e recuperar marcos de projetos.
milestones.writeValidar e aplicar upserts de marcos.
members.readListar membros aceites apenas com o ID de cliente do membro, o ID de utilizador e o nome de apresentação.
events.readListar e recuperar eventos e agendas principais.
events.writeValidar e aplicar upserts de eventos.
mails.readLer o histórico de correio enviado e falhado pertencente à organização.
mail-drafts.readLer os rascunhos autónomos de aprovação de e-mail desta integração e o estado de entrega.
mail-drafts.writePreparar ou rever rascunhos de e-mail para aprovação por uma pessoa; nunca aprovar nem enviar.
tags.readDescobrir etiquetas selecionáveis para os tipos de entidade compatíveis.

As tarefas e os protocolos privados nunca são devolvidos por esta API. Um escopo em falta devolve um erro de autorização; não é tratado como um resultado vazio.

Um contacto de CRM que não seja membro pode ser lido e referenciado mesmo quando está associado a um início de sessão do Scoutello. A resposta contém apenas os campos de CRM da organização, nunca dados de identidade ou de acesso do utilizador. Os contactos com uma função, permissões, convite, aceitação ou estado de conta da organização permanecem ocultos. A edição de um contacto associado a um início de sessão continua proibida (protected_contact), incluindo campos de CRM que, de outra forma, não sofreriam alterações. Para referenciar um contacto legível existente a partir de uma tarefa/protocolo, contacts.write pode estabelecer a sua ligação externa apenas com externalId, scoutelloId e externalUpdatedAt opcional. As atualizações posteriores apenas dos metadados da ligação utilizam externalId e externalUpdatedAt opcional; omitir scoutelloId de bootstrap depois de estabelecer a ligação. Isto nunca altera o contacto nem o respetivo utilizador. A atribuição de membros aceites utiliza a projeção separada members.read.

As novas chaves usam o prefixo sctl_api_ e começam apenas com contacts.write. Todos os outros escopos exigem adesão explícita e devem ser concedidos por uma pessoa com permissões de administração da organização ao criar ou fazer a rotação de uma chave. As credenciais existentes mantêm os escopos atuais e continuam válidas.

Contactos associados a projetos e rascunhos de e-mail​

As operações de criação ou atualização de contactos aceitam pares opcionais projectScoutelloId / projectExternalId e companyScoutelloId / companyExternalId (escolher uma opção por par). O contacto, a relação com a empresa e a participação no projeto são guardados atomicamente por item. Adicionar uma participação no projeto requer projects.write; referências omitidas preservam as restantes relações e participações. As leituras dos detalhes do contacto incluem projectParticipations quando projects.read é concedido. Os agentes de projetos de vendas devem incluir explicitamente a referência ao projeto, mesmo ao reutilizar um contacto.

Os rascunhos autónomos usam o sistema existente de aprovação por pessoas, sem uma execução de fluxo de trabalho:

MétodoCaminhoObjetivo
GET/mail-draftsRascunhos pertencentes à integração, com paginação; filtros opcionais projectScoutelloId e status.
GET/mail-drafts/{scoutelloId}Versão atual, link de revisão, hash do conteúdo, estado de aprovação/envio e ID final do e-mail.
GET/mail-drafts/external/{externalId}Procurar um ID externo estável da integração.
POST/mail-drafts/batch-upsertValidar ou aplicar a preparação do rascunho.

A preparação do rascunho requer mail-drafts.write, contacts.read e projects.write. O contacto referenciado torna-se participante do projeto. A pessoa responsável pela aprovação deve ser um membro aceite da organização com permissão para editar e-mails. A seleção do remetente usa as definições existentes de remetente da organização ou pessoais permitidas para esse membro; não são aceites endereços arbitrários no campo From.

{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}

Verificar todos os resultados de validação antes de repetir a operação com mode: "apply". Ler o ID resultante para obter reviewUrl, draftVersion, contentHash, status, dispatchStatus e mailScoutelloId. Usar expectedVersion: 0 apenas para a criação e a versão atual devolvida para revisões. O contexto e a pessoa responsável pela aprovação são imutáveis; os rascunhos revistos ou enviados rejeitam conteúdo alterado. As tentativas idênticas devolvem o rascunho original.

Os rascunhos aparecem nas abas de e-mail do projeto/contacto e nas notificações de aprovação do painel. A preparação pela API não envia e-mails, incluindo e-mails de notificação; o comportamento existente dos e-mails de notificação do fluxo de trabalho permanece inalterado. A pessoa responsável pode editar os destinatários, o assunto, o corpo e os anexos compatíveis, guardar a versão e, em seguida, Aprovar e enviar. As integrações não podem aprovar nem enviar. Uma entrega falhada ou ambígua nunca é repetida às cegas. Ao converter rascunhos baseados em protocolos, preserve os protocolos e faça referência cruzada às respetivas substituições.

Acesso MCP​

A mesma chave de API e os mesmos escopos do Scoutello podem ser usados com o endpoint MCP HTTP com streaming:

https://admin.scoutello.com/api/v1/mcp

Configure o cliente MCP para enviar Authorization: Bearer YOUR_API_KEY. O URL /api/mcp legado permanece como alias de compatibilidade de caminho, mas os novos clientes devem usar o endpoint com versão. As credenciais sctl_mcp_ anteriores não são aceites; substitua-as por uma chave de integração de API do Scoutello.

As ferramentas MCP correspondem diretamente ao contrato REST e usam os mesmos esquemas de runtime, verificações de tenant, ciclo de vida da integração, limite de taxa e métodos de serviço. Por exemplo, contacts_list, contacts_get, contacts_get_by_external_id e contacts_batch_upsert refletem as quatro rotas de contactos. O mesmo padrão aplica-se a tarefas, protocolos, oportunidades, projetos, marcos e eventos; o correio expõe mails_list e mails_get, os membros expõem members_list e as etiquetas expõem tags_list.

O servidor só anuncia as ferramentas permitidas pelos escopos da chave atual. Uma chave com contacts.read pode descobrir as ferramentas de leitura de contactos, mas não contacts_batch_upsert; uma chave com contacts.write obtém a ferramenta de atualização em lote, mas não as ferramentas de leitura. whoami está sempre disponível. As ferramentas de escrita têm os mesmos efeitos imediatos que os equivalentes REST; por isso, use mode: "validate" quando for necessário inspecionar um lote sem o aplicar.

O MCP também é servidor a servidor e não permite o acesso de navegadores entre origens. O seu transporte JSON-RPC requer um URL dedicado, pelo que não pode partilhar um URL de recurso REST individual, embora a autenticação e o comportamento dos dados sejam partilhados.

Para obter instruções completas de configuração do cliente, verificação, mapeamento de ferramentas e resolução de problemas, consulte o guia de integração do MCP.

Ler registos​

Os contactos, as tarefas, os protocolos, as oportunidades, os projetos, os marcos e os eventos usam as mesmas rotas de leitura:

GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}

Substitua contacts por tasks, protocols, opportunities, projects, milestones ou events para os outros recursos de sincronização. externalId aparece num DTO de leitura quando o registo foi associado por esta integração.

Uma resposta de lista tem este envelope:

{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}

limit deve estar entre 1 e 100. Os resultados são ordenados pelo momento efetivo em que a representação na API pública foi alterada e, em seguida, pelo ID do Scoutello. Esse momento efetivo pode ser posterior ao updatedAt da entidade retornada quando os metadados do vínculo de integração foram alterados. Os cursores são opacos: armazená-los e enviá-los sem alterações e não derivar significado de seu conteúdo.

A primeira resposta fixa snapshotAt para essa travessia. Seguir nextCursor até que hasMore seja falso antes de iniciar outra leitura incremental. Isso impede que alterações nos registros durante a paginação tornem a travessia atual instável.

Para a sincronização incremental, consumir todas as páginas do cursor e persistir o snapshotAt dessa travessia como o timestamp de marca d’água superior. Passá-lo como o valor updatedSince ISO 8601 na próxima travessia. O limite inferior é inclusivo; portanto, repetir um snapshot concluído pode retornar registros no limite, mas não pode ignorá-los.

Uma resposta de registro único tem este envelope:

{
"data": {},
"requestId": "request-id"
}

As respostas de contato único também incluem um array relations. Cada relação mantém o ID da relação no Scoutello, o horário de criação, o tipo, as observações e as referências de contato connectedFrom e connectedTo. As referências de contato contêm o ID do Scoutello e o ID externo desta integração, quando existir. Contatos excluídos pelo limite de privacidade de acesso da organização da API não são expostos por meio das relações. A resposta da lista de contatos permanece compacta e não inclui relações; usar qualquer uma das rotas de contato único quando for necessário obter detalhes dos relacionamentos.

Filtros de trabalho e escopo do cursor​

As listas de contatos aceitam search, type (person, company, supplier, other), status e tagIds. A busca remove espaços excedentes, não diferencia maiúsculas de minúsculas e é limitada a 200 caracteres / 10 tokens separados por espaços em branco. Cada token deve ocorrer em pelo menos um de firstName, lastName ou companyName, incluindo nomes de empresas legados armazenados em lastName. Caracteres como % e _ são correspondidos literalmente. As tags usam correspondência de qualquer um com 1 a 50 IDs. Todos os filtros fornecidos são combinados com AND. O REST codifica os IDs de tags como parâmetros repetidos; o MCP fornece um array:

GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two

Os cursores de contato são vinculados à organização, à integração e a todos os filtros. Manter os filtros em cada página; alterar um filtro rejeita o cursor. A ordem e as duplicatas das tags, assim como a ordem, as maiúsculas e minúsculas e os espaços em branco dos tokens de busca, não alteram o filtro efetivo.

As rotas de listas de trabalho aceitam os seguintes filtros adicionais; outras combinações de recursos/campos são rejeitadas:

RecursoFiltros
TarefasprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtocolosprojectScoutelloId, milestoneScoutelloId, status (draft ou final)
OportunidadesprojectScoutelloId, stage, ownerScoutelloUserId
Projetosstatus, assignedContactScoutelloId
MarcosprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore é exclusivo; dueAfter é inclusivo. A comparação é feita com a data de vencimento da tarefa ou a data de término do marco; registros sem essa data não correspondem. Usar datas e horas ISO com fuso horário. Todos os filtros são aplicados antes da paginação. Continuar um cursor exige exatamente os mesmos filtros, incluindo updatedSince, e a mesma organização/integração. O tamanho da página pode mudar. Cursores antigos sem escopo devem reiniciar a partir do timestamp de maior valor salvo após esta versão.

Projetos, marcos, atribuições e notas​

GET /members (MCP members_list) usa a paginação padrão e requer members.read. Retorna scoutelloId (ID de membro Customer), scoutelloUserId (ID de User) e displayName. Apenas membros aceitos da organização que tenham uma função aparecem; a consulta não expõe e-mails nem permissões.

As tarefas aceitam assignedScoutelloUserIds; as oportunidades usam ownerScoutelloUserId. Projetos e marcos usam assignedContacts: [{"scoutelloId":"member-customer-id"}]. As atribuições exigem membros aceitos da organização da credencial. A omissão das atribuições não altera as existentes; [] as remove. As importações de projetos, marcos, tarefas e protocolos são silenciosas: não enviam notificações de atribuição nem comunicações.

O evento assignedContacts aceita contatos de CRM legíveis e membros aceitos fornecidos pelo ID de membro Customer. Membros aceitos continuam indisponíveis como referências comuns de contatos do CRM ou destinos de links externos; usar o campo de atribuição de membro para indicar a responsabilidade da equipe.

Crie marcos com um name e projectScoutelloId ou projectExternalId. Eles são compatíveis com description (Markdown), status (open, in_progress, completed, closed), startDate/endDate anuláveis, order (com valor padrão 0) e assignedContacts. As datas de término não podem ser anteriores às datas de início. Cada marco tem um link externo estável, com escopo definido pela integração. O projeto não pode ser alterado por meio da API. As operações de criação e atualização localizam o nome e a descrição no idioma da organização.

As tarefas e os protocolos aceitam referências a projetos, marcos e oportunidades como <entity>ScoutelloId ou <entity>ExternalId, por exemplo, milestoneExternalId. Forneça apenas uma grafia por relação, inclusive ao remover uma relação com null. Todas as relações devem pertencer à organização da credencial. Uma referência somente ao marco infere o projeto; um projeto conflitante ou a remoção explícita de um projeto mantendo o respectivo marco é rejeitado. Uma oportunidade vinculada que tenha um projeto deve corresponder ao projeto do trabalho. Relações omitidas preservam os valores atuais; null explícito remove uma relação quando o contexto restante é válido. As leituras expõem ambas as grafias de ID e as atribuições de tarefas.

Planejamento de tarefas e fluxos de trabalho​

Task status é a chave imutável de um status no fluxo de trabalho efetivo da tarefa, não um enum fixo. Leia os fluxos de trabalho disponíveis da organização e do projeto com GET /task-workflows usando o escopo tasks.read. Cada status inclui sua chave, seu rótulo, seu ciclo de vida type (backlog, unstarted, started, completed ou cancelled), sua cor, sua ordem, o indicador de status padrão e o estado de arquivamento. As entradas de projeto indicam se o fluxo de trabalho da organização é herdado. A configuração do fluxo de trabalho continua sendo administrada no painel.

As tarefas aceitam priority anulável (low, medium, high ou urgent) e estimatedEffortMinutes, além de startDate e dueDate anuláveis. As leituras de tarefas incluem statusType desnormalizado, a referência ao item pai, referências compactas a subtarefas e referências blockedBy / blocks.

Crie ou atualize uma subtarefa de um nível usando parentTaskScoutelloId ou parentTaskExternalId; null promove-a a uma tarefa de nível superior. As dependências usam arrays de referências { "scoutelloId": "..." } ou { "externalId": "..." } em blockedBy e blocks. Campos de relacionamento omitidos preservam os relacionamentos existentes, enquanto um array de dependências vazio limpa essa direção. A API rejeita subtarefas aninhadas, dependências entre elementos pai e filho, dependências entre organizações, duplicatas, autorreferências e ciclos diretos ou transitivos.

Os filtros da lista de tarefas aceitam um status exato, um ciclo de vida statusType, priority, parentState (top_level, subtask ou parent) e blockedState (blocked, blocking ou unblocked).

Os protocolos também aceitam status: "draft" | "final" (novos registros assumem final por padrão). Um novo protocolo requer type, date e um contacto ou um contexto válido de projeto/marco. contactExternalId: null remove o contacto apenas quando o contexto de projeto/marco permanece. Assim, é possível criar e ler notas internas de projetos sem inventar um cliente. Rascunho/final descreve o estado da nota e nunca envia uma comunicação. Tarefas e protocolos privados continuam inacessíveis.

Participantes do projeto​

O projeto participants contém operações de inserção ou atualização aditivas identificadas por uma referência contact, por exemplo:

{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}

Os participantes descrevem potenciais clientes/clientes associados a um projeto; os membros responsáveis são definidos por atribuições. Participantes omitidos, um array vazio e campos de participantes omitidos preservam os dados existentes. null remove role, notes ou groupScoutelloId. Contactos resolvidos duplicados no mesmo payload são rejeitados. Os grupos já devem pertencer ao projeto selecionado; as leituras incluem participantGroups (ID/nome), além de IDs dos participantes, contactos, função, notas e ID do grupo. A remoção de participantes ou a criação de grupos está atualmente disponível no painel.

Inserir ou atualizar registros em lote​

Escreva até 100 registros usando a rota de lote do recurso:

POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}

Os lotes de tarefas resolvem os registros de tarefas antes de aplicar os relacionamentos de hierarquia e dependência. Esse processamento em duas fases permite que uma tarefa pai, bloqueadora ou bloqueada referencie outra tarefa criada no mesmo lote pelo seu ID externo, independentemente da ordem dos registros.

Use o documento OpenAPI para consultar os campos e as restrições de validação de cada recurso. Cada registro deve ter um externalId estável entre 1 e 200 caracteres. Trate-o como um identificador técnico opaco: não use um endereço de e-mail, nome, segredo de API ou outros dados pessoais. externalUpdatedAt é opcional, mas altamente recomendado quando o sistema de origem fornece um carimbo de data e hora de modificação confiável.

O corpo da solicitação está limitado a 1 MiB. mode assume apply por padrão:

  • apply valida e grava os registros aceitos.
  • validate executa a mesma validação e correspondência sem gravar, retornando os resultados would_*.

Para importações de contatos, matchByEmail pode ser definido como true na solicitação. O padrão é false; o ID externo é o limite de identidade mais seguro.

Os campos omitidos preservam o valor atual. Um null explícito limpa um campo anulável, e uma matriz vazia de atribuições/tags fornecida limpa essa relação. Os participants de projetos são upserts aditivos: uma matriz vazia não altera a lista de pessoas. As gravações de tags de contatos, tarefas, oportunidades e eventos usam IDs de tags do Scoutello. Os IDs externos de relacionamentos são resolvidos somente por meio de links pertencentes à integração atual, enquanto os IDs de usuário do Scoutello usados para propriedade ou responsabilidade devem identificar membros aceitos da organização atual.

As criações de oportunidades exigem uma conta ou contato, e oportunidades perdidas exigem um motivo da perda. Os valores monetários usam centavos inteiros. Os nomes e as descrições de projetos e eventos são lidos e gravados no idioma configurado da organização. As gravações de eventos aceitam datas explícitas e recorrência diária, semanal ou mensal com exclusões; os níveis de visibilidade publicados continuam sujeitos aos controles de preparação jurídica do Scoutello. A API não expõe controles de venda de ingressos para eventos, participantes, mídia, modelos, newsletters, colaborações ou outros recursos avançados de gestão de eventos.

Descobrir tags​

Use o endpoint de tags antes de fornecer tagIds:

GET /tags?entity=events&type=category

entity é obrigatório e aceita contacts, tasks, opportunities ou events. Ele é mapeado para a relevância da tag armazenada correspondente. type é opcional e aceita category ou attribute. As categorias selecionáveis podem pertencer à organização ou ser globais; os atributos selecionáveis vêm do conjunto global de atributos selecionados pelo Scoutello. Os resultados incluem scoutelloId, o nome localizado no idioma da organização, type e relevancy. IDs de tags de outra organização, com relevância incorreta ou não selecionáveis rejeitam o item do lote afetado.

Ler o histórico de e-mails enviados​

O histórico de e-mails é somente leitura:

GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}

Apenas e-mails pertencentes à organização com status sent ou failed são retornados. As respostas contêm cabeçalhos e corpo armazenados comuns, BCC, status e carimbos de data e hora, referências a projetos/eventos/newsletters, IDs e tipos de anexos, além de estatísticas agregadas de entrega, abertura, cliques, devoluções, reclamações e rejeições dos destinatários. Rascunhos, e-mails enfileirados ou agendados, registros por destinatário, instantâneos renderizados, erros brutos do provedor e URLs para download de anexos nunca são expostos. Uma atualização posterior da entrega a um destinatário adianta o carimbo de data e hora efetivo de sincronização do e-mail, fazendo com que ele volte a aparecer nas leituras incrementais. Não existem rotas para gravar e-mails.

Um resultado de aplicação pode ser created, updated, linked, unchanged, stale_ignored ou rejected. A validação usa would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale ou rejected. Uma solicitação de lote válida retorna HTTP 200 mesmo quando registros individuais são rejeitados; portanto, sempre inspecione cada item e o resumo da resposta. Mantenha a resposta requestId ao solicitar que o suporte do Scoutello investigue uma falha.

Carimbos de data e hora e conflitos​

Quando externalUpdatedAt está presente, o Scoutello o utiliza para rejeitar alterações obsoletas sem falhar o restante do lote. Um resultado stale_ignored é definitivo para esse payload antigo; busque o registro atual antes de decidir se deve enviar uma versão mais recente.

Trate os carimbos de data e hora como valores UTC no formato ISO 8601. Preserve a precisão original e não substitua o horário em que um trabalho de sincronização ocorreu pelo horário de modificação do registro de origem.

Idempotência​

O limite de idempotência é a integração mais externalId. O Scoutello compara um hash canônico do payload e o valor opcional externalUpdatedAt; portanto, repetir o mesmo registro não cria duplicatas e pode retornar unchanged.

Com externalUpdatedAt, o mesmo carimbo de data e hora e o mesmo payload resultam em unchanged, um carimbo mais antigo resulta em stale_ignored, e o mesmo carimbo com um payload diferente gera um conflito de versão. Para um link que nunca aceitou um carimbo de data e hora, o mesmo payload sem carimbo continua unchanged, enquanto um payload alterado é aplicado na ordem de chegada. Depois que um link aceita um carimbo de data e hora, um payload alterado que omite externalUpdatedAt é rejeitado como conflito de versão, para que dados sem versão não possam substituir um estado versionado. Por isso, os carimbos de modificação da origem são altamente recomendados.

Trilha de auditoria​

As ações de criação, atualização e sincronização apenas de links aceitas pela API aparecem nos changelogs do Scoutello com Public API como origem e ficam associadas à integração responsável. Os resumos operacionais das execuções mantêm os IDs das solicitações e as contagens agregadas dos resultados para fins de solução de problemas; eles não mantêm payloads de registros nem segredos de API.

Erros e novas tentativas​

Os erros no nível da solicitação usam este envelope:

{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}

Repetir solicitações HTTP 429 e respostas 5xx transitórias usando recuo exponencial e jitter. Respeitar Retry-After quando estiver presente. Falhas de rede podem ter ocorrido depois que o Scoutello aceitou uma solicitação; reenviar o mesmo lote é seguro porque cada registro é idempotente por ID externo e payload canônico. Não repetir automaticamente resultados de autenticação, autorização, validação, conflito de versão ou resultados individuais rejected sem alterar a solicitação.

Loop de sincronização bidirecional recomendado​

  1. Chamar /whoami durante a configuração e verificar a organização e os escopos esperados.
  2. Ler todas as páginas alteradas desde o último marcador de alta prioridade concluído e aplicar essas alterações ao sistema externo de forma idempotente.
  3. Enviar as alterações externas para /batch-upsert, usando IDs externos estáveis e carimbos de data e hora da modificação na origem.
  4. Persistir os pontos de verificação somente depois de todas as páginas e dos resultados dos itens terem sido processados.
  5. Resolver conflitos de acordo com as regras de propriedade do sistema de origem; não simular exclusões enviando registros vazios.

O Scoutello deliberadamente não oferece uma rota pública de exclusão nesta primeira versão. Gerenciar as políticas de exclusão ou arquivamento fora da API até que uma operação de ciclo de vida documentada seja introduzida.

Publicações sociais para revisão humana​

A API social prepara publicações para uma pessoa revisora identificada. Ela não pode aprová-las nem publicá-las. REST e MCP usam os mesmos escopos e o mesmo serviço.

EscopoEndpoints em /api/v1
social-channels.readGET /social-channels
social-posts.readGET /social-posts, GET /social-posts/{scoutelloId}
social-post-drafts.readGET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId}
social-post-drafts.writePOST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize

Novos escopos devem ser concedidos explicitamente. As credenciais existentes não obtêm acesso adicional. Usar members.read para descobrir os IDs de usuário das pessoas membros e selecionar uma pessoa revisora com permissão de publicação (newsletter.edit). Os rascunhos não exigem um contato de CRM nem um projeto.

{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}

Use publishMode: "now" e scheduledAt: null para publicar após a aprovação. Cada variante de canal contém o texto completo, as configurações e os IDs de mídia ordenados. A descoberta de canais retorna os formatos compatíveis, os limites e as configurações. Atualmente, os canais compatíveis são perfis/páginas do LinkedIn, Facebook, Instagram e Threads. O Instagram requer mídia. Uma variante aceita até dez imagens ou vídeos.

Os lotes aceitam até 100 IDs externos exclusivos dentro do limite atual de 1 MiB por solicitação. mode: "validate" verifica referências e versões sem salvar rascunhos, enviar recursos, criar notificações ou enfileirar tarefas. Os resultados da aplicação incluem IDs, links de revisão, versões e resultados por registro. Falhas parciais não revertem os registros relacionados processados com sucesso. Uma falha de notificação retorna um aviso com a URL de revisão salva.

Recuperar o draftVersion atual antes de revisar um rascunho pendente. Novas tentativas idênticas são idempotentes e preservam edições humanas posteriores. As pessoas revisoras não podem ser alteradas no próprio registro. Após a aprovação ou recusa, usar um novo ID externo para outra proposta. As leituras de rascunhos são limitadas à integração que faz a chamada; o histórico de publicações inclui todas as campanhas criadas pelo Scoutello e persistidas na organização, incluindo publicações do painel, do script e legadas do Scoutello. O histórico externo dos canais não é importado.

As listas usam os parâmetros padrão limit, cursor e updatedSince. As publicações e os rascunhos também aceitam channelId, status, after, before e search; manter todos os filtros nas páginas subsequentes do cursor. Os filtros de data se aplicam ao horário de publicação (ao horário de criação no caso de rascunhos pendentes imediatos). O filtro status de rascunhos filtra o status de aprovação; status de publicações corresponde ao status de entrega da campanha ou do canal. As leituras expõem o último estado de entrega conhecido, as falhas por canal, os links públicos e os horários de reconciliação. As leituras incrementais de rascunhos também refletem alterações na entrega da campanha.

Fazer upload de mídia​

  1. Chamar POST /social-media/uploads com clientUploadId, filename, contentType, size em bytes e com sha256 hexadecimal minúsculo dos bytes originais. Os tipos compatíveis são PNG, JPEG, WebP, MP4, WebM, QuickTime e M4V. O limite de upload é de 500 MiB.
  2. Enviar os bytes originais com HTTP PUT para o upload.url retornado, usando os cabeçalhos correspondentes. Os URLs de upload expiram após 15 minutos. Reutilizar clientUploadId para novas tentativas do mesmo arquivo; sessões expiradas ou arquivos diferentes exigem um novo ID.
  3. Chamar POST /social-media/uploads/{assetId}/finalize com um corpo JSON de {}. A finalização verifica tamanho, tipo, assinatura e soma de verificação, congela uma cópia privada e retorna o ID do ativo para mediaIds. Repetir a finalização é seguro.

A propriedade do upload está vinculada à organização e à integração. Rascunhos podem fazer referência a ativos finalizados da própria organização. Os URLs de pré-visualização são temporários; recuperar o rascunho novamente para atualizá-los. URLs de upload nunca são emitidos para objetos finalizados.

Revisão humana e entrega​

A pessoa revisora recebe uma notificação no painel e pode abrir a publicação em Postings ou pelo URL de revisão. A edição cria outra versão imutável. A aprovação usa a versão exibida e o hash do conteúdo, verifica novamente a associação, os canais e os ativos e cria atomicamente uma única campanha persistente. Se o horário proposto já tiver passado, a pessoa revisora deverá salvar um novo horário explícito ou selecionar a publicação após a aprovação.

As novas tentativas da fila reutilizam a campanha e os comprovantes da plataforma. Campanhas aprovadas não podem ser editadas no local. O cancelamento pelo painel preserva o histórico de aprovação e a mídia; o cancelamento não pode interromper um envio em andamento. Consultar o rascunho ou a campanha para distinguir a aprovação da entrega efetiva na plataforma.