API do sistema POSPonto de entrada único a partir do teu POS para fiskaltrust.Middleware.
Cria recibos, executa pagamentos, emite recibos digitais e exporta diários através de uma API HTTP orientada para o processo
A API permite-te concentrar-te no teu sistema enquanto a fiskaltrust trata da infraestrutura dos recibos. Em vez de tratar os recibos como uma funcionalidade secundária ou um complemento para o consumidor, a API de recibos trata os recibos como um componente de sistema regulamentado de primeira classe. Integra uma vez e conta com uma API unificada e de código aberto que é mantida à medida que os regulamentos e os requisitos operacionais evoluem.
A API do sistema POS da fiskaltrust serve como interface central entre os sistemas POS e o Middleware da fiskaltrust. Oferece um conjunto abrangente de funcionalidades, incluindo a fiscalização (ou assinatura) de recibos, a execução de pagamentos através de vários fornecedores, a impressão de recibos digitais e a exportação de dados a partir do Middleware.
Através de pontos de extremidade simples e consistentes, a API suporta funções-chave: /echo para testes de conetividade, /order para registar dados de encomendas, /pay para atribuição de pagamentos, /sign para selar transacções em conformidade, /issue para gerar recibos digitais ou imprimíveis e /journal para exportações prontas para auditoria.
Endpoints de API de fácil leitura
International PosSystem-API
- /echo,verifica o estado de saúde e reinicia.
- /order,regista as informações da encomenda e consulta o estado ou o resultado.
- /pay,executa pagamentos, aguarda a conclusão com tempos limite, vai buscar o resultado.
- /sign,finaliza os recibos com regras nacionais e encadeamento de hash.
- /issuecria e actualiza o recibo emitido, incluindo o estado da entrega.
- /journal,recupera entradas individuais ou intervalos para auditorias e encerramentos.
API do concessionário de POS. Criada para integrações estáveis, transparentes e à prova de auditoria.
Concebida para utilização em várias plataformas, a API suporta implementações locais e instâncias alojadas na nuvem em centros de dados europeus. Fornece armazenamento seguro de revisão e integra-se com o Middleware fiskaltrust para actualizações automáticas de conformidade.
Partes da API e do Middleware são de fonte aberta, oferecendo transparência e estabilidade a longo prazo. Com documentação aberta e um modelo de dados uniforme, isto reduz o esforço de manutenção e mantém as soluções POS à prova de auditoria.
Uma API, comportamento consistente, independentemente dos requisitos específicos de cada país.
Conceitos fundamentais
A API trata uma transação como uma viagem. Cada etapa altera o estado no servidor. Passa um identificador de operação único em cada chamada. Se a rede cair, repete a mesma chamada com o mesmo identificador.
O backend deduplica e devolve o primeiro resultado concluído. Esta conceção permite tentativas seguras e resultados previsíveis para passos fiscais críticos.
- Ponto de entrada central para o Middleware para fiscalizações, pagamentos, emissões e exportações.
- Padrões de chamada processuais e com estado que se comportam como uma máquina de estado.
- Idempotência através do cabeçalho x-operation-id com respostas determinísticas na repetição.
- Ganchos de retorno de chamada para observar transições de estado durante operações longas.
Um pedido com x-operation-id entra no Middleware
Middleware processing
Volta a tentar com o mesmo x-operation-id
Concluído resultado
Ponto de extremidade de resposta x-operation-callback-state
Autenticação e controlo de versões
O acesso é delimitado pela CashBox. Utiliza o CashBoxId e o AccessToken do Portal. A API segue o versionamento semântico. As alterações de rutura estão limitadas às versões principais e podem ser fixadas no URL quando necessário.
- Credenciais: CashBoxId e AccessToken.
- Versões semânticas, as mais recentes por defeito, com suporte de fixação explícita.
Programador de POS
Autenticação CashBoxId + AccessToken
V1
V2
V3
Padrões assíncronosAPI
A API permite-te concentrar-te no teu sistema enquanto a fiskaltrust trata da infraestrutura dos recibos. Em vez de tratar os recibos como uma funcionalidade secundária ou um complemento para o consumidor, a API de recibos trata os recibos como um componente de sistema regulamentado de primeira classe. Integra uma vez e conta com uma API unificada e de código aberto que é mantida à medida que os regulamentos e os requisitos operacionais evoluem.
Cabeçalhos e idempotência
Cada chamada crítica aceita cabeçalhos de controlo. x-operation-id é a tua chave de idempotência. x-operation-lifetime define o tempo de validade da operação. Podes definir um URL de chamada de retorno por chamada para receber mensagens de estado sem sondagem.
- x-operation-id, único por operação para deduplicar as tentativas.
- x-operation-lifetime, janela de aceitação em milissegundos.
- x-operation-callback-state, notifica em cada mudança de estado.
- Opcional x-terminal-id e x-possystem-id para atribuição.
Estado da entrega e da receção
Após a emissão, podes ir buscar o conteúdo emitido, actualizá-lo ou consultar o estado de entrega. Existem pontos de extremidade de bloqueio que aguardam até um tempo limite máximo e informam se foram entregues ou não. Isto simplifica o fluxo de utilizadores no checkout e evita sondagens ocupadas.
Ambientes
A API fornece ambientes sandbox e de produção para cada ponto de extremidade. Usa a sandbox para integração e testes automatizados. Promove as mesmas chamadas para produção quando estiver pronto. A AynchronousAPI, os cabeçalhos e os callbacks comportam-se da mesma forma em ambos.
Tratamento de erros
As chamadas devolvem códigos de estado HTTP normais. Pedidos malformados ou cabeçalhos em falta produzem erros de cliente. As falhas de autenticação devolvem não autorizado. O servidor comunica erros inesperados com detalhes do problema, quando disponíveis. As novas tentativas com o mesmo identificador de operação devolvem o primeiro resultado concluído.
Utiliza uma interface aberta e documentada que se adapta à medida que os regulamentos mudam.
Como funciona em 3 passos
Configura uma caixa registadora no Portal e obtém as credenciais. O teu POS chama o carrinho, encomenda e paga para construir a viagem. Completa com assinar e emitir, depois lê as entradas do diário para o fecho diário ou auditorias. Repete os passos falhados com segurança, reutilizando o identificador de operação.
1.
Inscreve-te no fiskaltrust.Portal.
2.
Cria uma caixa de dinheiro e liga-a ao seu POS ou ERP.
3.
Conduz a viagem: carrinho, encomenda, pagamento, assinatura, emissão.
Fundamentos do programador
Começa com a especificação OpenAPI e a documentação em tempo real. Revê os diagramas SynchronousAPI e o contrato de cabeçalho. Constrói tentativas com idempotência e callbacks. Usa a sandbox para validar as transições de estado e o comportamento de entrega de recibos antes da produção.
- Página de documentos da API do sistema POS e ficheiro OpenAPI.
- Diagramas de estado e de tempo da SynchronousAPI.
- Pontos finais de sandbox para echo, carrinho, encomenda, pagamento, assinatura, emissão, diário.
Tens dúvidas sobre a integração? A nossa equipa técnica está apenas a uma mensagem de distância.
Contacta-nos