> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Custom Push Source

> Registre uma origem e envie lotes de eventos em JSON ou CSV para a Living Security com uma chave de acesso de API com escopo definido.

Use uma Custom Push Source quando um sistema enviar registros para a Living Security, em vez de ser consultado periodicamente por um conector do Catálogo. O remetente pode enviar arrays JSON ou arquivos CSV para um endpoint HTTPS regional.

## Antes de começar

Você precisa de:

* permissão para gerenciar integrações e chaves de acesso na Living Security
* um remetente no lado do servidor capaz de fazer requisições HTTPS `POST`
* a região da Living Security da sua organização
* um nome de origem estável e pelo menos um nome de stream

Os nomes de origem e de stream são chaves de roteamento permanentes. Os nomes de origem devem ter de 1 a 64 caracteres, entre letras minúsculas, dígitos ou hifens. Os nomes de stream também permitem sublinhados. Ambos devem começar com uma letra ou um dígito.

<Warning>
  Trate a chave de acesso de API como um segredo. Não a coloque em código de navegador, não a inclua
  no controle de versão nem a envie em um chamado de suporte.
</Warning>

## 1. Registre a origem e os streams

<Steps>
  <Step title="Abra o Custom Push Source">
    Acesse **Configurações → Integrações → Catálogo**, localize **Custom Push Source** e selecione **Adicionar**.
  </Step>

  <Step title="Nomeie a origem">
    Informe a chave de roteamento da origem e uma descrição opcional. Por exemplo, use `custom-phishing-sim` em vez de um nome de exibição com espaços.
  </Step>

  <Step title="Adicione os streams">
    Adicione cada stream que o remetente utilizará. O par formado pela origem e pelo stream deve existir antes do primeiro envio; um par desconhecido retorna `404 Not Found`.
  </Step>

  <Step title="Salve a origem">
    Após a criação, abra a origem em **Configurações → Integrações → conectado**. A visualização **Push via API** mostra o padrão do endpoint e as execuções recentes.
  </Step>
</Steps>

## 2. Crie uma chave de push-ingest

Acesse **Configurações → Access Keys**, selecione **Create Access Key** e escolha o escopo **Push Ingest**. Copie o valor gerado imediatamente; ele é exibido apenas uma vez.

A chave está vinculada a uma única organização da Living Security. A requisição de envio não precisa de um cabeçalho de organização. Consulte [Chaves de acesso de API](/pt-BR/features/settings/api-keys) para informações sobre rotação e revogação.

## 3. Escolha o endpoint regional

Use o nome de host correspondente à organização da Living Security:

| Região | URL base |
| - | - |
| Estados Unidos | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| União Europeia | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Acrescente `/push-ingest/{integrationKey}/{streamName}`. O caminho diferencia maiúsculas de minúsculas e deve corresponder exatamente à origem e ao stream registrados.

<ParamField path="integrationKey" type="string" required>
  O nome da origem registrada. Use de 1 a 64 letras minúsculas, dígitos ou hifens, começando com uma letra ou um dígito.
</ParamField>

<ParamField path="streamName" type="string" required>
  O nome do stream registrado. As mesmas regras se aplicam, e sublinhados também são permitidos.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Envie a chave de acesso de push-ingest como `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Use `application/json` para JSON ou `text/csv` para CSV. O servidor também pode detectar um array JSON quando este cabeçalho é omitido.
</ParamField>

<ParamField header="x-organization-id" type="string">
  UUID da organização (opcional). A chave de acesso já determina a organização. Se você enviar este cabeçalho, ele deverá corresponder à organização da chave; ele não permite selecionar outra organização.
</ParamField>

### Corpo da requisição

Envie um array JSON de nível superior, não vazio, com objetos, ou os bytes de um arquivo CSV com linha de cabeçalho. Não há campo de encapsulamento JSON nomeado. Cada lote pode conter até 10.000 registros e 10 MB.

## 4. Envie um lote JSON

Envie um array JSON não vazio cujos elementos sejam objetos. `Content-Type: application/json` é recomendado e exigido por muitos produtos de envio, embora a Living Security consiga detectar um corpo em formato de array sem ele.

<RequestExample>
  ```bash JSON batch theme={null}
  curl --request POST \
    'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
    --header 'Authorization: Bearer <access-key>' \
    --header 'Content-Type: application/json' \
    --data '[
      {
        "email": "person@example.com",
        "event_at": "2026-09-21T14:30:00Z",
        "action": "reported"
      }
    ]'
  ```

  ```bash CSV file theme={null}
  curl --request POST \
    'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
    --header 'Authorization: Bearer <access-key>' \
    --header 'Content-Type: text/csv' \
    --data-binary '@events.csv'
  ```
</RequestExample>

Uma requisição bem-sucedida retorna `202 Accepted`. A guia de erro mostra um `400 Bad Request` quando o corpo JSON está malformado:

<ResponseExample>
  ```json 202 Accepted theme={null}
  {
    "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
    "recordsAccepted": 1,
    "integrationKey": "custom-phishing-sim",
    "streamName": "events"
  }
  ```

  ```json 400 Invalid JSON theme={null}
  {
    "statusCode": 400,
    "timestamp": "2026-09-22T14:30:00.000Z",
    "path": "/api/v1/push-ingest/custom-phishing-sim/events",
    "message": "Request body is not valid JSON. Send a JSON array of objects, or set Content-Type: text/csv to push a CSV.",
    "error": "Bad Request"
  }
  ```
</ResponseExample>

A aceitação significa que o lote foi armazenado para processamento assíncrono. Isso não significa que todos os registros já tenham sido interpretados como atividade.
No exemplo de `400`, corrija o JSON ou envie um CSV com `Content-Type: text/csv` e tente novamente.

<ResponseField name="runId" type="string" required>
  O ID da execução deste lote aceito. Guarde-o para consultar o status do processamento.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  O número de registros aceitos e armazenados.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  O nome da origem usado neste envio.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  O nome do stream usado neste envio.
</ResponseField>

## Envie CSV em vez de JSON

Defina `Content-Type: text/csv` e envie os bytes do arquivo, conforme mostrado no exemplo de requisição **CSV file** acima. A primeira linha fornece os nomes dos campos.

Textos booleanos tornam-se booleanos e textos numéricos comuns tornam-se números. Valores com zeros à esquerda, inteiros grandes demais para serem representados com segurança, datas e demais textos permanecem como strings. Células vazias omitem o respectivo campo. Linhas malformadas, aspas sem par e arquivos UTF-16 são rejeitados.

## Limites de requisição e novas tentativas

| Contrato | Valor atual |
| - | - |
| Máximo de registros | 10.000 por requisição |
| Tamanho máximo do corpo da requisição | 10 MB |
| Taxa de requisições por organização | 600 requisições por 60 segundos |

Divida exportações maiores em lotes que atendam a ambos os limites. Aguarde cada resposta e mantenha o `runId` retornado nos logs do remetente.

| Resposta | Significado | Ação do remetente |
| - | - | - |
| `202` | Lote aceito | Registre o `runId`; não reenvie imediatamente |
| `400` | Nome, JSON, CSV, quantidade de registros ou corpo inválido | Corrija a requisição; não tente novamente sem alterações |
| `401` | Chave ausente, expirada, revogada ou inválida | Substitua a chave e use o cabeçalho Bearer |
| `403` | A chave não possui o escopo necessário | Crie uma chave com o escopo **Push Ingest** |
| `404` | A origem ou o stream não está registrado | Registre o par exato ou corrija a URL |
| `413` | O corpo da requisição excede 10 MB | Divida o lote em requisições menores |
| `429` | Limitação temporária em nível de IP | Respeite `Retry-After` quando presente e reduza a frequência |
| `503` | Bucket de taxa da organização ou limitador indisponível | Aguarde `Retry-After` e reenvie o mesmo lote |

O limite normal da organização autenticada retorna `503`, e não `429`, de modo que os remetentes de webhook o tratem como passível de nova tentativa. Um `503` é retornado antes de o lote ser armazenado; reenviar esse mesmo lote após o intervalo indicado não duplica uma execução aceita.

## Verifique o fluxo de dados

Abra o Custom Push Source e revise o **Push History**. Confirme o stream, a contagem de registros, a atribuição da chave e o status do processamento. Dados com um interpretador mantido podem então se tornar pessoas e atividade normalizada. Dados sem interpretador permanecem armazenados, mas não geram atividade.

<Info>
  Use os nomes exatos dos campos e o formato de payload do guia específico do
  provedor, quando houver. Um `202` bem-sucedido comprova a entrega, mas não que um
  esquema arbitrário seja mapeado para a atividade da Living Security.
</Info>

## Lista de verificação para solução de problemas

* Copie o endpoint da origem correta e substitua o marcador de posição do stream.
* Envie a chave de acesso como `Authorization: Bearer …`; `x-api-key` não é aceito.
* Confirme que o corpo é um array JSON de nível superior, e não um único objeto nem um envelope em torno dos registros.
* Confirme a grafia da origem e do stream, incluindo hifens, sublinhados e maiúsculas/minúsculas.
* Revise o **Push History** antes de reenviar um lote cuja resposta tenha sido perdida.
* Ao entrar em contato com o [Suporte da Living Security](mailto:support@livingsecurity.com), inclua a organização, a origem, o stream, o horário da requisição, o `runId` quando disponível e o status da resposta. Não inclua a chave de acesso nem o payload do evento.

## Relacionados

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/pt-BR/integrations/zscaler-zia-cloud-nss">
    Configure um feed de logs web do Zscaler compatível com a origem, o stream, os cabeçalhos e o formato JSON exatos.
  </Card>

  <Card title="Chaves de acesso de API" icon="key" href="/pt-BR/features/settings/api-keys">
    Crie, faça a rotação e revogue credenciais com escopo definido.
  </Card>

  <Card title="Fontes de dados de Sinais" icon="wave-pulse" href="/pt-BR/signals/data-sources">
    Saiba como a atividade interpretada das integrações oferece suporte aos Sinais.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.