Autenticação

Como autenticar requisições na API de Integração Fhinck usando o campo key.

Visão geral

Todos os endpoints de integração utilizam autenticação por chave criptografada no corpo da requisição. Não há header de Authorization e não há exceções — o campo key é enviado diretamente no body JSON em toda chamada.

Como funciona

O processo de autenticação ocorre em três etapas no servidor:

1. O campo key é lido do body da requisição.
2. A chave identifica sua empresa nos sistemas Fhinck.
3. A validação ocorre em milissegundos via algoritmo criptográfico padrão e identifica a empresa (company) usada em todos os dados da operação.

Como obter a chave

A key de integração é gerada pelo time de infraestrutura Fhinck e entregue ao responsável técnico da empresa durante o processo de onboarding. Cada empresa recebe uma chave única. Para solicitar ou renovar sua chave, entre em contato em contato@fhinck.com.

Teste sua chave

Use o endpoint /integrationValidatorData para confirmar se a chave está funcional antes de integrar qualquer fluxo de produção. É útil como ferramenta de diagnóstico inicial e para validar que a chave não foi corrompida durante a transmissão.

Exemplos por linguagem

curl -X POST https://integrations.fhinck.com/integrationValidatorData \
  -H "Content-Type: application/json" \
  -d '{ "key": "SUA_CHAVE_DE_INTEGRACAO" }'

const res = await fetch('https://integrations.fhinck.com/integrationValidatorData', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: process.env.FHINCK_KEY }),
});

const data = await res.json();
if (data.err) {
  throw new Error('Chave inválida: ' + data.message);
}
console.log('Chave válida — empresa autenticada');

import os, requests

resp = requests.post(
    'https://integrations.fhinck.com/integrationValidatorData',
    json={'key': os.environ['FHINCK_KEY']},
    timeout=30,
)
body = resp.json()
if body.get('err'):
    raise RuntimeError('Chave inválida: ' + body['message'])
print('Chave válida — empresa autenticada')

Erros de autenticação

Quando a autenticação falha, a API retorna sempre HTTP 400 (key ausente ou formato inválido) ou 401 (key não descriptografável):

Shape de resposta de erro

{
  "err": true,
  "message": "Parametro key não informado ou inválido"
}

Boas práticas

• Armazene a key em variáveis de ambiente — nunca em código-fonte.
• Não transmita a key via query string ou header customizado.
• Verifique se a key não foi truncada ou re-codificada (ex.: encoding duplo de base64).
• Use HTTPS em todas as requisições — o endpoint integrations.fhinck.com exige TLS.