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

# Requisições e respostas

> O envelope de resposta da API do Connecta DESK: data, meta e error. Formatos aceitos, códigos de status e a ordem de verificação de cada requisição.

Os 150 endpoints da v1 respondem no mesmo formato, que chamamos de envelope. Assim, você escreve o
cliente HTTP uma vez e reaproveita em toda a API.

## O envelope

<Tabs>
  <Tab title="Item">
    Um recurso vem sempre dentro de `data`:

    ```json theme={null}
    {
      "data": {
        "id": 1042,
        "name": "Marina Alves",
        "number": "5511999999999"
      }
    }
    ```
  </Tab>

  <Tab title="Lista">
    Listas trazem `data` como array e um `meta` com os dados de paginação:

    ```json theme={null}
    {
      "data": [
        { "id": 1042, "name": "Marina Alves" },
        { "id": 1043, "name": "Rafael Nunes" }
      ],
      "meta": { "page": 1, "perPage": 20, "hasMore": true }
    }
    ```
  </Tab>

  <Tab title="Erro">
    Erros nunca vêm em `data`. O corpo tem um único campo `error`:

    ```json theme={null}
    {
      "error": {
        "code": "ERR_API_VALIDATION",
        "message": "Informe ao menos um destes campos: name, number.",
        "details": null
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  Leia sempre o recurso em `resposta.data`, nunca na raiz do corpo. O envelope pode ganhar campos
  novos no futuro.
</Note>

## Enviando dados

<ParamField header="Content-Type" type="application/json">
  O padrão para criar e editar. Use em todo `POST` e `PUT` que não envolva arquivo.
</ParamField>

<ParamField header="Content-Type" type="multipart/form-data">
  Necessário quando a requisição leva arquivo, como mídia de mensagem, imagem de produto, anexo de
  anotação do CRM ou planilha de campanha. Os campos de texto vão no mesmo formulário.
</ParamField>

Os endpoints que recebem arquivo aceitam **os dois formatos**. Sem arquivo, envie JSON puro. Com
arquivo, envie o formulário. Quando os dois formatos existem, a referência do endpoint mostra
ambos.

## Códigos de status

| Código | Quando acontece |
| - | - |
| `200` | Leitura ou alteração concluída. |
| `201` | Recurso criado. O corpo traz o registro novo. |
| `202` | Aceito para processamento assíncrono (hoje, o envio de mensagem). O corpo traz o `jobId`. |
| `204` | Concluído, sem corpo na resposta. Comum em exclusões. |
| `400` | Requisição malformada ou campo obrigatório ausente. |
| `401` | Problema com o token. Veja [Autenticação](/authentication). |
| `403` | Empresa inativa, plano sem API ou token sem a permissão necessária. |
| `404` | O recurso não existe ou pertence a outra empresa. |
| `409` | Conflito de estado, incluindo reuso de `Idempotency-Key`. |
| `422` | O corpo está bem formado, mas viola uma regra de negócio. |
| `429` | A empresa atingiu o limite de requisições por minuto. |

## Ordem de verificação

Antes de chegar ao endpoint, cada requisição passa por cinco verificações, nesta ordem. Você
recebe o erro da primeira que falhar, o que ajuda a encontrar o problema mais rápido.

<Steps>
  <Step title="Token" icon="key">
    O token existe, é válido, não foi revogado nem expirou, e a origem da chamada está na allowlist
    de IPs. Se falhar, a resposta é `401`.
  </Step>

  <Step title="Empresa ativa" icon="building">
    A empresa dona do token está ativa e dentro da validade. Se falhar, a resposta é `403`.
  </Step>

  <Step title="API liberada no plano" icon="package-check">
    O plano contratado inclui a API pública. Se falhar, a resposta é `403 ERR_API_NOT_ENABLED`.

    Essa verificação não se aplica a instalações on-premise.
  </Step>

  <Step title="Rate limit" icon="gauge">
    A empresa está dentro do limite de requisições por minuto. Se falhar, a resposta é `429`.
  </Step>

  <Step title="Permissão do token" icon="shield-check">
    O token tem permissão para aquele método naquele módulo. Se falhar, a resposta é
    `403 ERR_API_FORBIDDEN_SCOPE`.
  </Step>
</Steps>

## Identificadores e escopo

Todo recurso tem um id numérico, e **cada id vale apenas dentro da empresa do token**. Se você
pedir um id que pertence a outra empresa, recebe `404`, como se o registro não existisse.

<Warning>
  Os ids não são globais, e não há como prever qual id um registro terá em outro ambiente. Não
  copie ids de homologação para produção. Busque o registro pelo campo natural (número do contato,
  SKU do produto, e-mail do usuário) e guarde o id que vier na resposta.
</Warning>


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