Documentação da API · IntegraWhats

Começo rápido

Em Configurações › Desenvolvedores, crie um token e marque as habilidades de que precisa. O token aparece uma única vez.
Faça a primeira chamada para conferir a empresa e o plano do token.
Envie uma mensagem de teste para um número seu.

curl https://integrawhats.app/api/v1/me \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

curl -X POST https://integrawhats.app/api/v1/messages \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999990000","text":"Olá, Maria. Seu pedido saiu para entrega."}'

Autenticação

Cada token pertence a uma empresa e dá acesso só aos dados dela. Envie o token no cabeçalho Authorization, no formato Bearer. Guarde-o no servidor, nunca em código que roda no navegador. Quem perde o acesso a um token pode revogá-lo no painel e o efeito é imediato.

Authorization: Bearer iw_<prefix>_<secret>

Habilidades do token

read: Consultar conversas, contatos, agenda, leads e tickets.
write: Criar e alterar agendamentos e tickets, e resolver conversas.
messages: Enviar mensagens pelo WhatsApp.
orders: Consultar, criar e atualizar pedidos.

Convenções

Endereço base: Todas as rotas começam com o endereço abaixo. Envie Accept: application/json em todas as chamadas.
Identificadores: Os ids são textos públicos e estáveis. Em pedidos, o caminho também aceita o número do pedido na sua loja (external_id).
Telefones: Só os dígitos, com código do país. Número brasileiro com 10 ou 11 dígitos recebe o 55 automaticamente.
Datas: As respostas usam ISO 8601 com fuso. Na agenda, data enviada sem fuso é lida no fuso da empresa.
Valores: Sempre em centavos, como número inteiro: R$ 159,00 é 15900.
Paginação: As listas vêm do mais novo para o mais antigo, em páginas de 50 itens (100 em mensagens e contatos). Para a página seguinte, envie o valor de next_cursor no parâmetro cursor. Quando next_cursor vier null, a lista acabou.
Limite de uso: 120 requisições por minuto por token. Acima disso a resposta é 429, com retry_after em segundos.
Repetir sem duplicar: Nas rotas marcadas, envie o cabeçalho Idempotency-Key com até 100 caracteres. Por 24 horas, repetir a mesma chave com o mesmo corpo devolve a primeira resposta, com o cabeçalho Idempotent-Replayed: true, sem criar nada de novo. Só respostas de sucesso ficam guardadas: depois de um erro de validação, corrija e reenvie com a mesma chave.

Erros

Erros de autenticação, permissão e regra de negócio trazem o campo error com um código estável e message com o texto para pessoas. Erros de validação trazem message e errors, com a lista por campo.

HTTP	Código	Quando acontece
401	unauthenticated	Token ausente, inválido ou revogado.
403	forbidden	A empresa está sem acesso, o plano não inclui a API ou o token não tem a habilidade da rota.
404		O recurso não existe nesta empresa.
404	not_found	O app da rota não está instalado.
409	channel_disconnected	O número usado na conversa está desconectado.
409	idempotency_in_progress	Outra requisição com a mesma Idempotency-Key ainda está em andamento.
409	not_upcoming	Só agendamentos futuros podem ser remarcados.
413	payload_too_large	O pedido passou de 256 KB.
422		Validação: confira o objeto errors.
422	slot_unavailable	O horário pedido não está livre.
422	invalid_idempotency_key	A Idempotency-Key passou de 100 caracteres.
422	idempotency_conflict	A chave já foi usada com outro corpo de requisição.
429	rate_limited	Limite de requisições atingido. Aguarde os segundos de retry_after.

Conta

Empresa do token, plano e uso dos limites.

GET /me Mostra a empresa do token, o plano e o uso de cada limite.

Habilidade: read

Requisição

curl https://integrawhats.app/api/v1/me \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": {
        "workspace": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "name": "Clínica Exemplo",
            "locale": "pt_BR",
            "timezone": "America/Sao_Paulo"
        },
        "plan": "pro",
        "usage": {
            "users": {
                "limit": 10,
                "usage": 4,
                "tracked": true
            }
        }
    }
}

Conversas e mensagens

Consulte o atendimento e envie mensagens de texto. O envio acontece em fila: a resposta 202 confirma o recebimento, e o status final chega pelo webhook message.status.

GET /conversations Lista as conversas.

Habilidade: read

Parâmetros

Campo	Tipo	Descrição
`status`	string	Filtra pela situação. open, resolved
`department`	string	Filtra pelo id do setor.
`phone`	string	Filtra pelo telefone do contato.

Requisição

curl https://integrawhats.app/api/v1/conversations \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": [
        {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "status": "open",
            "channel": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "contact": {
                "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
                "phone": "5511999990000",
                "name": "Maria Silva",
                "push_name": "Maria",
                "created_at": "2026-11-03T10:15:00-03:00"
            },
            "department": {
                "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
                "name": "Comercial"
            },
            "assigned_to": {
                "name": "Ana",
                "email": "ana@exemplo.com"
            },
            "tags": [
                "orçamento"
            ],
            "opened_at": "2026-11-03T10:15:00-03:00",
            "resolved_at": null
        }
    ],
    "next_cursor": "eyJpZCI6MTIwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
}

GET /conversations/{conversation} Mostra uma conversa.

Habilidade: read

Requisição

curl https://integrawhats.app/api/v1/conversations/01JC4Z8N5Q3V7W2K9M6T1R0YHD \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "status": "open",
        "channel": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "department": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "name": "Comercial"
        },
        "assigned_to": {
            "name": "Ana",
            "email": "ana@exemplo.com"
        },
        "tags": [
            "orçamento"
        ],
        "opened_at": "2026-11-03T10:15:00-03:00",
        "resolved_at": null
    }
}

GET /conversations/{conversation}/messages Lista as mensagens de uma conversa, da mais nova para a mais antiga.

Habilidade: read

Requisição

curl https://integrawhats.app/api/v1/conversations/01JC4Z8N5Q3V7W2K9M6T1R0YHD/messages \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": [
        {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "conversation": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "contact": {
                "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
                "phone": "5511999990000",
                "name": "Maria Silva",
                "push_name": "Maria",
                "created_at": "2026-11-03T10:15:00-03:00"
            },
            "direction": "out",
            "type": "text",
            "body": "Olá, Maria. Seu pedido saiu para entrega.",
            "media": null,
            "status": "queued",
            "risk": null,
            "reply_to": null,
            "reactions": [],
            "edited_at": null,
            "revoked_at": null,
            "hold_reason": null,
            "hold_message": null,
            "send_after": null,
            "timestamp": null
        }
    ],
    "next_cursor": "eyJpZCI6MTIwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
}

POST /conversations/{conversation}/resolve Marca a conversa como resolvida.

Habilidade: write

Requisição

curl -X POST https://integrawhats.app/api/v1/conversations/01JC4Z8N5Q3V7W2K9M6T1R0YHD/resolve \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": {
        "status": "resolved",
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "channel": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "department": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "name": "Comercial"
        },
        "assigned_to": {
            "name": "Ana",
            "email": "ana@exemplo.com"
        },
        "tags": [
            "orçamento"
        ],
        "opened_at": "2026-11-03T10:15:00-03:00",
        "resolved_at": null
    }
}

POST /messages Envia um texto para uma conversa ou para um telefone. Com telefone, usa a conversa aberta ou abre uma nova. Informe conversation ou to. A proteção de envio pode segurar uma mensagem fria: nesse caso ela volta com o status held e o motivo em hold_reason e hold_message.

Habilidade: messages Aceita Idempotency-Key

Parâmetros

Campo	Tipo	Descrição
`conversation`	string	Id da conversa. Obrigatório se não houver to.
`to`	string	Telefone de destino. Obrigatório se não houver conversation.
`text` obrigatório	string	Texto da mensagem, até 4096 caracteres.
`channel`	string	Id do número que envia, quando a empresa tem mais de um.
`department`	string	Id do setor.
`origin`	string	Use system para aviso gerado pelo seu sistema, que não é campanha. system

Requisição

curl -X POST https://integrawhats.app/api/v1/messages \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999990000","text":"Olá, Maria. Seu pedido saiu para entrega."}'

Resposta 202

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "conversation": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "direction": "out",
        "type": "text",
        "body": "Olá, Maria. Seu pedido saiu para entrega.",
        "media": null,
        "status": "queued",
        "risk": null,
        "reply_to": null,
        "reactions": [],
        "edited_at": null,
        "revoked_at": null,
        "hold_reason": null,
        "hold_message": null,
        "send_after": null,
        "timestamp": null
    }
}

Contatos

Busca na base de contatos da empresa. Os contatos nascem nas conversas, nos agendamentos e nos pedidos.

GET /contacts Lista os contatos, com busca por nome ou telefone.

Habilidade: read

Parâmetros

Campo	Tipo	Descrição
`search`	string	Parte do nome ou do telefone.

Requisição

curl https://integrawhats.app/api/v1/contacts \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": [
        {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        }
    ],
    "next_cursor": "eyJpZCI6MTIwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
}

Agenda

Consulte horários livres e crie, remarque ou cancele agendamentos, com as mesmas regras do painel e do WhatsApp.

GET /calendars Lista as agendas da empresa.

Habilidade: read

Requisição

curl https://integrawhats.app/api/v1/calendars \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": [
        {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "name": "Consultas",
            "slot_minutes": 30,
            "max_days_ahead": 30,
            "active": true
        }
    ]
}

GET /calendars/{calendar}/slots Lista os horários livres de uma agenda.

Habilidade: read

Parâmetros

Campo	Tipo	Descrição
`date`	date	Primeiro dia, no formato AAAA-MM-DD.
`days`	integer	Quantidade de dias, de 1 a 31. Padrão: 1.

Requisição

curl https://integrawhats.app/api/v1/calendars/01JC4Z8N5Q3V7W2K9M6T1R0YHD/slots \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": [
        "2026-11-10T09:00:00-03:00",
        "2026-11-10T09:30:00-03:00"
    ],
    "timezone": "America/Sao_Paulo"
}

GET /appointments Lista os agendamentos.

Habilidade: read

Parâmetros

Campo	Tipo	Descrição
`calendar`	string	Filtra pelo id da agenda.
`status`	string	Filtra pela situação. scheduled, confirmed, cancelled, done, no_show
`phone`	string	Filtra pelo telefone do contato.
`from`	datetime	Início do período.
`to`	datetime	Fim do período.

Requisição

curl https://integrawhats.app/api/v1/appointments \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": [
        {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "calendar": {
                "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
                "name": "Consultas",
                "slot_minutes": 30,
                "max_days_ahead": 30,
                "active": true
            },
            "contact": {
                "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
                "phone": "5511999990000",
                "name": "Maria Silva",
                "push_name": "Maria",
                "created_at": "2026-11-03T10:15:00-03:00"
            },
            "conversation": null,
            "starts_at": "2026-11-10T09:00:00-03:00",
            "ends_at": "2026-11-10T09:30:00-03:00",
            "status": "scheduled",
            "notes": null,
            "source": "api",
            "created_at": "2026-11-03T10:15:00-03:00"
        }
    ],
    "next_cursor": "eyJpZCI6MTIwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
}

GET /appointments/{appointment} Mostra um agendamento.

Habilidade: read

Requisição

curl https://integrawhats.app/api/v1/appointments/01JC4Z8N5Q3V7W2K9M6T1R0YHD \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "calendar": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "name": "Consultas",
            "slot_minutes": 30,
            "max_days_ahead": 30,
            "active": true
        },
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "conversation": null,
        "starts_at": "2026-11-10T09:00:00-03:00",
        "ends_at": "2026-11-10T09:30:00-03:00",
        "status": "scheduled",
        "notes": null,
        "source": "api",
        "created_at": "2026-11-03T10:15:00-03:00"
    }
}

POST /appointments Cria um agendamento num horário livre. O contato é criado se ainda não existir.

Habilidade: write Aceita Idempotency-Key

Parâmetros

Campo	Tipo	Descrição
`calendar` obrigatório	string	Id da agenda.
`phone` obrigatório	string	Telefone do contato.
`starts_at` obrigatório	datetime	Data e hora do início.
`name`	string	Nome do contato, usado se ele for criado agora.
`notes`	string	Observações, até 2000 caracteres.
`notify`	boolean	Avisa o cliente pelo WhatsApp. Padrão: true.

Requisição

curl -X POST https://integrawhats.app/api/v1/appointments \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"calendar":"01JC4Z8N5Q3V7W2K9M6T1R0YHD","phone":"5511999990000","starts_at":"2026-11-10T09:00:00-03:00","name":"Maria Silva"}'

Resposta 201

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "calendar": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "name": "Consultas",
            "slot_minutes": 30,
            "max_days_ahead": 30,
            "active": true
        },
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "conversation": null,
        "starts_at": "2026-11-10T09:00:00-03:00",
        "ends_at": "2026-11-10T09:30:00-03:00",
        "status": "scheduled",
        "notes": null,
        "source": "api",
        "created_at": "2026-11-03T10:15:00-03:00"
    }
}

POST /appointments/{appointment}/reschedule Remarca um agendamento futuro para outro horário livre.

Habilidade: write Aceita Idempotency-Key

Parâmetros

Campo	Tipo	Descrição
`starts_at` obrigatório	datetime	Data e hora do início.
`notify`	boolean	Avisa o cliente pelo WhatsApp. Padrão: true.

Requisição

curl -X POST https://integrawhats.app/api/v1/appointments/01JC4Z8N5Q3V7W2K9M6T1R0YHD/reschedule \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"starts_at":"2026-11-11T14:00:00-03:00"}'

Resposta 200

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "calendar": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "name": "Consultas",
            "slot_minutes": 30,
            "max_days_ahead": 30,
            "active": true
        },
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "conversation": null,
        "starts_at": "2026-11-10T09:00:00-03:00",
        "ends_at": "2026-11-10T09:30:00-03:00",
        "status": "scheduled",
        "notes": null,
        "source": "api",
        "created_at": "2026-11-03T10:15:00-03:00"
    }
}

POST /appointments/{appointment}/cancel Cancela um agendamento.

Habilidade: write Aceita Idempotency-Key

Parâmetros

Campo	Tipo	Descrição
`notify`	boolean	Avisa o cliente pelo WhatsApp. Padrão: true.

Requisição

curl -X POST https://integrawhats.app/api/v1/appointments/01JC4Z8N5Q3V7W2K9M6T1R0YHD/cancel \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"notify":false}'

Resposta 200

{
    "data": {
        "status": "cancelled",
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "calendar": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "name": "Consultas",
            "slot_minutes": 30,
            "max_days_ahead": 30,
            "active": true
        },
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "conversation": null,
        "starts_at": "2026-11-10T09:00:00-03:00",
        "ends_at": "2026-11-10T09:30:00-03:00",
        "notes": null,
        "source": "api",
        "created_at": "2026-11-03T10:15:00-03:00"
    }
}

Leads do site

Leads recebidos pelos formulários e pelo pop-up de captura. Somente leitura.

Exige o app Formulários ou Captura de leads instalado.

GET /leads Lista os leads do site.

Habilidade: read

Parâmetros

Campo	Tipo	Descrição
`status`	string	Filtra pela situação. new, contacted, converted, discarded
`source`	string	Filtra pela origem. form, popup

Requisição

curl https://integrawhats.app/api/v1/leads \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": [
        {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "source": "form",
            "status": "new",
            "name": "Maria Silva",
            "phone": "5511999990000",
            "email": "maria@exemplo.com",
            "utm_source": "google",
            "utm_medium": "cpc",
            "utm_campaign": "promo-novembro",
            "consent_at": "2026-11-03T10:15:00-03:00",
            "confirmed_at": null,
            "created_at": "2026-11-03T10:15:00-03:00"
        }
    ],
    "next_cursor": "eyJpZCI6MTIwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
}

GET /leads/{lead} Mostra um lead.

Habilidade: read

Requisição

curl https://integrawhats.app/api/v1/leads/01JC4Z8N5Q3V7W2K9M6T1R0YHD \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "source": "form",
        "status": "new",
        "name": "Maria Silva",
        "phone": "5511999990000",
        "email": "maria@exemplo.com",
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "promo-novembro",
        "consent_at": "2026-11-03T10:15:00-03:00",
        "confirmed_at": null,
        "created_at": "2026-11-03T10:15:00-03:00"
    }
}

Pedidos

Envie os pedidos da sua loja para ver o faturamento real de cada campanha.

Exige o app API de pedidos instalado.

GET /orders Lista os pedidos.

Habilidade: orders

Parâmetros

Campo	Tipo	Descrição
`status`	string	Filtra pela situação. pending, paid, shipped, delivered, cancelled, refunded
`source`	string	Filtra pela origem. api, pixel, bio, manual, kori
`phone`	string	Filtra pelo telefone do contato.

Requisição

curl https://integrawhats.app/api/v1/orders \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": [
        {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "external_id": "10231",
            "source_key": "",
            "source": "api",
            "status": "paid",
            "contact": {
                "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
                "phone": "5511999990000",
                "name": "Maria Silva",
                "push_name": "Maria",
                "created_at": "2026-11-03T10:15:00-03:00"
            },
            "customer_name": "Maria Silva",
            "customer_phone": "5511999990000",
            "customer_email": null,
            "currency": "BRL",
            "subtotal_cents": 15900,
            "shipping_cents": 0,
            "discount_cents": 0,
            "total_cents": 15900,
            "placed_at": "2026-11-03T10:15:00-03:00",
            "paid_at": "2026-11-03T10:15:00-03:00",
            "cancelled_at": null,
            "refunded_at": null,
            "confirmed_at": "2026-11-03T10:15:00-03:00",
            "attribution": null,
            "utm_source": null,
            "utm_medium": null,
            "utm_campaign": null,
            "items": [
                {
                    "sku": "CAFE-250",
                    "title": "Café especial 250 g",
                    "quantity": 2,
                    "unit_price_cents": 7950
                }
            ]
        }
    ],
    "next_cursor": "eyJpZCI6MTIwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
}

GET /orders/{order} Mostra um pedido, pelo id ou pelo número na loja.

Habilidade: orders

Requisição

curl https://integrawhats.app/api/v1/orders/01JC4Z8N5Q3V7W2K9M6T1R0YHD \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "external_id": "10231",
        "source_key": "",
        "source": "api",
        "status": "paid",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "customer_name": "Maria Silva",
        "customer_phone": "5511999990000",
        "customer_email": null,
        "currency": "BRL",
        "subtotal_cents": 15900,
        "shipping_cents": 0,
        "discount_cents": 0,
        "total_cents": 15900,
        "placed_at": "2026-11-03T10:15:00-03:00",
        "paid_at": "2026-11-03T10:15:00-03:00",
        "cancelled_at": null,
        "refunded_at": null,
        "confirmed_at": "2026-11-03T10:15:00-03:00",
        "attribution": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_campaign": null,
        "items": [
            {
                "sku": "CAFE-250",
                "title": "Café especial 250 g",
                "quantity": 2,
                "unit_price_cents": 7950
            }
        ]
    }
}

POST /orders Cria o pedido ou atualiza o que já tem o mesmo external_id. A resposta é 201 ao criar e 200 ao atualizar. O campo applied indica se o status enviado foi aceito.

Habilidade: orders Aceita Idempotency-Key

Parâmetros

Campo	Tipo	Descrição
`external_id` obrigatório	string	Número do pedido na sua loja, até 80 caracteres.
`source_key`	string	Identifica a loja quando há mais de uma.
`status`	string	Situação do pedido. pending, paid, shipped, delivered, cancelled, refunded
`status_at`	datetime	Quando a situação mudou.
`currency`	string	Moeda com 3 letras. Exemplo: BRL.
`subtotal_cents`	integer	Valor em centavos.
`shipping_cents`	integer	Valor em centavos.
`discount_cents`	integer	Valor em centavos.
`total_cents`	integer	Valor em centavos.
`customer_name`	string	Nome do comprador.
`customer_phone`	string	Telefone do comprador. Liga o pedido ao contato.
`customer_email`	string	E-mail do comprador.
`placed_at`	datetime	Data do pedido.
`pixel`	string	Código do pixel que atribui o pedido.
`visitor_id`	string	Id do visitante informado pelo pixel.
`gxclid`	string	Id do clique rastreado.
`items`	array	Até 100 itens, cada um com title, quantity e unit_price_cents, e sku opcional.

Requisição

curl -X POST https://integrawhats.app/api/v1/orders \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"10231","status":"paid","total_cents":15900,"customer_name":"Maria Silva","customer_phone":"5511999990000","items":[{"sku":"CAFE-250","title":"Café especial 250 g","quantity":2,"unit_price_cents":7950}]}'

Resposta 201

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "external_id": "10231",
        "source_key": "",
        "source": "api",
        "status": "paid",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "customer_name": "Maria Silva",
        "customer_phone": "5511999990000",
        "customer_email": null,
        "currency": "BRL",
        "subtotal_cents": 15900,
        "shipping_cents": 0,
        "discount_cents": 0,
        "total_cents": 15900,
        "placed_at": "2026-11-03T10:15:00-03:00",
        "paid_at": "2026-11-03T10:15:00-03:00",
        "cancelled_at": null,
        "refunded_at": null,
        "confirmed_at": "2026-11-03T10:15:00-03:00",
        "attribution": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_campaign": null,
        "items": [
            {
                "sku": "CAFE-250",
                "title": "Café especial 250 g",
                "quantity": 2,
                "unit_price_cents": 7950
            }
        ]
    },
    "applied": true
}

POST /orders/{order}/status Muda o status do pedido. Status só avança, e applied volta false quando a mudança não é permitida.

Habilidade: orders Aceita Idempotency-Key

Parâmetros

Campo	Tipo	Descrição
`status` obrigatório	string	Situação do pedido. pending, paid, shipped, delivered, cancelled, refunded
`at`	datetime	Quando a mudança aconteceu.

Requisição

curl -X POST https://integrawhats.app/api/v1/orders/01JC4Z8N5Q3V7W2K9M6T1R0YHD/status \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status":"shipped"}'

Resposta 200

{
    "data": {
        "status": "shipped",
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "external_id": "10231",
        "source_key": "",
        "source": "api",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "customer_name": "Maria Silva",
        "customer_phone": "5511999990000",
        "customer_email": null,
        "currency": "BRL",
        "subtotal_cents": 15900,
        "shipping_cents": 0,
        "discount_cents": 0,
        "total_cents": 15900,
        "placed_at": "2026-11-03T10:15:00-03:00",
        "paid_at": "2026-11-03T10:15:00-03:00",
        "cancelled_at": null,
        "refunded_at": null,
        "confirmed_at": "2026-11-03T10:15:00-03:00",
        "attribution": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_campaign": null,
        "items": [
            {
                "sku": "CAFE-250",
                "title": "Café especial 250 g",
                "quantity": 2,
                "unit_price_cents": 7950
            }
        ]
    },
    "applied": true
}

Tickets

Abra e acompanhe tickets a partir do seu sistema.

Exige o app Tickets instalado.

GET /tickets Lista os tickets.

Habilidade: read

Parâmetros

Campo	Tipo	Descrição
`status`	string	Filtra pela situação. new, in_progress, waiting_customer, waiting_third_party, resolved, closed
`priority`	string	Filtra pela prioridade. low, normal, high, urgent
`phone`	string	Filtra pelo telefone do contato.

Requisição

curl https://integrawhats.app/api/v1/tickets \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": [
        {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "number": 128,
            "subject": "Produto chegou com defeito",
            "description": null,
            "status": "new",
            "priority": "high",
            "source": "api",
            "contact": {
                "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
                "phone": "5511999990000",
                "name": "Maria Silva",
                "push_name": "Maria",
                "created_at": "2026-11-03T10:15:00-03:00"
            },
            "channel": null,
            "category": null,
            "department": null,
            "assigned_to": null,
            "first_response_due_at": "2026-11-03T14:15:00-03:00",
            "resolve_due_at": "2026-11-04T10:15:00-03:00",
            "first_response_at": null,
            "customer_replied_at": null,
            "resolved_at": null,
            "closed_at": null,
            "reopen_count": 0,
            "created_at": "2026-11-03T10:15:00-03:00"
        }
    ],
    "next_cursor": "eyJpZCI6MTIwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
}

GET /tickets/{ticket} Mostra um ticket.

Habilidade: read

Requisição

curl https://integrawhats.app/api/v1/tickets/01JC4Z8N5Q3V7W2K9M6T1R0YHD \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json"

Resposta 200

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "number": 128,
        "subject": "Produto chegou com defeito",
        "description": null,
        "status": "new",
        "priority": "high",
        "source": "api",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "channel": null,
        "category": null,
        "department": null,
        "assigned_to": null,
        "first_response_due_at": "2026-11-03T14:15:00-03:00",
        "resolve_due_at": "2026-11-04T10:15:00-03:00",
        "first_response_at": null,
        "customer_replied_at": null,
        "resolved_at": null,
        "closed_at": null,
        "reopen_count": 0,
        "created_at": "2026-11-03T10:15:00-03:00"
    }
}

POST /tickets Abre um ticket.

Habilidade: write Aceita Idempotency-Key

Parâmetros

Campo	Tipo	Descrição
`subject` obrigatório	string	Assunto, até 200 caracteres.
`description`	string	Descrição, até 8000 caracteres.
`priority`	string	Prioridade. low, normal, high, urgent
`contact`	string	Id do contato.
`phone`	string	Telefone de um contato que já existe.
`conversation`	string	Id da conversa ligada ao ticket.
`category`	string	Nome de uma categoria de tickets.
`department`	string	Id do setor.

Requisição

curl -X POST https://integrawhats.app/api/v1/tickets \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Produto chegou com defeito","phone":"5511999990000","priority":"high"}'

Resposta 201

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "number": 128,
        "subject": "Produto chegou com defeito",
        "description": null,
        "status": "new",
        "priority": "high",
        "source": "api",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "channel": null,
        "category": null,
        "department": null,
        "assigned_to": null,
        "first_response_due_at": "2026-11-03T14:15:00-03:00",
        "resolve_due_at": "2026-11-04T10:15:00-03:00",
        "first_response_at": null,
        "customer_replied_at": null,
        "resolved_at": null,
        "closed_at": null,
        "reopen_count": 0,
        "created_at": "2026-11-03T10:15:00-03:00"
    }
}

POST /tickets/{ticket}/status Muda o status do ticket.

Habilidade: write Aceita Idempotency-Key

Parâmetros

Campo	Tipo	Descrição
`status` obrigatório	string	Situação do ticket. new, in_progress, waiting_customer, waiting_third_party, resolved, closed

Requisição

curl -X POST https://integrawhats.app/api/v1/tickets/01JC4Z8N5Q3V7W2K9M6T1R0YHD/status \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress"}'

Resposta 200

{
    "data": {
        "status": "in_progress",
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "number": 128,
        "subject": "Produto chegou com defeito",
        "description": null,
        "priority": "high",
        "source": "api",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "channel": null,
        "category": null,
        "department": null,
        "assigned_to": null,
        "first_response_due_at": "2026-11-03T14:15:00-03:00",
        "resolve_due_at": "2026-11-04T10:15:00-03:00",
        "first_response_at": null,
        "customer_replied_at": null,
        "resolved_at": null,
        "closed_at": null,
        "reopen_count": 0,
        "created_at": "2026-11-03T10:15:00-03:00"
    }
}

POST /tickets/{ticket}/notes Acrescenta uma nota interna ao ticket.

Habilidade: write Aceita Idempotency-Key

Parâmetros

Campo	Tipo	Descrição
`body` obrigatório	string	Texto da nota, até 4000 caracteres.

Requisição

curl -X POST https://integrawhats.app/api/v1/tickets/01JC4Z8N5Q3V7W2K9M6T1R0YHD/notes \
  -H "Authorization: Bearer $INTEGRA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"body":"Cliente enviou as fotos pelo WhatsApp."}'

Resposta 201

{
    "data": {
        "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
        "number": 128,
        "subject": "Produto chegou com defeito",
        "description": null,
        "status": "new",
        "priority": "high",
        "source": "api",
        "contact": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "phone": "5511999990000",
            "name": "Maria Silva",
            "push_name": "Maria",
            "created_at": "2026-11-03T10:15:00-03:00"
        },
        "channel": null,
        "category": null,
        "department": null,
        "assigned_to": null,
        "first_response_due_at": "2026-11-03T14:15:00-03:00",
        "resolve_due_at": "2026-11-04T10:15:00-03:00",
        "first_response_at": null,
        "customer_replied_at": null,
        "resolved_at": null,
        "closed_at": null,
        "reopen_count": 0,
        "created_at": "2026-11-03T10:15:00-03:00"
    }
}

Webhooks

Cadastre até 10 endereços HTTPS públicos em Configurações › Desenvolvedores e escolha os eventos. A cada evento, enviamos um POST em JSON para o endereço.

Corpo da entrega

O objeto data traz o recurso do evento, no mesmo formato da API, e properties traz detalhes da mudança. Use o id da entrega para ignorar repetições.

{
    "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
    "event": "message.received",
    "created_at": "2026-11-03T10:15:00-03:00",
    "data": {
        "message": {
            "id": "01JC4Z8N5Q3V7W2K9M6T1R0YHD",
            "direction": "in",
            "type": "text",
            "body": "Olá!"
        },
        "properties": []
    }
}

Cabeçalhos

X-Integra-Event: Nome do evento.
X-Integra-Delivery: Id da entrega. Continua o mesmo nas novas tentativas.
X-Integra-Signature: Assinatura no formato t=<unix>,v1=<hex>.

Conferir a assinatura

Calcule o HMAC-SHA256 de "<t>.<corpo>", com o segredo do webhook e o corpo exatamente como chegou, e compare com v1. O segredo começa com whsec_ e aparece uma única vez. Rejeite também um t muito antigo.

PHP

$body = file_get_contents('php://input');
parse_str(strtr($_SERVER['HTTP_X_INTEGRA_SIGNATURE'], ',', '&'), $sig);

$expected = hash_hmac('sha256', $sig['t'].'.'.$body, $secret);
if (! hash_equals($expected, $sig['v1']) || time() - (int) $sig['t'] > 300) {
    http_response_code(400);
    exit;
}

Node.js

import crypto from 'node:crypto';

function isValid(header, rawBody, secret) {
  const sig = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${sig.t}.${rawBody}`).digest('hex');
  const fresh = Date.now() / 1000 - Number(sig.t) < 300;
  return fresh && expected.length === sig.v1.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}

Entrega e novas tentativas

Responda com um status 2xx em até 10 segundos. Se falhar, tentamos de novo depois de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas e 24 horas. Redirecionamentos não são seguidos. Depois de 50 entregas perdidas seguidas, o endereço é desligado e pode ser reativado no painel.

Eventos

Os eventos de tickets, pedidos e negociações só aparecem com o app instalado. Em formulários sensíveis, o evento avisa que houve envio e não traz o conteúdo.

Mensagens: message.received, message.sent, message.status
Conversas: conversation.opened, conversation.assigned, conversation.resolved
Contatos: contact.created, contact.updated, contact.stage_changed
Leads: lead.created
Formulários: form.submitted
Pixel: pixel.event
Pedidos: order.created, order.status_changed, order.paid
Negociações: deal.created, deal.stage_changed, deal.won, deal.lost
Números: channel.status
Agenda: appointment.created, appointment.rescheduled, appointment.cancelled
Tickets: ticket.created, ticket.assigned, ticket.status_changed, ticket.resolved, ticket.sla_breached