API de Mensageria Externa

Introdução

Visão geral

Esta documentação apresenta a API de Mensageria Externa no formato de referência (estilo Swagger) e descreve como um parceiro deve autenticar e integrar o próprio sistema.

A API foi criada para permitir que o cliente envie e receba mensagens fora do ERP Fórmula Certa ou Phusion, mantendo a integração de mensageria ativa por meio de uma aplicação externa.

Enviar mensagens

Dispare texto, imagem, áudio ou template para seus contatos via endpoint de envio.

Receber mensagens

Receba eventos de mensagem (tipo 1) no webhook que você configurar.

Acompanhar status

Receba eventos de status de entrega (tipo 2) para conciliar cada envio.

A configuração de webhook é obrigatória para receber os eventos de mensagem e de status no seu sistema.

Introdução

O que é webhook

Webhook é uma URL HTTP do seu sistema que recebe eventos automaticamente quando algo acontece na API.

Em vez de consultar a API repetidamente para verificar atualizações, é a API que envia um POST para o endpoint que você configurou assim que houver um novo evento.

Nesta integração, o webhook é utilizado para receber:

eventos de mensagem (tipo = 1);
eventos de status de mensagem (tipo = 2).

Introdução

Ambientes e URLs

DEV

Recurso	URL
API	`https://fate-mensageria-externa-api-dev-02.fagron.tech`
Swagger	`/swagger/index.html`
SSO (token)	`https://sso-dev-02.fagron.tech/connect/token`

Produção

As credenciais e URLs de produção são diferentes do ambiente DEV e serão compartilhadas em um segundo momento pela nossa equipe.

Introdução

Contrato padrão de resposta

Todos os endpoints retornam o mesmo envelope:

JSON

{
  "sucesso": true,
  "resultado": {},
  "erros": null
}

Campo	Descrição
`sucesso`	Indica sucesso ou falha da operação.
`resultado`	Payload de retorno em caso de sucesso.
`erros`	Lista de erros em caso de falha.

Comece por aqui

Guia de início rápido

Do zero ao primeiro envio em 8 passos. Os exemplos usam o ambiente DEV — troque os valores entre {{ }} pelos seus.

Passo 1 · Solicite usuário e senha

Solicite à nossa equipe um usuário e uma senha para o ambiente.

Passo 2 · Gere o token no SSO

Copie o comando abaixo, trocando Seu_Usuario e Sua_Senha. No retorno, copie o valor de access_token.

cURL

curl --location 'https://sso-dev-02.fagron.tech/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=Seu_Usuario' \
--data-urlencode 'password=Sua_Senha' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=fate_mensageria_externa_api' \
--data-urlencode 'client_secret={{CLIENT_SECRET}}' \
--data-urlencode 'scope=fate_mensageria_externa'

Passo 3 · Liste os webhooks cadastrados

Troque {{ACCESS_TOKEN}} pelo token do passo anterior.

cURL

curl --location 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/WebhookConfiguracao' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Se vier uma lista vazia, siga para o Passo 4 (cadastrar webhook). Se o webhook já existir e estiver correto, pule para o Passo 7 (enviar mensagem).

Passo 4 · Cadastre o webhook (se não existir)

cURL

curl --location 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/WebhookConfiguracao' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "enderecoUrl": "https://seu-dominio.com/webhook/status",
  "tipo": 2,
  "headerName": "X-Webhook-Token",
  "headerValue": "seu-token-secreto",
  "envioParaWebhookEFila": false
}'

Use tipo: 1 para evento de mensagem e tipo: 2 para evento de status. Cadastre os dois se quiser receber ambos.

Passo 5 · Altere o webhook (se precisar)

Use o id retornado na listagem ou no cadastro.

cURL

curl --location --request PUT 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/WebhookConfiguracao/{{ID_CONFIGURACAO}}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "enderecoUrl": "https://seu-dominio.com/webhook/status-v2",
  "tipo": 2,
  "headerName": "X-Webhook-Token",
  "headerValue": "novo-token-secreto",
  "envioParaWebhookEFila": true
}'

Passo 6 · Exclua o webhook (se precisar remover)

cURL

curl --location --request DELETE 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/WebhookConfiguracao/{{ID_CONFIGURACAO}}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Passo 7 · Envie uma mensagem

cURL

curl --location 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/Mensagem/enviar' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "para": "5511999999999",
  "de": "5511888888888",
  "texto": "Mensagem de teste",
  "provedor": "nome-do-provedor",
  "tipoMensagem": 1,
  "produto": "MeuProduto"
}'

Passo 8 · Aguarde o retorno no seu webhook

Após o envio, aguarde as chamadas HTTP no endpoint configurado por você. Os retornos chegam como eventos de:

Mensagem (tipo = 1) — dados da mensagem recebida/processada: telefone de origem, destino, texto, anexos, produto, tenant e identificadores de acompanhamento;
Status (tipo = 2) — andamento do envio: status, descrição, data, código/descrição de erro (quando houver) e acompanhamentoId para conciliação.

Comece por aqui

Autenticação (SSO)

A API usa autenticação Bearer Token. Gere o token no SSO com seu usuário e senha (fluxo password) e envie-o no header Authorization de cada requisição.

POST https://sso-dev-02.fagron.tech/connect/token

Parâmetros (x-www-form-urlencoded)

Parâmetro	Valor
`grant_type`	`password`
`username`	seu usuário
`password`	sua senha
`client_id`	`fate_mensageria_externa_api`
`client_secret`	`{{CLIENT_SECRET}}` — fornecido pela nossa equipe
`scope`	`fate_mensageria_externa`

Exemplo

cURL

curl --location 'https://sso-dev-02.fagron.tech/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=Seu_Usuario' \
--data-urlencode 'password=Sua_Senha' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=fate_mensageria_externa_api' \
--data-urlencode 'client_secret={{CLIENT_SECRET}}' \
--data-urlencode 'scope=fate_mensageria_externa'

Usando o token

Inclua o access_token retornado no header de toda chamada à API:

HTTP Header

Authorization: Bearer {{ACCESS_TOKEN}}

Solicite o client_secret, o usuário e a senha à nossa equipe (DEV e produção usam segredos diferentes). Nunca exponha credenciais em repositórios públicos, no front-end ou em páginas acessíveis externamente.

Experimente

Playground

Gere um token de homologação e faça chamadas reais à API direto desta página. Edite o corpo, envie e veja a resposta — ou copie tudo como cURL.

Suas credenciais ficam apenas no seu navegador e são enviadas diretamente para a API de homologação — nada passa por nós nem é gravado. O token vale só para esta sessão (não é salvo). Use apenas dados de homologação/DEV.

As chamadas saem do seu navegador. Se a API não autorizar a origem desta página (CORS) — por exemplo ao abrir o arquivo localmente — o navegador bloqueia a requisição. Nesse caso use Copiar como cURL e rode no terminal/Postman, ou hospede a página numa origem autorizada.

1 Autenticação

URL do token (SSO)

URL base da API

Usuário

Senha

client_id

client_secret

scope

Sem token

2 Requisição

Endpoint

POST

Carregar exemplo de corpo

Corpo da requisição (JSON)

API · Mensagem

Enviar mensagem

Enfileira uma mensagem para processamento e envio.

POST /api/Mensagem/enviar

Regras importantes

para é obrigatório;
de é obrigatório;
provedor é obrigatório;
para envio de anexo, informe mediaUrl com uma URL pública HTTPS do arquivo;
para envio por template, o template já deve estar previamente configurado no Mobypharma.

Campos do corpo

Campo	Tipo	Obrig.	Descrição
`para`	string	Sim	Número de destino (com DDI/DDD).
`de`	string	Sim	Número de origem.
`provedor`	string	Sim	Provedor de envio. Ex.: `twilio`.
`tipoMensagem`	int	—	Tipo da mensagem. Ver enum tipoMensagem.
`texto`	string	cond.	Conteúdo de texto ou corpo do template.
`mediaUrl`	string	cond.	URL pública HTTPS do anexo (imagem/áudio).
`produto`	string	—	Produto de origem. Ex.: `phusion`.
`template`	objeto	cond.	Dados do template: `nome`, `linguagem`, `contentTemplateSId`.
`dadosTemplate`	objeto	cond.	Parâmetros do template: `tipo` e `parametros[]`.

Exemplos de corpo por tipo

JSON · tipoMensagem 1

{
  "para": "5511997370379",
  "de": "5540200236",
  "texto": "Teste envio Postman",
  "provedor": "twilio",
  "tipoMensagem": 1,
  "produto": "phusion"
}

JSON · tipoMensagem 2

{
  "para": "5511997370379",
  "de": "5540200236",
  "provedor": "twilio",
  "tipoMensagem": 2,
  "mediaUrl": "https://seu-cdn.com/arquivos/imagem.png",
  "produto": "phusion"
}

JSON · tipoMensagem 5

{
  "para": "5511996326295",
  "de": "5540200236",
  "texto": "Olá {{1}}, podemos falar com você? Responda com sim que daremos continuidade na conversa.",
  "provedor": "twilio",
  "tipoMensagem": 5,
  "produto": "phusion",
  "template": {
    "nome": "",
    "linguagem": "",
    "contentTemplateSId": "HX9e656fbd35b3ed852a21999529ab6e2c"
  },
  "dadosTemplate": {
    "tipo": 1,
    "parametros": [
      {
        "numeroParametro": 1,
        "parametro": "Carol"
      }
    ]
  }
}

JSON · tipoMensagem 9

{
  "para": "5511997370379",
  "de": "5540200236",
  "provedor": "twilio",
  "tipoMensagem": 9,
  "mediaUrl": "https://seu-cdn.com/arquivos/audio.ogg",
  "produto": "phusion"
}

Exemplo cURL

cURL

curl --location 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/Mensagem/enviar' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "para": "5511999999999",
  "de": "5511888888888",
  "texto": "Mensagem de teste",
  "provedor": "nome-do-provedor",
  "tipoMensagem": 1,
  "produto": "MeuProduto"
}'

Respostas

200OK — mensagem enfileirada

JSON

{
  "sucesso": true,
  "resultado": {
    "id": "6626cb9b2b7d5f6c5f87a912",
    "registradoEm": "2026-04-22T14:30:12.345Z"
  },
  "erros": null
}

400Bad Request — validação

JSON

{
  "sucesso": false,
  "resultado": null,
  "erros": [
    "Para e obrigatorio.",
    "De e obrigatorio.",
    "Provedor e obrigatorio."
  ]
}

400Bad Request — configuração tenant/número

JSON

{
  "sucesso": false,
  "resultado": null,
  "erros": [
    "Configuracao nao encontrada para o tenantId e numero informados."
  ]
}

401Unauthorized

JSON

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401
}

500Internal Server Error

JSON

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "title": "An error occurred while processing your request.",
  "status": 500
}

API · Webhook Configuração

Listar configurações

Lista as configurações de webhook do tenant autenticado.

GET /api/WebhookConfiguracao

Exemplo cURL

cURL

curl --location 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/WebhookConfiguracao' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Respostas

200OK

JSON

{
  "sucesso": true,
  "resultado": [
    {
      "id": "6626cf0d2b7d5f6c5f87a913",
      "tenant": "tenant-exemplo",
      "enderecoUrl": "https://parceiro.com/webhooks/mensagem",
      "tipo": 1,
      "headerName": "X-Webhook-Token",
      "headerValue": "token-seguro",
      "envioParaWebhookEFila": false
    },
    {
      "id": "6626d0102b7d5f6c5f87a914",
      "tenant": "tenant-exemplo",
      "enderecoUrl": "https://parceiro.com/webhooks/status",
      "tipo": 2,
      "headerName": "X-Webhook-Token",
      "headerValue": "token-seguro",
      "envioParaWebhookEFila": false
    }
  ],
  "erros": null
}

400Bad Request

JSON

{
  "sucesso": false,
  "resultado": null,
  "erros": [
    "Erro ao se comunicar com o servico de configuracao de webhook."
  ]
}

API · Webhook Configuração

Criar configuração

Cria uma configuração de webhook.

POST /api/WebhookConfiguracao

Campos do corpo

Campo	Tipo	Obrig.	Descrição
`enderecoUrl`	string	Sim	URL do seu endpoint. Deve usar HTTPS.
`tipo`	int	Sim	`1` = Mensagem, `2` = Status.
`headerName`	string	—	Nome do header de segurança enviado nas chamadas.
`headerValue`	string	—	Valor do header de segurança.
`envioParaWebhookEFila`	bool	—	Define o envio para webhook e fila.

Exemplo cURL

cURL

curl --location 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/WebhookConfiguracao' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "enderecoUrl": "https://parceiro.com/webhooks/status",
  "tipo": 2,
  "headerName": "X-Webhook-Token",
  "headerValue": "token-seguro",
  "envioParaWebhookEFila": false
}'

Respostas

200OK — criado

JSON

{
  "sucesso": true,
  "resultado": {
    "id": "6626cf0d2b7d5f6c5f87a913",
    "tenant": "tenant-exemplo",
    "enderecoUrl": "https://parceiro.com/webhooks/status",
    "tipo": 2,
    "headerName": "X-Webhook-Token",
    "headerValue": "token-seguro",
    "envioParaWebhookEFila": false
  },
  "erros": null
}

400Bad Request — validação

JSON

{
  "sucesso": false,
  "resultado": null,
  "erros": [
    "EnderecoUrl e obrigatoria.",
    "EnderecoUrl deve utilizar o protocolo HTTPS.",
    "Tipo deve ser um dos valores validos do enum (1 - Mensagem ou 2 - Status)."
  ]
}

API · Webhook Configuração

Atualizar configuração

Atualiza uma configuração de webhook existente.

PUT /api/WebhookConfiguracao/{id}

Exemplo cURL

cURL

curl --location --request PUT 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/WebhookConfiguracao/{{ID_CONFIGURACAO}}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "enderecoUrl": "https://parceiro.com/webhooks/status-v2",
  "tipo": 2,
  "headerName": "X-Webhook-Token",
  "headerValue": "token-seguro-novo",
  "envioParaWebhookEFila": true
}'

Respostas

200OK — atualizado

JSON

{
  "sucesso": true,
  "resultado": {
    "id": "6626cf0d2b7d5f6c5f87a913",
    "tenant": "tenant-exemplo",
    "enderecoUrl": "https://parceiro.com/webhooks/status-v2",
    "tipo": 2,
    "headerName": "X-Webhook-Token",
    "headerValue": "token-seguro-novo",
    "envioParaWebhookEFila": true
  },
  "erros": null
}

400Bad Request

JSON

{
  "sucesso": false,
  "resultado": null,
  "erros": [
    "EnderecoUrl deve utilizar o protocolo HTTPS."
  ]
}

API · Webhook Configuração

Excluir configuração

Exclui uma configuração de webhook.

DELETE /api/WebhookConfiguracao/{id}

Exemplo cURL

cURL

curl --location --request DELETE 'https://fate-mensageria-externa-api-dev-02.fagron.tech/api/WebhookConfiguracao/{{ID_CONFIGURACAO}}' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Respostas

200OK — excluído

JSON

{
  "sucesso": true,
  "resultado": true,
  "erros": null
}

400Bad Request

JSON

{
  "sucesso": false,
  "resultado": null,
  "erros": [
    "Erro ao se comunicar com o servico de configuracao de webhook."
  ]
}

Eventos no seu webhook

Evento de Mensagem (tipo 1)

Quando configurado, o sistema envia POST no seu enderecoUrl com Content-Type: application/json. Se headerName e headerValue estiverem preenchidos, o header também é enviado.

No webhook de mensagem (tipo = 1), devolvemos os dados da mensagem recebida/processada.

Campo	Descrição
`acompanhamentoId`	Identificador de acompanhamento da mensagem.
`canal`	Canal de origem. Ex.: `WhatsApp`.
`tenant` / `filial`	Identificação do tenant e da filial.
`clienteNome`	Nome do contato.
`de` / `para`	Telefone de origem e de destino.
`texto`	Conteúdo textual da mensagem.
`canalParticularidade`	Metadados do canal (JSON serializado). Ex.: provedor.
`produto`	Produto associado.
`time` / `sequency`	Marca de tempo e sequência da mensagem.
`anexos[]`	Anexos com `tipo`, `url` e `thumbnail`.
`mensagemCitada`	Mensagem citada (reply), quando houver.
`mensagemEnviada`	Controle de fluxo: indica se a mensagem foi enviada por você.

Exemplo de payload

JSON · enviado ao seu webhook

{
  "acompanhamentoId": "wamid.HBgLM...",
  "canal": "WhatsApp",
  "tenant": "tenant-exemplo",
  "filial": 123,
  "clienteNome": "Maria",
  "de": "5511999999999",
  "para": "5511888888888",
  "texto": "Oi, preciso de ajuda",
  "canalParticularidade": "{\"Provedor\":\"nome-do-provedor\"}",
  "produto": "MeuProduto",
  "time": 1713796502,
  "sequency": 1,
  "anexos": [
    {
      "tipo": "Imagem",
      "url": "https://cdn.parceiro.com/imagem.jpg",
      "thumbnail": "https://cdn.parceiro.com/thumb.jpg"
    }
  ],
  "mensagemCitada": {
    "mensagemCitadaId": "wamid.HBgLMabc",
    "textoCitado": "Mensagem anterior",
    "urlAnexoCitado": null,
    "tipoAnexo": null
  },
  "mensagemEnviada": false
}

Eventos no seu webhook

Evento de Status (tipo 2)

No webhook de status (tipo = 2), devolvemos o andamento do envio.

Campo	Descrição
`acompanhamentoId`	Identificador para conciliação — tende a representar o `id` retornado no `POST /api/Mensagem/enviar`.
`status`	Código do status atual da mensagem.
`descricao`	Descrição legível do status. Ex.: `Mensagem entregue`.
`dataRecebimento`	Data/hora do evento (ISO 8601).
`produto` / `tenant`	Identificação do produto e do tenant.
`erroCodigo` / `erroMensagem`	Código e descrição do erro, quando houver.

Exemplo de payload

JSON · enviado ao seu webhook

{
  "acompanhamentoId": "6626cb9b2b7d5f6c5f87a912",
  "status": 2,
  "descricao": "Mensagem entregue",
  "dataRecebimento": "2026-04-22T14:33:21.198Z",
  "produto": "MeuProduto",
  "tenant": "tenant-exemplo",
  "erroCodigo": null,
  "erroMensagem": null
}

Use o acompanhamentoId para casar o evento de status com o id recebido na resposta do envio e conciliar a entrega no seu sistema.

Eventos no seu webhook

Resposta esperada do seu endpoint

Para confirmar o recebimento correto do evento, seu endpoint deve responder com HTTP 2xx.

200OK

204No Content

Respostas fora da faixa 2xx são tratadas como falha de entrega do evento ao seu sistema.

Referência

Enums

`tipoMensagem` — tipo da mensagem enviada

Valor	Significado
`1`	Texto
`2`	Imagem
`5`	Template
`9`	Áudio

`tipo` — tipo de webhook

Valor	Significado
`1`	Mensagem
`2`	Status

Regras de webhook

enderecoUrl é obrigatório;
enderecoUrl deve ser HTTPS;
tipo deve ser 1 ou 2.

Referência

Erros e respostas HTTP

Em caso de falha, o envelope traz sucesso: false e a lista erros preenchida. Os principais códigos:

HTTP	Significado	Quando acontece
200	OK	Operação concluída com sucesso.
400	Bad Request	Validação de campos, configuração ausente ou falha ao comunicar com o serviço de webhook.
401	Unauthorized	Token ausente, inválido ou expirado. Gere um novo no SSO.
500	Internal Server Error	Erro inesperado ao processar a requisição.

Recebeu 401? O token expirou — refaça o passo de autenticação e use o novo access_token.

Visão geral

Enviar mensagens

Receber mensagens

Acompanhar status

O que é webhook

Ambientes e URLs

DEV

Produção

Contrato padrão de resposta

Guia de início rápido

Passo 1 · Solicite usuário e senha

Passo 2 · Gere o token no SSO

Passo 3 · Liste os webhooks cadastrados

Passo 4 · Cadastre o webhook (se não existir)

Passo 5 · Altere o webhook (se precisar)

Passo 6 · Exclua o webhook (se precisar remover)

Passo 7 · Envie uma mensagem

Passo 8 · Aguarde o retorno no seu webhook

Autenticação (SSO)

Parâmetros (x-www-form-urlencoded)

Exemplo

Usando o token

Playground

Enviar mensagem

Regras importantes

Campos do corpo

Exemplos de corpo por tipo

Exemplo cURL

Respostas

Listar configurações

Exemplo cURL

Respostas

Criar configuração

Campos do corpo

Exemplo cURL

Respostas

Atualizar configuração

Exemplo cURL

Respostas

Excluir configuração

Exemplo cURL

Respostas

Evento de Mensagem (tipo 1)

Exemplo de payload

Evento de Status (tipo 2)

Exemplo de payload

Resposta esperada do seu endpoint

Enums

tipoMensagem — tipo da mensagem enviada

tipo — tipo de webhook

Regras de webhook

Erros e respostas HTTP

`tipoMensagem` — tipo da mensagem enviada

`tipo` — tipo de webhook