Documentacao para desenvolvedores

Use esta pagina para integrar sistemas externos com o HubNotas. O contrato atual cobre autenticacao por token, cadastro do sistema cliente, envio de imagem, foto ou PDF de notas e retorno dos dados extraidos.

Visao geral

Base local sugerida para desenvolvimento:

https://hubnotas.brunoalves.dev.br/api/v1

Todas as rotas protegidas usam Bearer Token. Cada usuario possui seus sistemas clientes e suas notas. O usuario pode escolher Gemini ou OpenAI/ChatGPT e deve cadastrar a propria chave do provedor escolhido. O HubNotas usa sempre a chave do usuario autenticado pelo token.

Autenticacao

Envie estes headers nas chamadas protegidas:

Authorization: Bearer SEU_TOKEN
Accept: application/json

Para requests JSON, inclua tambem:

Content-Type: application/json

Tokens Bearer

O usuario pode gerar e remover tokens pelo painel web. O valor completo do token aparece apenas no momento da criacao; se ele for perdido, gere um novo token e remova o antigo.

Authorization: Bearer TOKEN_DO_USUARIO

Quando um token e removido, sistemas externos que usam esse Bearer deixam de autenticar imediatamente.

Cadastro e login

POST/api/v1/auth/register

curl -X POST https://hubnotas.brunoalves.dev.br/api/v1/auth/register \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Empresa Cliente",
    "email": "financeiro@empresa.test",
    "password": "password123",
    "device_name": "sistema-financeiro",
    "ai_provider": "gemini",
    "gemini_api_key": "sua-chave-gemini",
    "openai_api_key": null
  }'

Resposta

{
  "user": {
    "id": 1,
    "name": "Empresa Cliente",
    "email": "financeiro@empresa.test"
  },
  "token": "1|TOKEN_GERADO",
  "token_type": "Bearer"
}

POST/api/v1/auth/login

Use quando a conta ja existir e voce precisar gerar um novo token.

Sistemas clientes

Cadastre cada sistema que vai enviar notas, como um ERP, plataforma financeira, sistema de compras ou aplicacao propria. Isso pode ser feito pelo painel web ou pela API. O ID retornado deve ser usado no campo system_id ao enviar notas.

O system_id identifica a origem da nota dentro da conta do usuario. Ele tambem ajuda a separar notas de varios sistemas usando o mesmo token.

POST/api/v1/systems

curl -X POST https://hubnotas.brunoalves.dev.br/api/v1/systems \
  -H "Accept: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sistema Financeiro",
    "slug": "sistema-financeiro",
    "callback_url": "https://empresa.test/webhooks/notas"
  }'

Campo	Obrigatorio	Descricao
`name`	Sim	Nome do sistema cliente.
`slug`	Nao	Identificador curto unico por usuario.
`callback_url`	Nao	URL futura para notificacoes/webhooks.

Remover sistema cliente

DELETE/api/v1/systems/{system}

Remove o sistema cliente da conta autenticada. As notas vinculadas e seus arquivos armazenados tambem sao removidos.

Notas fiscais

O endpoint aceita imagem, foto, PDF ou XML da nota por multipart form-data. Quando a IA estiver configurada, a resposta ja traz os campos extraidos.

POST/api/v1/invoices

curl -X POST https://hubnotas.brunoalves.dev.br/api/v1/invoices \
  -H "Accept: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "system_id": 1,
    "external_id": "NF-001",
    "issuer_name": "Fornecedor Teste LTDA",
    "document_number": "12345",
    "issued_at": "2026-08-24",
    "total_amount": 199.90,
    "currency": "BRL",
    "category": "servicos",
    "payment_method": "pix"
  }'

Envio recomendado com arquivo

curl -X POST https://hubnotas.brunoalves.dev.br/api/v1/invoices \
  -H "Accept: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -F "system_id=1" \
  -F "external_id=NF-002" \
  -F "file=@/caminho/nota.pdf"

Em Postman, use Body como form-data. Configure system_id e external_id como Text, e file como File.

Resposta com dados extraidos

{
  "data": {
    "id": 10,
    "system_id": 1,
    "external_id": "NF-002",
    "issuer_name": "Mercado Central",
    "document_number": "CUPOM-789",
    "issued_at": "2026-08-24T00:00:00.000000Z",
    "total_amount": "58.35",
    "currency": "BRL",
    "category": "alimentacao",
    "payment_method": "cartao",
    "status": "extracted",
    "extracted_data": {
      "extraction_provider": "gemini",
      "extraction_model": "gemini-3.6-flash",
      "extraction_key_source": "user"
    }
  }
}

Campo	Obrigatorio	Descricao
`system_id`	Sim	ID do sistema cliente cadastrado.
`external_id`	Nao	ID da nota no sistema de origem. Evita duplicidade dentro do mesmo sistema.
`file`	Nao	Arquivo jpg, jpeg, png, pdf ou xml ate 10MB.
`issuer_name`	Nao	Fornecedor/emissor.
`document_number`	Nao	Numero ou chave da nota.
`issued_at`	Nao	Data de emissao ou compra.
`total_amount`	Nao	Valor total da nota.
`currency`	Nao	Moeda ISO com 3 letras. Padrao: BRL.

GET/api/v1/invoices?system_id=1&status=stored

Lista as notas do usuario autenticado. Os filtros sao opcionais.

DELETE/api/v1/invoices/{invoice}

Remove uma nota do usuario autenticado e apaga o arquivo armazenado, quando existir.

Se enviar novamente o mesmo external_id para o mesmo system_id, a API retorna a nota ja salva com status 200 e nao reprocessa a IA. Para reprocessar uma imagem, use um external_id novo ou remova a nota anterior.

Provedor de IA por usuario

Cada usuario pode escolher gemini ou openai. O HubNotas salva a chave do provedor criptografada e usa ela no momento da extracao.

Essa configuracao pode ser feita pelo painel web ou pela API.

PUT/api/v1/me/gemini

Gemini

curl -X PUT https://hubnotas.brunoalves.dev.br/api/v1/me/gemini \
  -H "Accept: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_provider": "gemini",
    "gemini_api_key": "sua-chave-gemini"
  }'

OpenAI / ChatGPT

curl -X PUT https://hubnotas.brunoalves.dev.br/api/v1/me/gemini \
  -H "Accept: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_provider": "openai",
    "openai_api_key": "sua-chave-openai"
  }'

Os modelos sao fixos pela configuracao GEMINI_MODEL e OPENAI_INVOICE_MODEL. Sem chave para o provedor escolhido, a nota ainda sera salva, mas voltara com status extraction_unavailable.

Quando a extracao funciona, o retorno inclui extraction_provider, extraction_model e extraction_key_source dentro de extracted_data.

Erros

401

Token ausente, invalido ou expirado.

404

Registro inexistente ou pertencente a outro usuario.

422

Payload invalido ou campos obrigatorios ausentes.

Status da nota:

extracted

A IA extraiu os dados principais com sucesso.

extraction_unavailable

O provedor escolhido nao possui chave configurada ou valida.

extraction_failed

O provedor respondeu erro ou ficou indisponivel durante a leitura.

Integracao externa

No sistema cliente, guarde o token Bearer e o system_id. Ao dar entrada em uma nota, envie o arquivo para /api/v1/invoices com um external_id unico da nota no sistema de origem.

O HubNotas devolve os campos extraidos na propria resposta. O sistema cliente pode usar esses dados para preencher fornecedor, numero, data, valor, categoria e forma de pagamento.

Para evitar duplicidade, mantenha sempre o mesmo external_id para a mesma nota real. Para teste manual, altere o external_id a cada envio.