API

Leia os dados da sua equipe a partir do seu próprio código, por HTTPS, com respostas em JSON, e receba os eventos dela como webhooks assinados.

Autenticação

Crie uma chave de API nas configurações da sua equipe, em Chaves de API, e envie-a como bearer token. Uma chave pertence a uma equipe, tem escopos, pode expirar e pode ser revogada a qualquer momento. Ela é mostrada só uma vez, então guarde-a num lugar seguro.

curl https://app.farinu.com/api/v1/members \
  -H "Authorization: Bearer $API_KEY"

Endpoints

GET /api/v1/members: Os membros da equipe. Exige uma chave com o escopo read.
GET /api/v1/audit-log: O registro de auditoria da equipe. Exige uma chave com o escopo read, num plano que inclua o registro de auditoria.
POST /api/v1/webhooks/:id/test: Envia um evento de teste para um dos endpoints de webhook da equipe e retorna o ID da entrega. Exige uma chave com o escopo write, num plano que inclua webhooks.
GET /api/v1/assistant/instructions: As instruções da equipe para o assistente, null quando ela não definiu nenhuma. Exige uma chave com o escopo read.

Todos os endpoints, parâmetros e respostas estão descritos no documento OpenAPI 3.1: openapi.json

Paginação

As listas retornam uma página de itens, dos mais antigos aos mais novos, com o cursor para continuar e se há mais itens esperando.

limit: Quantos itens retornar, de 1 a 100. O padrão é 50.
after: O próximo cursor de uma página, para receber os itens seguintes. Continue consultando com o último para receber novos itens conforme chegam.

{ "data": [ … ], "next": "1767225600000.…", "hasMore": true }

Versionamento

A API é versionada por data. Envie um cabeçalho API-Version para fixar uma; sem ele, você recebe a versão atual. Toda resposta informa a versão dela em API-Version, e uma versão desconhecida retorna 400.

Mudanças que podem quebrar seu código (remover ou renomear um campo, mudar um tipo ou um erro) saem com uma nova data. Adições, como novos campos, endpoints ou eventos, chegam a todas as versões. Uma versão antiga continua funcionando por pelo menos 12 meses depois que uma mais nova é lançada.

curl https://app.farinu.com/api/v1/members \
  -H "Authorization: Bearer $API_KEY" \
  -H "API-Version: 2026-10-06"

Idempotência

Envie um cabeçalho Idempotency-Key (até 255 caracteres imprimíveis, como um UUID) com um POST para repeti-lo com segurança. Por 24 horas, a mesma chave e a mesma solicitação retornam de novo a primeira resposta, com Idempotent-Replayed: true, sem executá-la duas vezes; a mesma chave com outra solicitação retorna 422, e uma enviada enquanto a primeira ainda está em execução retorna 409.

curl -X POST https://app.farinu.com/api/v1/webhooks/$ENDPOINT_ID/test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Webhooks

Proprietários e administradores adicionam endpoints HTTPS nas configurações da equipe, em Webhooks, e escolhem os eventos a enviar. Cada evento é um POST de JSON com o tipo, a hora e os dados, assinado no padrão Standard Webhooks. Responda com qualquer 2xx em até 15 segundos; qualquer outra resposta é repetida depois de 1, 5, 25, 125 e 625 minutos, e um endpoint cujas entregas continuam falhando é desativado e os administradores dele recebem um e-mail.

POST /your/endpoint
webhook-id: whd_…
webhook-timestamp: 1767225600
webhook-signature: v1,…

{ "type": "member.added", "timestamp": "2026-01-01T00:00:00.000Z", "data": { "orgId": "…", "memberId": "…", "userId": "…", "role": "member" } }

Para verificar uma solicitação, calcule o HMAC-SHA256 em base64 de webhook-id, webhook-timestamp e do corpo bruto unidos por pontos, usando como chave os bytes do segredo depois de whsec_ (base64), e compare-o em tempo constante com o valor depois de v1, em webhook-signature. Recuse um timestamp com mais de 5 minutos de diferença e ignore um webhook-id que você já tratou.

Eventos: member.added, member.removed, subscription.changed, file.uploaded e webhook.test, além dos do próprio produto. O documento OpenAPI descreve cada corpo.

Erros

Um erro retorna o código de status e um corpo JSON com um código para verificar e uma mensagem para mostrar.

{ "error": { "code": "forbidden", "message": "…" } }

400 badRequest: Um parâmetro de consulta é inválido.
401 unauthorized: A chave está faltando, está errada, foi revogada ou expirou.
402 upgradeRequired: O plano da equipe não inclui a API ou este endpoint.
403 forbidden: A chave não tem o escopo que este endpoint exige.
409 conflict: O recurso está num estado que não permite isso, ou uma solicitação com a mesma Idempotency-Key ainda está em execução.
422 idempotencyMismatch: A Idempotency-Key já foi usada em outra solicitação.
429 rateLimited: Muitas solicitações. Cada chave pode fazer 100 por minuto; espere os segundos indicados no cabeçalho Retry-After.