Horizon Finanças

API Horizon

Integre seus sistemas aos dados do Horizon Finanças da sua empresa. Os endpoints são organizados em grupos; cada grupo corresponde a uma área do sistema, é liberado na sua chave e exige acesso à tela dela.

Endereço base
Autenticação: Chave → token Bearer de 15 min
Formato: JSON, UTF-8
Datas e horas: Horário de Brasília (-03:00)

Grupos de endpoints

Início rápido

1

Gere sua chave no Horizon Finanças, em Integrações › API Horizon: escolha a empresa, a validade e o que a chave acessa. Aparecem só os grupos das telas que você tem.

A chave aparece uma vez só: guarde num cofre de senhas.
2
Troque a chave por um token. Ele vale 15 minutos.
3
Chame os endpoints com o token no cabeçalho Authorization. Ao lado, um exemplo com o grupo Notas fiscais.

Autenticação e permissões

Chave de API hzn_…

Uma por usuário, gerada em Integrações › API Horizon, com validade de 90 dias, 180 dias ou 1 ano. Gerar outra substitui a anterior.
Presa ao usuário (age com as permissões dele) e a uma empresa (só enxerga os dados dela).
Acessa só os grupos liberados nela e as permissões de escrita marcadas. Dá para mudar sem trocar a chave.
Enviada só em POST /auth/token, no cabeçalho X-Api-Key.

Token hzt_…

Vale 15 minutos. Reaproveite até expirar.
Enviado em todas as outras rotas: Authorization: Bearer <token>.
Expirou (401 TOKEN_EXPIRADO)? Gere outro com a chave.
Serve só para esta API: não abre nenhuma tela do Horizon.

Conferido a cada chamada: o dono da chave está ativo e com acesso à empresa; o grupo do endpoint está liberado na chave (senão 403 GRUPO_NAO_LIBERADO); e o dono ainda tem a tela do grupo (senão 403 SEM_PERMISSAO). Revogar ou substituir a chave invalida também os tokens já gerados com ela.

Testar nesta página

Cole sua chave e use o botão Executar de cada endpoint. A cada execução a página gera um token novo e faz a chamada com ele — os dados são reais.

A chave fica só na memória desta aba: não é gravada e some ao recarregar a página.

Notas fiscais

Objeto Nota fiscal

Devolvido pela listagem, pela consulta de uma nota e pela inativação.

statusInterno

Mesmas abas do Acervo NF-e / NFS-e. Quando mais de um vale, prevalece nesta ordem: inativada, cancelada, vinculada, pendente.

Notas fiscais

Consulta incremental

Para não baixar tudo a cada rodada, guarde o momento em que a consulta começou e envie esse valor em atualizadoDesde na próxima.

dataAtualizacao muda quando a nota:

é capturada;
é inativada ou reativada;
é vinculada ou desvinculada do contas a pagar;
recebe um evento fiscal (cancelamento, CT-e, comprovante de entrega…).

Mantenha o período de emissão cobrindo as notas que você acompanha (até 366 dias).

Convenções

Data	`AAAA-MM-DD`
Data e hora	ISO 8601 em horário de Brasília, com o deslocamento: `2026-10-28T09:15:42-03:00`. Em parâmetros de data e hora o fuso é obrigatório (aceita `Z`).
Valores	Número decimal em reais, com ponto: `379.34`.
CNPJ	Só dígitos, 14 caracteres (CPF: 11).
Listas na URL	Separadas por vírgula (`status=pendente,vinculada`) ou repetindo o parâmetro.
Paginação	`page` e `pageSize` (padrão 100, máximo 200). A resposta traz `items` e `pagination` com `total` e `totalPages`.
Parâmetros	Nome desconhecido é recusado (`400 PARAMETRO_DESCONHECIDO`), para um erro de digitação não virar filtro ignorado.
Versão	Tudo sob `/v1`. Campos novos podem ser acrescentados nas respostas sem aviso; mudanças incompatíveis só numa versão nova.

Erros

Todo erro vem com o status HTTP e um corpo no mesmo formato. Trate pelo codigo; a mensagem é para pessoas e pode mudar.

Limites

O quê	Limite
Endpoints com token	60 por minuto, por chave
Geração de token	30 por minuto, por endereço IP
Total	120 por minuto, por endereço IP

Passou do limite: 429 LIMITE_EXCEDIDO com o cabeçalho Retry-After (segundos até liberar). Toda resposta traz RateLimit e RateLimit-Policy com o saldo restante.

Segurança

Guarde a chave num cofre de senhas ou variável de ambiente do servidor. Nunca em código-fonte, repositório, aplicativo ou página web.
Libere na chave só os acessos que a integração precisa; escrita só quando o fluxo exigir.
A chave só trafega em POST /auth/token; nas demais chamadas vai só o token, que expira em 15 minutos.
Sempre HTTPS. O Horizon guarda apenas o hash da chave e do token.
Vazou? Revogue ou gere uma nova em Integrações › API Horizon: a chave antiga e todos os tokens dela param na hora.
Toda chamada fica registrada (quando, rota, status, IP) e aparece em Chamadas, na tela da chave.