Documentação da API de Suporte

Bem-vindo à documentação da API de Suporte do Audit. Aqui você encontrará todos os detalhes necessários para integrar e consultar dados de contatos e mensagens das suas instâncias de WhatsApp.

Visão Geral

Nossa API segue os princípios REST. Retornamos respostas em formato JSON e utilizamos códigos de status HTTP padrão para indicar o sucesso ou falha das requisições.

URL Base: https://audit.fcati.com.br/api/v1

Autenticação

Para autenticar suas requisições, você deve enviar seu Token de API no cabeçalho Authorization como um Bearer Token.

            Authorization: Bearer {seu_token_aqui}
        

Gestão de Contatos

GET Listar Contatos com Interação com o Atendente

Retorna uma lista paginada de contatos que trocaram mensagens com o atendente em uma instância específica durante o período informado. Útil para identificar clientes ativos, gerar relatórios de atendimento e analisar o volume de interações por contato. A busca pode ser feita pelo instance_id ou pelo instance_phone cadastrado na instância.

Endpoint

                    GET /api/v1/contacts/interactions
                

Parâmetros de Query

Campo	Tipo	Obrigatório	Descrição
instance_id	integer	*	ID numérico da instância. Obrigatório se `instance_phone` não for informado.
instance_phone	string	*	Telefone da instância. Obrigatório se `instance_id` não for informado. Deve estar cadastrado na instância.
retroactive_days	integer	✓	Quantidade de dias retroativos para o período de busca. Limite máximo: 30 dias.
page	integer	✓	Número da página para paginação. Começa em `1`.
per_page	integer	-	Quantidade de registros por página. Padrão: `20`. Máximo: `100`. (Opcional)

* Ao menos um entre instance_id e instance_phone deve ser informado.

Exemplo de Requisição (cURL / Postman)

                    curl "https://audit.fcati.com.br/api/v1/contacts/interactions?instance_phone=5511988776655&retroactive_days=30&page=1&per_page=20" \
                    -H "Authorization: Bearer {TOKEN}"
                

200 OK Response

                    {
                        "success": true,
                        "message": "Contatos com interação recuperados com sucesso.",
                        "data": {
                            "instance_id": 12345,
                            "instance_phone": "5511988776655",
                            "contacts": [
                                {
                                    "contact_id": 1024,
                                    "name": "Maria Souza",
                                    "phone": "5511999887766",
                                    "email": "maria@email.com",
                                    "total_messages": 87,
                                    "last_message_at": "2026-05-17T14:30:05Z"
                                },
                                {
                                    "contact_id": 1025,
                                    "name": "João Pereira",
                                    "phone": "5521988776655",
                                    "email": null,
                                    "total_messages": 32,
                                    "last_message_at": "2026-05-18T09:12:44Z"
                                }
                            ],
                            "pagination": {
                                "current_page": 1,
                                "per_page": 20,
                                "records": 243,
                                "total_pages": 13
                            }
                        }
                    }
                

401 Não Autorizado

                    {
                        "success": false,
                        "message": "Token de autenticação inválido ou expirado.",
                        "error_code": "UNAUTHORIZED"
                    }
                

422 Erro de Validação

                    {
                        "success": false,
                        "message": "Erro de validação.",
                        "error_code": "ERROR_VALIDATION",

                        "errors": {
                            "retroactive_days": ["O campo retroactive_days é obrigatório."],
                            "instance_id": ["Informe ao menos instance_id ou instance_phone."]
                        }
                    }
                

GET Listar Todos os Contatos da Empresa

Retorna uma lista paginada de todos os contatos da empresa autenticada. Não é necessário informar uma instância. Filtros opcionais permitem localizar um contato pelo phone (aceita com ou sem código de país, e ignora caracteres não numéricos) ou pelo contact_id.

Endpoint

                    GET /api/v1/contacts
                

Parâmetros de Query (opcionais)

Campo	Tipo	Descrição
phone	string	Telefone do contato. Aceita `5511912345678` (com DDI) ou `11912345678` (sem DDI). Caracteres não numéricos (hífens, espaços) são ignorados automaticamente. Mínimo 8 dígitos.
contact_id	integer	ID exato do contato.
page	integer	Página da listagem. Padrão: `1`.
per_page	integer	Registros por página. Padrão: `20`. Máximo: `100`.

Exemplos de Requisição (cURL / Postman)

                    # Todos os contatos (sem filtro)
                    curl "https://audit.fcati.com.br/api/v1/contacts?page=1&per_page=20" \
                    -H "Authorization: Bearer {TOKEN}"

                    # Filtrar por telefone com DDI
                    curl "https://audit.fcati.com.br/api/v1/contacts?phone=5511912345678" \
                    -H "Authorization: Bearer {TOKEN}"

                    # Filtrar por telefone sem DDI (equivalente ao acima)
                    curl "https://audit.fcati.com.br/api/v1/contacts?phone=11912345678" \
                    -H "Authorization: Bearer {TOKEN}"

                    # Filtrar por contact_id
                    curl "https://audit.fcati.com.br/api/v1/contacts?contact_id=1024" \
                    -H "Authorization: Bearer {TOKEN}"
                

200 OK Response

                    {
                        "success": true,
                        "message": "Contatos recuperados com sucesso.",
                        "data": {
                            "contacts": [
                                {
                                    "id": 1024,
                                    "name": "Maria Souza",
                                    "phone": "5511999887766",
                                    "email": "maria@email.com",
                                    "last_message_at": "2026-05-17T14:30:05Z",
                                    "total_messages": 87,
                                    "created_at": "2026-03-10T08:15:30Z"
                                },
                                {
                                    "id": 1025,
                                    "name": "João Pereira",
                                    "phone": "5521988776655",
                                    "email": null,
                                    "last_message_at": "2026-05-18T09:12:44Z",
                                    "total_messages": 32,
                                    "created_at": "2026-04-22T11:45:10Z"
                                }
                            ],
                            "pagination": {
                                "current_page": 1,
                                "per_page": 20,
                                "records": 58,
                                "total_pages": 3
                            }
                        }
                    }
                

401 Não Autorizado

                    {
                        "success": false,
                        "message": "Token de autenticação inválido ou expirado.",
                        "error_code": "UNAUTHORIZED"
                    }
                

422 Erro de Validação

                    {
                        "success": false,
                        "message": "Erro de validação.",
                        "error_code": "ERROR_VALIDATION",
                        "errors": {
                            "phone": ["O campo phone deve ter pelo menos 8 caracteres."],
                            "per_page": ["O campo per_page não pode ser superior a 100."]
                        }
                    }
                

Gestão de Mensagens

GET Listar Mensagens por Instância

Retorna as mensagens de uma instância com filtros obrigatórios. Utilize este endpoint para consultar o histórico de conversas enviando os parâmetros como query string.

Atenção: O campo instance_phone precisa estar previamente configurado no cadastro da instância dentro do dashboard para que a busca por telefone funcione corretamente.

Endpoint

                    GET /api/v1/messages/search
                

Parâmetros de Query

Campo	Tipo	Obrigatório	Descrição
instance_phone	string	✓	Telefone da instância. Deve estar cadastrado na instância.
contact_phone	string	✓	Telefone do contato (com DDI). Ex: `5511999887766`
retroactive_days	integer	✓	Quantidade de dias retroativos para busca. Limite máximo: 30 dias.
page	integer	✓	Número da página para paginação. Começa em `1`
per_page	integer	✓	Quantidade de registros por página. Máximo: `100`
order	string	-	Ordenação das mensagens (por data). Valores: `asc` ou `desc`. Padrão: `desc`. (Opcional)

Exemplo de Requisição (cURL / Postman)

                    curl "https://audit.fcati.com.br/api/v1/messages/search?contact_phone=5511999887766&instance_phone=5511988776655&retroactive_days=30&page=1&per_page=20&order=desc" \
                    -H "Authorization: Bearer {TOKEN}"
                

200 OK Response

                    {
                        "success": true,
                        "message": "Mensagens recuperadas com sucesso.",
                        "data": {
                            "instance_phone": "5511988776655",
                            "contact_phone": "5511999887766",
                            "contact_name": "Maria Souza",
                            "period": {
                                "retroactive_days": 30
                            },
                            "messages": [
                                {
                                    "id": 48201,
                                    "direction": "incoming",
                                    "type": "text",
                                    "message": "Olá, gostaria de saber sobre o plano mensal.",
                                    "timestamp": "2026-05-17T14:23:11Z",
                                    "status": "read"
                                },
                                {
                                    "id": 48202,
                                    "direction": "outgoing",
                                    "type": "text",
                                    "message": "Olá Maria! Temos o plano mensal por R$49,90. Posso te enviar mais detalhes?",
                                    "timestamp": "2026-05-17T14:25:42Z",
                                    "status": "delivered"
                                },
                                {
                                    "id": 48203,
                                    "direction": "incoming",
                                    "type": "image",
                                    "message": null,
                                    "media_url": "https://storage.audit.fcati.com.br/media/img_20260517.jpg",
                                    "timestamp": "2026-05-17T14:30:05Z",
                                    "status": "read"
                                }
                            ],
                            "pagination": {
                                "current_page": 1,
                                "per_page": 20,
                                "records": 87,
                                "total_pages": 5
                            }
                        }
                    }
                

422 Erro de Validação

                    {
                        "success": false,
                        "message": "Erro de validação.",
                        "error_code": "ERROR_VALIDATION",
                        "errors": {
                            "contact_phone": ["O campo contact_phone é obrigatório."],
                            "retroactive_days": ["O campo retroactive_days é obrigatório."]
                        }
                    }
                