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

# Visão Geral da API

> Referência técnica completa dos endpoints da MessageFy API

# Referência da API

Esta seção contém a documentação técnica auto-gerada a partir da especificação OpenAPI do MessageFy.

<Note>
  Para guias práticos com exemplos de uso, consulte as seções [Enviando Mensagens](/mensagens/visao-geral),
  [Comandos](/comandos/visao-geral) e [Webhooks](/recebendo-eventos).
</Note>

## Base URL

| Ambiente        | URL                            |
| --------------- | ------------------------------ |
| Produção        | `https://api-prd.messagefy.io` |
| Staging         | `https://api-stg.messagefy.io` |
| Desenvolvimento | `https://api-dev.messagefy.io` |

## Autenticação

Todas as requisições devem incluir o header `X-API-KEY` com uma chave válida.
O gateway APISIX valida a chave e injeta automaticamente os headers de contexto:

| Header                         | Descrição           |
| ------------------------------ | ------------------- |
| `X-Consumer-Organization-Id`   | UUID da organização |
| `X-Consumer-Organization-Name` | Nome da organização |
| `X-Consumer-Account-Id`        | UUID da conta       |
| `X-Consumer-Account-Name`      | Nome da conta       |

## Endpoints

A API está organizada em dois grupos:

### Mensagens (`/api/v1/message/`)

Envio, recebimento, edição, exclusão e busca de mensagens.
Suporta múltiplos tipos de conteúdo (texto, imagem, documento, áudio, vídeo, etc.)
e comandos de sessão (status, contatos, grupos, etc.).

### Administração (`/api/v1/Admin/`)

CRUD de contas, canais e API keys.
Gerenciamento do outbox para canais HTTP Sender.

## Versionamento

A API usa versionamento por URL: `/api/v1/...`

## Formato de Resposta

Todas as respostas são JSON. Existem **dois formatos de erro**, dependendo de onde a
requisição falhou:

### 1. Erro de desserialização/binding (ProblemDetails)

Quando o corpo da requisição não pode ser desserializado (JSON malformado, `type`
desconhecido, campo obrigatório do schema ausente, tipo de valor errado), a resposta
segue o padrão ASP.NET `ValidationProblemDetails`:

```json theme={null}
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "package": ["The package field is required."],
    "$.content.to": ["The JSON value could not be converted to MessageFy.Protocol.Addressing.Address. ..."]
  },
  "traceId": "00-..."
}
```

<Note>
  A entrada `"package": ["The package field is required."]` **não** significa que falta um campo
  chamado `package` no seu JSON -- o corpo inteiro da requisição é o "package". Ela aparece sempre
  que a desserialização do corpo falha por qualquer motivo. A causa real está na **outra** entrada
  de `errors`, cuja chave é o caminho JSON do campo problemático (ex.: `$.content.to`).
</Note>

### 2. Erro de validação de negócio

Quando o JSON é válido mas viola uma regra de negócio (nome duplicado, canal inexistente,
feedback channel obrigatório etc.), a resposta é uma **lista** de erros de validação com
`errorCode`:

```json theme={null}
[
  {
    "propertyName": "Name",
    "errorMessage": "Nome já existe",
    "errorCode": "DUPLICATE_NAME"
  }
]
```