Referência da API

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

Para guias práticos com exemplos de uso, consulte as seções Enviando Mensagens, Comandos e Webhooks.

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:

{
  "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-..."
}

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).

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:

[
  {
    "propertyName": "Name",
    "errorMessage": "Nome já existe",
    "errorCode": "DUPLICATE_NAME"
  }
]

Referência API

Mensagens

Contas

API Keys

Canais

Outbox

Outros

Visão Geral da API

Referência da API

Base URL

Autenticação

Endpoints

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

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

Versionamento

Formato de Resposta

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

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

​Referência da API

​Base URL

​Autenticação

​Endpoints

​Mensagens (/api/v1/message/)

​Administração (/api/v1/Admin/)

​Versionamento

​Formato de Resposta

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

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

Referência da API

Base URL

Autenticação

Endpoints

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

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

Versionamento

Formato de Resposta

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

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