Notificações

Envie notificações direcionadas ou para toda a operação. Suporta recorrência diária, semanal e mensal.

Endpoint

POST https://integrations.fhinck.com/insertNotification

Insere ou atualiza uma notificação. Idempotente por notification_id.

Idempotência: a combinação notification_id + key é única por empresa. Reenviar uma notificação com o mesmo ID atualiza a notificação existente em vez de duplicar. Use IDs descritivos e versionados (ex.: ALERTA_FISCAL_2026_001) para permitir correções posteriores sem criar ruído.

Request body

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave criptografada da empresa.
`notification`	object	Sim	Dados da notificação. Ver schema abaixo.
`employees`	string[]	Não	Logins dos destinatários. Se omitido, envia para todos os usuários ativos.

Schema: `notification`

Campo	Tipo	Obrigatório	Descrição
`notification_id`	string	Sim	Identificador único. Recomendado: `PROJETO_001`. Reenviar o mesmo ID atualiza a notificação.
`title`	string	Sim	Título exibido na interface.
`description`	string	Não	Descrição detalhada. Suporta HTML simples.
`recurrency`	boolean	Sim	`true` para notificação recorrente, `false` para disparo único.
`one_time`	string	Se recurrency=false	Data/hora do disparo. Formato `YYYY-MM-DD HH:mm:ss`.
`recurrency_type`	string	Se recurrency=true	`daily`, `weekly` ou `monthly`.
`image`	string	Não	URL de imagem para exibição.
`buttons`	array	Não	Botões de ação customizados. Se omitido, botão "OK" é adicionado automaticamente.

Schema: `buttons[]` (opcional)

Cada botão customizado suporta os seguintes campos:

Campo	Tipo	Descrição
`icon`	string	Nome do ícone a exibir (ex.: `check`, `alert`, `link`).
`text`	string	Texto exibido no botão.
`embedURL`	string	URL aberta ao clicar (suporta deep links).
`iconColor`	string	Cor do ícone em hex. Ex.: `#ff6600`.

Exemplos por linguagem

Disparo único

cURL — disparo único

curl -X POST https://integrations.fhinck.com/insertNotification \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "notification": {
      "notification_id": "AVISO_FATURAMENTO_001",
      "title": "Lembrete: submissão de horas",
      "description": "Envie suas horas trabalhadas até as 18h de hoje.",
      "recurrency": false,
      "one_time": "2026-04-24 18:00:00"
    },
    "employees": ["joao.silva", "maria.souza"]
  }'

JavaScript (fetch)

await fetch('https://integrations.fhinck.com/insertNotification', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: process.env.FHINCK_KEY,
    notification: {
      notification_id: 'AVISO_FATURAMENTO_001',
      title: 'Lembrete: submissão de horas',
      description: 'Envie suas horas trabalhadas até as 18h de hoje.',
      recurrency: false,
      one_time: '2026-04-24 18:00:00',
    },
    employees: ['joao.silva', 'maria.souza'],
  }),
});

Python (requests)

import os, requests

requests.post(
    'https://integrations.fhinck.com/insertNotification',
    json={
        'key': os.environ['FHINCK_KEY'],
        'notification': {
            'notification_id': 'AVISO_FATURAMENTO_001',
            'title': 'Lembrete: submissão de horas',
            'description': 'Envie suas horas trabalhadas até as 18h de hoje.',
            'recurrency': False,
            'one_time': '2026-04-24 18:00:00',
        },
        'employees': ['joao.silva', 'maria.souza'],
    },
    timeout=30,
)

Recorrência semanal

cURL — recorrência semanal

curl -X POST https://integrations.fhinck.com/insertNotification \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "notification": {
      "notification_id": "LEMBRETE_SEMANAL_PONTO",
      "title": "Verificação semanal de ponto",
      "description": "Confira se todas as batidas da semana estão corretas.",
      "recurrency": true,
      "recurrency_type": "weekly"
    }
  }'

JavaScript (fetch)

await fetch('https://integrations.fhinck.com/insertNotification', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: process.env.FHINCK_KEY,
    notification: {
      notification_id: 'LEMBRETE_SEMANAL_PONTO',
      title: 'Verificação semanal de ponto',
      description: 'Confira se todas as batidas da semana estão corretas.',
      recurrency: true,
      recurrency_type: 'weekly',
    },
  }),
});

Python (requests)

import os, requests

requests.post(
    'https://integrations.fhinck.com/insertNotification',
    json={
        'key': os.environ['FHINCK_KEY'],
        'notification': {
            'notification_id': 'LEMBRETE_SEMANAL_PONTO',
            'title': 'Verificação semanal de ponto',
            'description': 'Confira se todas as batidas da semana estão corretas.',
            'recurrency': True,
            'recurrency_type': 'weekly',
        },
    },
    timeout=30,
)

Com botões customizados

Quando você envia o campo buttons, o botão padrão "OK" é substituído pelos customizados. Use embedURL para abrir deep links, landing pages ou fluxos internos.

cURL — com botões customizados

curl -X POST https://integrations.fhinck.com/insertNotification \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "notification": {
      "notification_id": "PESQUISA_ENGAJAMENTO_2026",
      "title": "Pesquisa de engajamento Q2",
      "description": "Sua opinião importa. Leva 3 minutos.",
      "recurrency": false,
      "one_time": "2026-04-25 10:00:00",
      "buttons": [
        {
          "icon": "check",
          "text": "Responder agora",
          "embedURL": "https://forms.empresa.com/engajamento-q2",
          "iconColor": "#ff6600"
        },
        {
          "icon": "clock",
          "text": "Lembrar depois",
          "embedURL": "fhinck://snooze/24h",
          "iconColor": "#64748b"
        }
      ]
    }
  }'

Erros

Status	Mensagem	Causa
400	`Parametro key não informado ou inválido`	Key ausente ou inválida.
422	`Campos obrigatórios ausentes: {campos}`	Campos obrigatórios do objeto `notification` não informados.
422	`Parametro employees deve ser um array`	Campo `employees` com tipo incorreto.
422	`Campo recurrency deve ser boolean`	Tipo de `recurrency` incorreto.
422	`Campo obrigatório ausente: one_time`	`recurrency=false` mas `one_time` não informado.
422	`Campo obrigatório ausente: recurrency_type`	`recurrency=true` mas `recurrency_type` não informado.
500	`Erro interno no servidor`	Falha inesperada.

Todas as chaves do JSON são normalizadas para lowercase automaticamente — notification_ID é tratado como notification_id.

Notificações

Endpoint

Request body

Schema: notification

Schema: buttons[] (opcional)

Exemplos por linguagem

Disparo único

Recorrência semanal

Com botões customizados

Erros

Schema: `notification`

Schema: `buttons[]` (opcional)