Documentación de la API

Inicio rápido

En Configuración › Desarrolladores, crea un token y marca las habilidades que necesitas. El token aparece una sola vez.
Haz la primera llamada para confirmar la empresa y el plan del token.
Envía un mensaje de prueba a un número tuyo.

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

Autenticación

Cada token pertenece a una empresa y solo accede a sus datos. Envíalo en el encabezado Authorization, con el formato Bearer. Guárdalo en el servidor, nunca en código que corre en el navegador. Puedes revocar un token en el panel y deja de funcionar de inmediato.

Authorization: Bearer iw_<prefix>_<secret>

Habilidades del token

read: Consultar conversaciones, contactos, agenda, leads y tickets.
write: Crear y cambiar citas y tickets, y resolver conversaciones.
messages: Enviar mensajes por WhatsApp.
orders: Consultar, crear y actualizar pedidos.

Convenciones

Dirección base: Todas las rutas empiezan con la dirección de abajo. Envía Accept: application/json en todas las llamadas.
Identificadores: Los ids son textos públicos y estables. En pedidos, la ruta también acepta el número del pedido en tu tienda (external_id).
Teléfonos: Solo dígitos, con código de país. Un número brasileño de 10 u 11 dígitos recibe el 55 automáticamente.
Fechas: Las respuestas usan ISO 8601 con zona horaria. En la agenda, una fecha sin zona horaria se lee en la zona de la empresa.
Valores: Siempre en centavos, como número entero: R$ 159,00 es 15900.
Paginación: Las listas van de lo más nuevo a lo más antiguo, en páginas de 50 ítems (100 en mensajes y contactos). Para la página siguiente, envía el valor de next_cursor en el parámetro cursor. Cuando next_cursor llega null, la lista terminó.
Límite de uso: 120 solicitudes por minuto por token. Por encima de eso la respuesta es 429, con retry_after en segundos.
Repetir sin duplicar: En las rutas marcadas, envía el encabezado Idempotency-Key con hasta 100 caracteres. Durante 24 horas, repetir la misma clave con el mismo cuerpo devuelve la primera respuesta, con el encabezado Idempotent-Replayed: true, sin crear nada nuevo. Solo se guardan las respuestas exitosas: tras un error de validación, corrige y reenvía con la misma clave.

Errores

Los errores de autenticación, permiso y regla de negocio traen el campo error con un código estable y message con el texto para personas. Los errores de validación traen message y errors, con la lista por campo.

HTTP	Código	Cuándo ocurre
401	unauthenticated	Token ausente, inválido o revocado.
403	forbidden	La empresa no tiene acceso, el plan no incluye la API o el token no tiene la habilidad de la ruta.
404		El recurso no existe en esta empresa.
404	not_found	La app de la ruta no está instalada.
409	channel_disconnected	El número usado en la conversación está desconectado.
409	idempotency_in_progress	Otra solicitud con la misma Idempotency-Key sigue en curso.
409	not_upcoming	Solo las citas futuras se pueden reprogramar.
413	payload_too_large	El pedido supera los 256 KB.
422		Validación: revisa el objeto errors.
422	slot_unavailable	El horario pedido no está libre.
422	invalid_idempotency_key	La Idempotency-Key supera los 100 caracteres.
422	idempotency_conflict	La clave ya se usó con otro cuerpo de solicitud.
429	rate_limited	Límite de solicitudes alcanzado. Espera los segundos de retry_after.

Cuenta

Empresa del token, plan y uso de los límites.

GET /me Muestra la empresa del token, el plan y el uso de cada límite.

Habilidad: read

Solicitud

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

Respuesta 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
            }
        }
    }
}

Conversaciones y mensajes

Consulta la atención y envía mensajes de texto. El envío va en cola: la respuesta 202 confirma la recepción, y el estado final llega por el webhook message.status.

GET /conversations Lista las conversaciones.

Habilidad: read

Parámetros

Campo	Tipo	Descripción
`status`	string	Filtra por estado. open, resolved
`department`	string	Filtra por id del sector.
`phone`	string	Filtra por teléfono del contacto.

Solicitud

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

Respuesta 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} Muestra una conversación.

Habilidad: read

Solicitud

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

Respuesta 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 los mensajes de una conversación, del más nuevo al más antiguo.

Habilidad: read

Solicitud

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

Respuesta 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 la conversación como resuelta.

Habilidad: write

Solicitud

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

Respuesta 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 Envía un texto a una conversación o a un teléfono. Con teléfono, usa la conversación abierta o abre una nueva. Indica conversation o to. La protección de envío puede retener un mensaje en frío: en ese caso vuelve con el estado held y el motivo en hold_reason y hold_message.

Habilidad: messages Acepta Idempotency-Key

Parámetros

Campo	Tipo	Descripción
`conversation`	string	Id de la conversación. Obligatorio si no hay to.
`to`	string	Teléfono de destino. Obligatorio si no hay conversation.
`text` obligatorio	string	Texto del mensaje, hasta 4096 caracteres.
`channel`	string	Id del número que envía, cuando la empresa tiene más de uno.
`department`	string	Id del sector.
`origin`	string	Usa system para un aviso generado por tu sistema, que no es campaña. system

Solicitud

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

Respuesta 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
    }
}

Contactos

Búsqueda en la base de contactos de la empresa. Los contactos nacen en las conversaciones, las citas y los pedidos.

GET /contacts Lista los contactos, con búsqueda por nombre o teléfono.

Habilidad: read

Parámetros

Campo	Tipo	Descripción
`search`	string	Parte del nombre o del teléfono.

Solicitud

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

Respuesta 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

Consulta horarios libres y crea, reprograma o cancela citas, con las mismas reglas del panel y de WhatsApp.

GET /calendars Lista las agendas de la empresa.

Habilidad: read

Solicitud

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

Respuesta 200

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

GET /calendars/{calendar}/slots Lista los horarios libres de una agenda.

Habilidad: read

Parámetros

Campo	Tipo	Descripción
`date`	date	Primer día, en formato AAAA-MM-DD.
`days`	integer	Cantidad de días, de 1 a 31. Predeterminado: 1.

Solicitud

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

Respuesta 200

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

GET /appointments Lista las citas.

Habilidad: read

Parámetros

Campo	Tipo	Descripción
`calendar`	string	Filtra por id de la agenda.
`status`	string	Filtra por estado. scheduled, confirmed, cancelled, done, no_show
`phone`	string	Filtra por teléfono del contacto.
`from`	datetime	Inicio del período.
`to`	datetime	Fin del período.

Solicitud

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

Respuesta 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} Muestra una cita.

Habilidad: read

Solicitud

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

Respuesta 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 Crea una cita en un horario libre. El contacto se crea si aún no existe.

Habilidad: write Acepta Idempotency-Key

Parámetros

Campo	Tipo	Descripción
`calendar` obligatorio	string	Id de la agenda.
`phone` obligatorio	string	Teléfono del contacto.
`starts_at` obligatorio	datetime	Fecha y hora de inicio.
`name`	string	Nombre del contacto, usado si se crea ahora.
`notes`	string	Observaciones, hasta 2000 caracteres.
`notify`	boolean	Avisa al cliente por WhatsApp. Predeterminado: true.

Solicitud

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"}'

Respuesta 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 Reprograma una cita futura a otro horario libre.

Habilidad: write Acepta Idempotency-Key

Parámetros

Campo	Tipo	Descripción
`starts_at` obligatorio	datetime	Fecha y hora de inicio.
`notify`	boolean	Avisa al cliente por WhatsApp. Predeterminado: true.

Solicitud

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"}'

Respuesta 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 una cita.

Habilidad: write Acepta Idempotency-Key

Parámetros

Campo	Tipo	Descripción
`notify`	boolean	Avisa al cliente por WhatsApp. Predeterminado: true.

Solicitud

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}'

Respuesta 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 del sitio

Leads recibidos por los formularios y el pop-up de captura. Solo lectura.

Requiere la app Formularios o Captura de leads.

GET /leads Lista los leads del sitio.

Habilidad: read

Parámetros

Campo	Tipo	Descripción
`status`	string	Filtra por estado. new, contacted, converted, discarded
`source`	string	Filtra por origen. form, popup

Solicitud

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

Respuesta 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} Muestra un lead.

Habilidad: read

Solicitud

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

Respuesta 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

Envía los pedidos de tu tienda para ver la facturación real de cada campaña.

Requiere la app API de pedidos.

GET /orders Lista los pedidos.

Habilidad: orders

Parámetros

Campo	Tipo	Descripción
`status`	string	Filtra por estado. pending, paid, shipped, delivered, cancelled, refunded
`source`	string	Filtra por origen. api, pixel, bio, manual, kori
`phone`	string	Filtra por teléfono del contacto.

Solicitud

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

Respuesta 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} Muestra un pedido, por id o por número en la tienda.

Habilidad: orders

Solicitud

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

Respuesta 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 Crea el pedido o actualiza el que ya tiene el mismo external_id. La respuesta es 201 al crear y 200 al actualizar. El campo applied indica si se aceptó el estado enviado.

Habilidad: orders Acepta Idempotency-Key

Parámetros

Campo	Tipo	Descripción
`external_id` obligatorio	string	Número del pedido en tu tienda, hasta 80 caracteres.
`source_key`	string	Identifica la tienda cuando hay más de una.
`status`	string	Estado del pedido. pending, paid, shipped, delivered, cancelled, refunded
`status_at`	datetime	Cuándo cambió el estado.
`currency`	string	Moneda de 3 letras. Ejemplo: BRL.
`subtotal_cents`	integer	Valor en centavos.
`shipping_cents`	integer	Valor en centavos.
`discount_cents`	integer	Valor en centavos.
`total_cents`	integer	Valor en centavos.
`customer_name`	string	Nombre del comprador.
`customer_phone`	string	Teléfono del comprador. Vincula el pedido al contacto.
`customer_email`	string	Correo del comprador.
`placed_at`	datetime	Fecha del pedido.
`pixel`	string	Código del píxel que atribuye el pedido.
`visitor_id`	string	Id del visitante informado por el píxel.
`gxclid`	string	Id del clic rastreado.
`items`	array	Hasta 100 ítems, cada uno con title, quantity y unit_price_cents, y sku opcional.

Solicitud

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}]}'

Respuesta 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 Cambia el estado del pedido. El estado solo avanza, y applied vuelve false cuando el cambio no está permitido.

Habilidad: orders Acepta Idempotency-Key

Parámetros

Campo	Tipo	Descripción
`status` obligatorio	string	Estado del pedido. pending, paid, shipped, delivered, cancelled, refunded
`at`	datetime	Cuándo ocurrió el cambio.

Solicitud

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"}'

Respuesta 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

Abre y sigue tickets desde tu sistema.

Requiere la app Tickets.

GET /tickets Lista los tickets.

Habilidad: read

Parámetros

Campo	Tipo	Descripción
`status`	string	Filtra por estado. new, in_progress, waiting_customer, waiting_third_party, resolved, closed
`priority`	string	Filtra por prioridad. low, normal, high, urgent
`phone`	string	Filtra por teléfono del contacto.

Solicitud

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

Respuesta 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} Muestra un ticket.

Habilidad: read

Solicitud

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

Respuesta 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 un ticket.

Habilidad: write Acepta Idempotency-Key

Parámetros

Campo	Tipo	Descripción
`subject` obligatorio	string	Asunto, hasta 200 caracteres.
`description`	string	Descripción, hasta 8000 caracteres.
`priority`	string	Prioridad. low, normal, high, urgent
`contact`	string	Id del contacto.
`phone`	string	Teléfono de un contacto que ya existe.
`conversation`	string	Id de la conversación vinculada al ticket.
`category`	string	Nombre de una categoría de tickets.
`department`	string	Id del sector.

Solicitud

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"}'

Respuesta 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 Cambia el estado del ticket.

Habilidad: write Acepta Idempotency-Key

Parámetros

Campo	Tipo	Descripción
`status` obligatorio	string	Estado del ticket. new, in_progress, waiting_customer, waiting_third_party, resolved, closed

Solicitud

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"}'

Respuesta 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 Agrega una nota interna al ticket.

Habilidad: write Acepta Idempotency-Key

Parámetros

Campo	Tipo	Descripción
`body` obligatorio	string	Texto de la nota, hasta 4000 caracteres.

Solicitud

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

Respuesta 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

Registra hasta 10 direcciones HTTPS públicas en Configuración › Desarrolladores y elige los eventos. Por cada evento, enviamos un POST en JSON a la dirección.

Cuerpo de la entrega

El objeto data trae el recurso del evento, en el mismo formato de la API, y properties trae detalles del cambio. Usa el id de la entrega para ignorar repeticiones.

{
    "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": []
    }
}

Encabezados

X-Integra-Event: Nombre del evento.
X-Integra-Delivery: Id de la entrega. Sigue igual en los reintentos.
X-Integra-Signature: Firma en el formato t=<unix>,v1=<hex>.

Verificar la firma

Calcula el HMAC-SHA256 de "<t>.<cuerpo>", con el secreto del webhook y el cuerpo tal como llegó, y compáralo con v1. El secreto empieza con whsec_ y aparece una sola vez. Rechaza también un t muy antiguo.

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 y reintentos

Responde con un estado 2xx en hasta 10 segundos. Si falla, reintentamos después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 24 horas. Las redirecciones no se siguen. Tras 50 entregas perdidas seguidas, la dirección se desactiva y se puede reactivar en el panel.

Eventos

Los eventos de tickets, pedidos y negociaciones solo aparecen con la app instalada. En formularios sensibles, el evento avisa que hubo un envío y no trae el contenido.

Mensajes: message.received, message.sent, message.status
Conversaciones: conversation.opened, conversation.assigned, conversation.resolved
Contactos: contact.created, contact.updated, contact.stage_changed
Leads: lead.created
Formularios: form.submitted
Píxel: pixel.event
Pedidos: order.created, order.status_changed, order.paid
Negociaciones: 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