📄 Documentação da API - WhatsContábil

Introdução

Essa API foi desenvolvida para permitir o envio de mensagens através da plataforma WhatsContábil. Você pode enviar mensagens de texto e mídias assim como consultar contatos, usuários e conexões.

Envio de Mensagens

Variáveis:

• URL: Link fornecido pelo WhatsContábil para envio das requisições
• TOKEN: JWT fornecido pelo cliente para autenticar as requisições

Endpoint: https://<URL>/api/messages/send

Método: POST

Parâmetros

• medias: anexo do arquivo a ser enviado no fluxo padrão
• to: número do contato (ex: 5511000000000)
• message: mensagem de texto
• whatsappId: (opcional) ID da conexão

Headers:

• Authorization: Bearer <TOKEN>

Exemplos

Node.js (Axios)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('to', '5511000000000');
form.append('message', 'Olá, tudo bem?');
form.append('medias', fs.createReadStream('./caminho/arquivo.jpg'));

axios.post('https://<URL>/api/messages/send', form, {
  headers: {
    ...form.getHeaders(),
    Authorization: 'Bearer <TOKEN>',
  },
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error.response.data);
});

PHP (cURL)

<?php
$curl = curl_init();

$data = [
  'to' => '5511000000000',
  'message' => 'Olá, tudo bem?',
  'medias' => new CURLFile('caminho/arquivo.jpg'),
];

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://<URL>/api/messages/send',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $data,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>'
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

Python (requests)

import requests

url = "https://<URL>/api/messages/send"
headers = {
    "Authorization": "Bearer <TOKEN>"
}

files = {
    "to": (None, "5511000000000"),
    "message": (None, "Olá, tudo bem?"),
    "medias": open("caminho/arquivo.jpg", "rb")
}

response = requests.post(url, headers=headers, files=files)
print(response.json())

Cloud API (API Oficial Meta)

Para o envio pela Cloud API oficial da Meta, primeiro é necessário consultar a conexão existente para obter o whatsappId, depois consultar os templates dessa conexão e, por fim, enviar usando apenas o nome do template.

1. Consultar conexões

Endpoint: https://<URL>/api/whatsapps

Use como whatsappId o campo id da conexão cujo campo isOfficial seja igual a 1. Quando isOfficial for 0, a conexão não pertence à Cloud API oficial e não deve ser usada nesse fluxo.

2. Consultar templates

Endpoint: https://<URL>/api/templates/

Informe ao final da rota o whatsappId obtido no passo 1 para consultar os templates da conexão desejada.

Método: GET

Do retorno do template, você precisa usar somente o campo name. Os valores de components e example servem para identificar a ordem das variáveis enviadas no campo message.

curl --location --request GET 'https://api.whatscontabil.com.br/api/templates/76' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>'

[
  {
    "name": "aviso_vencido",
    "parameter_format": "POSITIONAL",
    "components": [
      {
        "type": "HEADER",
        "format": "DOCUMENT",
        "example": {
          "header_handle": [
            "https://scontent.whatsapp.net/...pdf"
          ]
        }
      },
      {
        "type": "BODY",
        "text": "Olá {{1}} ... {{2}} ... {{3}}",
        "example": {
          "body_text": [
            ["Vini", "10/05/2026", "R$ 1.800,01"]
          ]
        }
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "URL",
            "text": "Portal de Documentos",
            "url": "https://financeiro.whatscontabil.com.br/{{1}}"
          }
        ]
      }
    ],
    "language": "pt_BR",
    "status": "APPROVED"
  }
]

3. Enviar template pela API oficial

Endpoint: https://<URL>/api/messages/send

Método: POST

Parâmetros da Cloud API

• to: número do destinatário com DDI e DDD
• template: nome do template aprovado
• message: array JSON em formato string com as variáveis do template
• files: arquivo(s) enviado(s) quando o template possuir header do tipo documento
• whatsappId: ID da conexão obtido no passo 1 em /api/whatsapps, usando a conexão com isOfficial = 1

No campo message, envie as variáveis na mesma ordem dos placeholders do template. Se o template não possuir variáveis, envie apenas o nome do template e os demais campos necessários. Para esse fluxo, o campo de arquivo é files.

curl --location 'https://api.whatscontabil.com.br/api/messages/send' \
--header 'Authorization: Bearer <TOKEN>' \
--form 'to="5511000000001"' \
--form 'message="[\"Marcel\", \"15/05/2026\", \"R$ 5.105,90\", \"login?cnpj=00.000.000%2F0000-00&codigo=12345&origem=api\"]"' \
--form 'template="aviso_vencido"' \
--form 'files=@"/C:/Users/mathe/Downloads/Cardapio Acai King Ipaussu_1777561731703.pdf"' \
--form 'whatsappId="81"'

Node.js (Axios) - Cloud API

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('to', '5511000000001');
form.append('message', JSON.stringify([
  'Marcel',
  '15/05/2026',
  'R$ 5.105,90',
  'login?cnpj=00.000.000%2F0000-00&codigo=12345&origem=api'
]));
form.append('template', 'aviso_vencido');
form.append('files', fs.createReadStream('C:/caminho/documento.pdf'));
form.append('whatsappId', '81');

axios.post('https://<URL>/api/messages/send', form, {
  headers: {
    ...form.getHeaders(),
    Authorization: 'Bearer <TOKEN>',
  },
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error.response?.data || error.message);
});

PHP (cURL) - Cloud API

<?php
$curl = curl_init();

$data = [
  'to' => '5511000000001',
  'message' => json_encode([
    'Marcel',
    '15/05/2026',
    'R$ 5.105,90',
    'login?cnpj=00.000.000%2F0000-00&codigo=12345&origem=api'
  ]),
  'template' => 'aviso_vencido',
  'files' => new CURLFile('C:/caminho/documento.pdf'),
  'whatsappId' => '81',
];

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://<URL>/api/messages/send',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $data,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>'
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

Python (requests) - Cloud API

import json
import requests

url = "https://<URL>/api/messages/send"
headers = {
    "Authorization": "Bearer <TOKEN>"
}

data = {
    "to": "5511000000001",
    "message": json.dumps([
        "Marcel",
        "15/05/2026",
        "R$ 5.105,90",
        "login?cnpj=00.000.000%2F0000-00&codigo=12345&origem=api"
    ]),
    "template": "aviso_vencido",
    "whatsappId": "81"
}

files = {
    "files": open("C:/caminho/documento.pdf", "rb")
}

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

Resposta de sucesso

Código de status HTTP: 200 (OK)
Corpo da resposta:
{
  "message": "Mensagem enviada com sucesso!"
}

Códigos de Erro

• 401 - ERR_SESSION_EXPIRED. Token inválido/não fornecido.
• 403 - PAYLOAD TOO LARGE. O tamanho da requisição excede o limite de 20 MB.
• 403 - INVALID TOKEN. Token inválido.
• 404 - ERR_NO_API_TOKEN_FOUND. Token inválido.
• 429 - TOO MANY REQUESTS. Limite de requisições excedido. Tente novamente mais tarde.
• 500 - INTERNAL SERVER ERROR. Erro no processamento da requisição.
• 500 - ERR_WAPP_INVALID_CONTACT. Esse número não é um contato válido do Whatsapp.
• 500 - ERR_WAPP_CHECK_CONTACT. Não foi possível verificar esse número.
• 500 - ERR_NUMBER_FORMAT_INVALID. Formato de número inválido.
• 500 - ERR_NUMBER_FORMAT_INVALID. Não foi possível enviar a mensagem pelo Whatsapp.
• 500 - ERR_NO_DEF_WAPP_FOUND. Não encontramos nenhum Whatsapp padrão configurado.
• 500 - ERR_WAPP_NOT_INITIALIZED. Conexão com Whatsapp não estabelecida/estável.
• 500 - TOO_MANY_MEDIAS. A quantidade de arquivos excede o limite de 3 arquivos por requisição.
• 500 - TOO_MANY_CARACTERS. Tamanho da mensagem excede o limite de 2000 caracteres.

Listagem de Contatos

Usado para obter todos os contatos cadastrados no sistema.

Endpoint: https://<URL>/api/contacts/

Método: GET

Headers

• Authorization: Bearer <TOKEN>

Resposta de sucesso

Código de status HTTP: 200 (OK)
Corpo da resposta:
[
  {
    "id": 297,
    "name": "Financeiro G-One",
    "number": "5511000000002",
    "email": "",
    "profilePicUrl": null,
    "isGroup": false,
    "respostaAutomatica": false,
    "createdAt": "2022-04-27T18:40:49.000Z",
    "tags": []
  },
  {
    "id": 4190,
    "name": "Suporte GOne",
    "number": "5511000000003",
    "email": "",
    "profilePicUrl": "https://pps.whatsapp.net/example.jpg",
    "isGroup": false,
    "respostaAutomatica": false,
    "createdAt": "2024-05-13T18:00:48.000Z",
    "tags": []
  }
]

Consulta de Contatos

Endpoint: https://<URL>/api/contacts/<contactId>

Método: GET

Variáveis:

• contactId: Identificador do contato no sistema

Headers

• Authorization: Bearer <TOKEN>

Resposta de sucesso

Código de status HTTP: 200 (OK)
Corpo da resposta:
{
  "id": 4190,
  "name": "Suporte GOne",
  "number": "5511000000003",
  "email": "",
  "profilePicUrl": "https://pps.whatsapp.net/example.jpg",
  "isGroup": false,
  "respostaAutomatica": false,
  "createdAt": "2024-05-13T18:00:48.000Z",
  "extraInfo": [],
  "tags": []
}

Códigos de Erro

• 404 - ERR_NO_CONTACT_FOUND. Contato não encontrado no sistema.
• 400 - ERR_BAD_REQUEST. Parâmetros em falta.

Consulta de Grupos

Este endpoint permite consultar informações sobre um grupo específico utilizando o ID do contato do grupo, incluindo os IDs das conexões que são participantes do grupo.

Endpoint: https://<URL>/api/contacts/group/<contactId>

Método: GET

Variáveis:

• contactId: Identificador do grupo no sistema

Headers

• Authorization: Bearer <TOKEN>

Exemplos

Node.js (Axios)

const axios = require('axios');

const contactId = 4190;
const url = `https://<URL>/api/contacts/group/${contactId}`;

const config = {
  method: 'get',
  url,
  headers: {
    Authorization: 'Bearer <TOKEN>'
  },
};

axios.request(config)
  .then(response => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch(error => {
    console.error(error.response?.data || error.message);
  });

PHP (cURL)

<?php
$curl = curl_init();
$contactId = 4190;

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://<URL>/api/contacts/group/' . $contactId,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_GET => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>'
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

Python (requests)

import requests

contact_id = 4190
url = f"https://<URL>/api/contacts/group/{contact_id}"

headers = {
    "Authorization": "Bearer <TOKEN>"
}

response = requests.get(url, headers=headers)
print(response.json())

Resposta de sucesso

Código de status HTTP: 200 (OK)
Corpo da resposta:
{
  "groupId": "1234",
  "jid": "[email protected]",
  "groupName": "Grupo de exemplo",
  "groupDescription": "Descrição do grupo criado como exemplo para API",
  "participantCount": 5,
  "connectionsInGroup": [
    2,
    8
  ]
}

Observação

• connectionsInGroup: Identificador das conexões que são participantes do grupo

Códigos de Erro

• 404 - ERR_NO_CONTACT_FOUND. Grupo não encontrado no sistema.
• 400 - ERR_BAD_REQUEST. Parâmetros em falta.

Consulta de Usuário

Este endpoint permite a consulta detalhada dos dados cadastrais de um usuário previamente registrado no sistema, a partir do seu ID.

Endpoint: https://<URL>/api/users/<userId>

Método: GET

Variáveis:

• URL: Link fornecido pelo WhatsContábil para envio das requisições
• TOKEN: JWT fornecido pelo cliente para autenticar as requisições
• userId: Identificador do usuário

Headers

• Authorization: Bearer <TOKEN>

Resposta de sucesso

Código de status HTTP: 200 (OK)
Corpo da resposta:
{
  "profilePicUrl": "https://api.whatscontabil.com.br/assets/1743082072733_user.png",
  "id": 7,
  "name": "Matheus",
  "email": "u2Sd6vukib8rfQUpQLcsAHKFlzk6ndA4kAFKQStZ1HegP1z+D7+4UPPdZs6pd",
  "profile": "admin",
  "weekdays": true,
  "saturday": true,
  "sunday": true,
  "holidays": true,
  "startTime": "08:00",
  "endTime": "18:00",
  "editContact": true,
  "addContact": true,
  "delContact": true,
  "status": "offline",
  "active": true,
  "whatsappId": null,
  "createdAt": "2022-03-21T11:57:17.000Z"
}

Códigos de Erro

• 404 - ERR_NO_USER_FOUND. Usuário não encontrado no sistema.
• 400 - ERR_BAD_REQUEST. Parâmetros em falta.

Listagem de Conexões

Este endpoint permite listar todas as conexões atualmente registradas na plataforma.

Na Cloud API oficial, utilize como whatsappId o id da conexão em que isOfficial seja 1. Se isOfficial for 0, essa conexão não é oficial. Esse mesmo id deve ser reaproveitado na consulta de templates e no envio da mensagem.

Endpoint: https://<URL>/api/whatsapps

Método: GET

Variáveis:

• URL: Link fornecido pelo WhatsContábil para envio das requisições
• TOKEN: JWT fornecido pelo cliente para autenticar as requisições

Headers

• Authorization: Bearer <TOKEN>

Resposta de sucesso

Código de status HTTP: 200 (OK)
Corpo da resposta:
{
  "id": 57,
  "name": "default_1734541459088",
  "status": "CONNECTED",
  "battery": null,
  "plugged": null,
  "greetingMessage": "",
  "farewellMessage": "",
  "isDefault": true,
  "phoneNumber": null,
  "phoneNumberId": "5511000000004:[email protected]",
  "createdAt": "2025-04-23T13:37:39.000Z"
}

Consulta de Mensagens por Contato

Este endpoint permite listar as mensagens trocadas com um contato específico durante um intervalo de tempo determinado.

Endpoint: https://<URL>/api/messages/<contactId>

Método: GET

Variáveis:

• URL: Link fornecido pelo WhatsContábil para envio das requisições
• TOKEN: JWT fornecido pelo cliente para autenticar as requisições
• startDate: Data de início do filtro
• endDate: Data de término do filtro
• contactId: Identificador do contato

Params:

• startDate: data de início (YYYY-MM-DD HH:mm:ss)
• endDate: data de término

Headers

• Authorization: Bearer <TOKEN>

Exemplos

Node.js (Axios)

const axios = require('axios');

const startDate = '2025-04-01 00:00:00';
const endDate = '2025-04-23 23:59:59';
const contactId = 9890;

const url = `https://api.whatscontabil.com.br/api/messages/${contactId}?startDate=${encodeURIComponent(startDate)}&endDate=${encodeURIComponent(endDate)}`;

const config = {
  method: 'get',
  url,
  headers: {
    Authorization: 'Bearer <TOKEN>'
  },
};

axios.request(config)
  .then(response => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch(error => {
    console.error(error.response?.data || error.message);
  });

Resposta de sucesso

Código de status HTTP: 200 (OK)
Corpo da resposta:
[
  {
    "id": "3EB09ADD9461F9DCCC8E6C",
    "ack": 3,
    "read": true,
    "fromMe": false,
    "body": "teste 1",
    "mediaType": "chat",
    "mediaUrl": null,
    "createdAt": "2025-04-23T13:41:07.338Z",
    "ticketId": 28687,
    "contactId": 9890
  },
  {
    "id": "3EB0F26ED537014C8158",
    "ack": 2,
    "read": true,
    "fromMe": true,
    "body": "musica",
    "mediaType": "chat",
    "mediaUrl": null,
    "createdAt": "2025-04-23T13:50:52.877Z",
    "ticketId": 28687,
    "contactId": 9890
  }
]

Códigos de Erro

• 400 - ERR_BAD_REQUEST. Parâmetros em falta.

Regras Gerais

• Content-Length: As requisições devem conter esse header
• Tamanho máximo: Arquivo de até 20MB
• TOKEN: Deve ser válido
• Limite: Máx. 12 requisições por minuto
• Envio de texto: Corpo JSON
• Envio de mídia: Corpo multipart/form-data
• Mensagem: Obrigatória (texto ou mídia)
• Limite de caracteres: Até 2000
• Número: Entre 12 e 13 dígitos
• Contato: Não pode ser grupo
• Arquivos por envio: Até 3
• Histórico: Todas mensagens são registradas
• Legenda: Texto será usado como legenda para mídia