PhotoFlow · Integrações

API de sincronização financeira

Para quem vai ligar um sistema financeiro ao PhotoFlow de um estúdio. Você implementa um endpoint de leitura; o PhotoFlow chama, com a chave que o estúdio cadastrar.

Guia para conectar o seu sistema

Contrato versão 1. Mande o link público para quem cuida do seu sistema: https://usephotoflow.com.br/guia/api-financeira

Como funciona

O seu sistema expõe um endpoint que lista lançamentos.
Você cadastra aqui o endereço e uma chave. A chave fica criptografada e nunca é mostrada de novo.
O PhotoFlow chama o seu sistema. Não é preciso mandar nada para o PhotoFlow nem abrir porta de entrada.
Da primeira vez vem tudo. Depois, só o que mudou desde a última sincronização.

O endpoint

GET {endereço cadastrado}/transactions?since=2026-09-20T12:00:00Z&cursor=abc&limit=500
X-API-Key: <sua chave>          (ou: Authorization: Bearer <sua chave>)
Accept: application/json

since	Opcional. Devolva só o que foi criado ou alterado a partir deste instante (ISO-8601, UTC). Ausente = tudo.
cursor	Opcional. O `next_cursor` da página anterior. Formato livre, o PhotoFlow só devolve o que recebeu.
limit	Até 500 por página.

A resposta

{
  "transactions": [
    {
      "id": "tx_9f2c1",
      "date": "2026-09-20",
      "amount": 2500,
      "description": "Pix recebido — Casamento Ana e Pedro",
      "category": "Receita de serviço",
      "account": "Inter PJ",
      "deleted": false,
      "updated_at": "2026-09-20T13:05:00Z"
    },
    {
      "id": "tx_9f2c2",
      "date": "2026-09-21",
      "amount": -380.9,
      "description": "Aluguel de lente",
      "category": "Equipamento",
      "account": "Inter PJ",
      "deleted": false,
      "updated_at": "2026-09-21T09:00:00Z"
    }
  ],
  "next_cursor": null
}

id	Obrigatório e estável. O mesmo lançamento sempre com o mesmo id: é assim que o PhotoFlow atualiza em vez de duplicar.
date	Obrigatório. `YYYY-MM-DD` (fica no dia certo no fuso de Brasília) ou ISO-8601 completo.
amount	Obrigatório. Positivo = entrada, negativo = saída. Nunca zero.
description	Obrigatório, até 255 caracteres.
category	Opcional. Vazio entra como `A_REVISAR`. Se você recategorizar no PhotoFlow, a sincronização seguinte não desfaz.
account	Opcional. Nome da conta, mostrado entre parênteses na descrição.
deleted	Opcional. `true` remove do PhotoFlow um lançamento que você apagou aí.
updated_at	Recomendado. Última alteração: é o que o seu filtro `since` deve comparar.
next_cursor	`null` na última página.

O que mandar (e o que não mandar)

Mande só o que é operacional do estúdio: receitas e despesas do negócio.
Deixe de fora as transferências entre as suas próprias contas, aplicações e resgates. Senão, o dinheiro que só mudou de lugar aparece como receita e despesa.
Se o sistema mistura conta pessoal com conta da empresa, filtre só a da empresa no endpoint.

Teste antes de cadastrar

curl -H "X-API-Key: SUA_CHAVE" "https://api.seusistema.com.br/photoflow/transactions?limit=5"

Se esse comando devolve o JSON acima, o PhotoFlow consegue ler. Depois use o botão Testar conexão: ele lê uma amostra e não grava nada.

Segurança

Só https. Endereços de rede interna (localhost, 192.168…, 10…) são recusados: o servidor do PhotoFlow não enxerga a sua rede local.
Use uma chave só para o PhotoFlow, somente leitura, com 16 caracteres ou mais. Se vazar, gere outra e cole aqui.
Redirecionamentos são recusados. Cadastre o endereço final.
Se o seu sistema fica atrás de um proxy com login (Cloudflare Access, por exemplo), libere só o caminho /transactions para a chave de API.

Manual ou automático

Manual: o botão Sincronizar agora, quando você quiser.
Automático: o PhotoFlow verifica de hora em hora e sincroniza quando passa o intervalo que você escolheu (1 a 24 h).
Cada rodada fica no histórico acima: quando foi, quantos lançamentos entraram e, se falhou, o motivo.

Chamadas saem de usephotoflow.com.br com o User-Agent PhotoFlow-Sync/1.