# Identificadores, paginação e erros

Toda requisição usa `Authorization: Bearer pf_live_…`. Guarde a chave no servidor da integração e não a inclua em código entregue ao navegador.

![Fluxo da integração: chave identifica o membro, permissões e recursos são conferidos, operação acessa os dados visíveis e devolve resposta ou erro](/_astro/fluxo-api.Bx0uNFGi.svg)

## Identificadores

| Identificador     | Uso                                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `seq` de negócio  | Número do lead dentro do workspace; usado em `/deals/{seq}`.                                    |
| `seq` de funil    | Número do funil; usado em `/pipelines/{seq}` e no parâmetro `pipeline` da listagem de negócios. |
| `seq` de empresa  | Número da empresa; usado em `/companies/{seq}`.                                                 |
| `id`              | Identificador técnico de contato, etapa, campo, canal ou automação. Não substitua por `seq`.    |
| `conversationKey` | Chave retornada pela listagem de conversas; preserve seu valor e codifique ao montar a URL.     |
| `slug` de campo   | Chave do valor em `customFields` e `properties`. A definição também tem um `id`.                |

## Paginar

Nas operações com cursor, envie `limit` dentro do intervalo documentado. Use o cursor retornado pela página seguinte sem interpretar seu conteúdo. Termine quando não houver próxima página.

Mantenha os mesmos filtros e a mesma ordenação enquanto percorre páginas. Não reutilize o cursor de outra rota. As operações de histórico de automações usam paginação por página; consulte os parâmetros específicos da referência.

Em mensagens, `since` é inclusivo. Remova duplicatas pelo ID e envie `since` junto com `cursor` quando continuar a leitura para frente.

## Tratar respostas

Leia o status HTTP antes de processar o corpo. Uma resposta `204` não possui JSON. Nas respostas com envelope, os dados ficam em `data`; o formato exato está documentado em cada operação.

| Status         | Como tratar                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------- |
| `400` ou `422` | Corrija parâmetros ou valores conforme a mensagem. Não repita o mesmo corpo automaticamente. |
| `401`          | Confira a chave e se ela continua ativa.                                                     |
| `403`          | Confira permissões, acesso ao canal e recursos contratados.                                  |
| `404`          | O registro pode não existir ou estar fora da visibilidade do membro.                         |
| `409`          | Resolva o conflito de estado indicado antes de tentar novamente.                             |
| `429`          | Respeite `X-Rate-Limit-Retry-After-Seconds`.                                                 |

O limite geral é de 600 requisições por minuto, por workspace e por IP. Uma escrita não deve ser repetida às cegas após perda de conexão: consulte o estado antes. Para executar tarefas de cadência, reutilize a mesma `idempotencyKey` da operação original.