Esta documentação tem como principal objetivo apresentar como deve ser realizada a integração de sistemas diversos com a aplicação web Fiscal Cloud. Devido a arquitetura escolhida para o Fiscal Cloud, os serviços que serão apresentados possuem total possibilidade de comunicação com aplicações desenvolvidas em diferentes tipos de linguagem de programação. Nos próximos sub-tópicos serão apresentados alguns dos padrões utilizados.
A Representational State Transfer (REST), em português Transferência de Estado Representacional, é uma abstração da arquitetura da World Wide Web, mais precisamente, é um estilo arquitetural que consiste de um conjunto coordenado de restrições arquiteturais aplicadas a componentes, conectores e elementos de dados dentro de um sistema de hipermídia distribuído.
O REST ignora os detalhes da implementação de componente e a sintaxe de protocolo com o objetivo de focar nos papéis dos componentes, nas restrições sobre sua interação com outros componentes e na sua interpretação de elementos de dados significantes.
REST foi definido oficialmente pela W3C.
Fonte: Wikipedia
Esta abstração de arquitetura é frequentemente aplicada à web services fornecendo APIs para acesso a um serviço qualquer na web. Utiliza integralmente as mensagens HTTP para se comunicar através do que já é definido no protocolo sem precisar "inventar" novos protocolos específicos para
aquela aplicação.
Em todo o tempo o trabalho estará relacionado com componentes, conectores e dados:
• REST usa o protocolo HTTP (verbos, accept headers, códigos de estado HTTP, Content-Type) de forma explícita e representativa para se comunicar. URIs são usados para expor a estrutura do serviço. Utiliza uma notação comum para transferência de dados como XML ou JSON.
• Não possui estado entre essas comunicações, ou seja, cada comunicação é independente e uniforme (padronizada) precisando passar toda informação necessária.
• Este estilo arquitetural deve facilitar o cache de conteúdo no cliente.
• Deve ter clara definição do que faz parte do cliente e do servidor. O cliente não precisa saber como o servidor armazena dados, por exemplo. Assim cada implementação não depende da outra e se torna mais escalável.
• Permite o uso em camadas também facilitando a escalabilidade, confiabilidade e segurança.
• Frequentemente é criado com alguma forma de extensibilidade.
Quando a arquitetura atende aos cinco primeiros itens acima, a mesma pode ser classificada formalmente como RESTful.
Uma API Restful é pensada para proporcionar melhor performance, escalabilidade, simplicidade, flexibilidade, visibilidade, portabilidade e confiabilidade.
Um ponto interessante sobre API REST é que cada pode definir como quiser sua API, ao contrário de SOAP onde tudo é definido oficialmente.
Fonte canônica na dissertação do Dr. Roy Fielding
O Hypertext Transfer Protocol (HTTP), em português Protocolo de Transferência de Hipertexto, é um protocolo de comunicação (na camada de aplicação segundo o Modelo OSI) utilizado para sistemas de informação de hipermídia, distribuídos e colaborativos.Ele é a base para a
comunicação de dados da World Wide Web.
Hipertexto é o texto estruturado que utiliza ligações lógicas (hiperlinks) entre nós contendo texto. O HTTP é o protocolo para a troca ou transferência de hipertexto.
Fonte: Wikipedia
...
O protocolo HTTP define oito métodos (GET, HEAD, POST, PUT, DELETE, TRACE, OPTIONS e CONNECT) que indicam a ação a ser realizada no recurso especificado. O método determina o que o servidor deve fazer com o URL fornecido no momento da requisição de um recurso.
A Api Restful tenta responder conforme possível ao padrão HTTP e convenções REST conforme descrito pelos principais métodos HTTP abaixo:
Métodos | Uso |
---|---|
GET | Solicita a representação de um determinado recurso. É definido como um método seguro e não deve ser usado para disparar uma ação (remover um usuário, por exemplo). |
POST | As informações enviadas no corpo (body) da requisição são utilizadas para criar um novo recurso. Também é responsável por fazer processamentos que não são diretamente relacionados a um recurso. |
PUT | Atualiza um recurso na URI especificada. Caso o recurso não exista, ele pode criar um. A principal diferenteça entre POST e PUT é que o primeiro pode lidar não somente com recursos, mas pode fazer processamento de informações, por exemplo. |
DELETE | Remove um recurso. Deve retornar o status 204 caso não exista nenhum recurso para a URI especificada. |
Toda requisição recebe um código de resposta conhecido como status. Com o status é possível saber se uma operação foi realizada com sucesso (200), se ele foi movida e agora existe em outro lugar (301) ou se não existe mais (404).
Existem muitos status divididos em diversas categorias. Na especificação é possível ver cada um deles com uma descrição bastante detalhada.
A Api Restful tenta responder conforme possível ao padrão HTTP e convenções REST conforme descrito abaixo:
Esta api aceita requisições HTTP com compressão GZIP. Este recurso é altamente recomendado para reduzir drasticamente o tamanho do tráfego de dados. Em algus casos esta compressão pode chegar a 90%.
Para utilizar este recurso é necessário habilitar duas propriedades no cabeçalho HTTP da requisição:
Cabeçalhos HTTP | Valor esperado | Referência |
---|---|---|
Content-Encoding | content-encoding:gzip | http://tools.ietf.org/html/rfc7231#section-3.1.2.2 |
Accept-Encoding | accept-encoding:gzip | http://tools.ietf.org/html/rfc7231#section-5.3.4 |
O endpoint authorizer atende apenas a documentos NFC-e
...
O modo de autenticação e endpoints para NFC-e são diferentes do modo de autenticação e endpoints para NF-e e SAT
Ambiente | Url |
---|---|
Produção | https://fiscalcloud.bematech.com.br/authorizer |
...
Ao receber tais informações o Fiscal Cloud retorna uma chave de acesso, também conhecida como token de acesso.
Este token possui validade diária, ou seja, deve ser solicitado a cada dia. Este token é uma identificação única para o pdv do estabelecimento em questão.
Este recurso está disponível conforme os ambientes abaixo:
Ambiente | Url |
---|---|
Produção | https://fiscalcloud.bematech.com.br/authorizer/services/nfce_resource/autenticarPDV |
Parâmetros
Parâmetro | Tipo | Descrição | Observações |
---|---|---|---|
cnpj_contribuinte | String | CNPJ do estabelecimento | [Não pode estar vazio, Precisa ser um CNPJ válido] |
pdv | String | Identificação do PDV | [Não pode estar vazio, O Tamanho precisa estar entre 1 e 35 inclusive] |
Resposta
Parâmetro | Tipo | Descrição |
---|---|---|
chave | String | TOKEN de autenticação disponibilizado por 24 horas |
Curl Request
Dica |
---|
$ curl 'http://localhost:8080/services/nfce_resource/autenticarPDV' -i -X POST -H |
...
Este recurso é responsável por interpretar as requisições do sistema cliente, permitindo assim, que o serviço de monitoramento de PDV do Fiscal Cloud tenha informações sobre o status de cada PDV do estabelecimento.
O monitoramento apresentará os status Ativo, Inativo e Offline, Sendo ativo o PDV que estiver enviando nota dentro do intervalo de tempo configurado, inativo o PDV que estiver comunicando com o servidor, porém sem enviar nenhuma nota no intervalo configurado e Offline o PDV que não se comunicar com o servidor no intervalo de tempo esperado.
Este recurso está disponível conforme os ambientes abaixo:
Ambiente | Url |
---|---|
Produção | https://fiscalcloud.bematech.com.br/authorizer/services/pdv_resource/status |
Parâmetros
Parâmetro | Tipo | Descrição | Observações |
---|---|---|---|
chave | String | Chave de autenticacao (token) | [Não pode estar vazio] |
cnpj_contribuinte | String | CNPJ do estabelecimento | [Não pode estar vazio, Precisa ser um CNPJ válido] |
pdv | String | Identificação do PDV | [Não pode estar vazio, O Tamanho precisa estar entre 1 e 35 inclusive] |
Resposta
Parâmetro | Tipo | Descrição |
---|---|---|
mensagem | Object | Detalhes da mensagem de retorno |
intervalo_pdv | Number | Intervalo esperado, em minutos, para próxima comunicação do pdv |
Curl Request
Dica |
---|
$ curl 'http://localhost:8080/services/pdv_resource/status' -i -X POST -H 'ContentType: application/json;charset=UTF-8' -H 'Content-Encoding: content-encoding:gzip' -H |
...
Este recurso é responsável por interpretar as requisições do sistema cliente, permitindo assim, que o serviço de monitoramento de Certificados Digitais do Fiscal Cloud tenha informações sobre o status de cada certificado do estabelecimento.
Através deste monitoramento é possível identificar quais certificados estão em uso, que irão expirar em breve etc.
Este recurso está disponível conforme os ambientes abaixo:
Exemplo de envio de dados do Certificado Digital
Parâmetros
Parâmetro | Tipo | Descrição | Observações |
---|---|---|---|
chave | String | Chave de autenticacao(token) | [Não pode estar vazio] |
numSerie | String | Número de Série do Certificado | [Não pode estar vazio] |
cnpj_contribuinte | String | CNPJ do estabelecimento | [Não pode estar vazio, Precisa ser um CNPJ válido] |
pdv | String | Identificação do PDV | [Não pode estar vazio, O Tamanho precisa estar entre 1 e 35 inclusive] |
dataExpiracao | String | Data de Expiração do Certificado | [Não pode ser nulo] |
dataEmissao | String | Data de Emissão do Certificado | [Não pode ser nulo, Precisa estar no passado] |
nome | String | Nome do Certificado | [Não pode estar vazio] |
tipo | String | Tipo do Certificado | [Não pode estar vazio] |
Resposta
Parâmetro | Tipo | Descrição |
---|---|---|
mensagem | Object | Detalhes da mensagem de retorno |
intervalo_pdv | Number | Intervalo esperado, em minutos, para próxima comunicação do pdv |
Curl Request
Dica |
---|
$ curl 'http://localhost:8080/services/pdv_resource/certificado' -i -X POST -H |
...
Emissão normal
Este recurso é responsável por custodiar documentos com emissão normal.
Este recurso está disponível conforme os ambientes abaixo:
Exemplo de envio de documento
Parâmetros
Parâmetro | Tipo | Descrição | Observações |
---|---|---|---|
chave | String | Chave de autenticacao(token) | [Não pode estar vazio] |
uf | String | Unidade Federativa (UF) do estabelecimento | [Deve atender a expressão regular '^[AZ]{2}$', Não pode estar vazio] |
cnpj_contribuinte | String | CNPJ do estabelecimento | [Não pode estar vazio, Precisa ser um CNPJ válido] |
pdv | String | Identificação do PDV | [Não pode estar vazio, O Tamanho precisa estar entre 1 e 35 inclusive] |
lista_arquivos[0].conteudo_xml | String | Conteúdo do XML da NFC-e que será custodiado | Não pode ser vazio |
lista_arquivos[0].id_xml_nfce | String | Chave de acesso | Não pode ser vazio |
lista_arquivos[0].serie | String | Número da série | Não pode ser vazio |
lista_arquivos[0].protocolo_autorizacao | String | Protocolo de autorização | Não pode ser vazio |
lista_arquivos[0].autorizacao | String | Data e Hora de Autorização | Não pode ser vazio |
lista_arquivos[0].emissao | String | Data e Hora de Emissão | Não pode ser vazio |
lista_arquivos[0].numero | String | Número da NFC-e | Não pode ser vazio |
lista_arquivos[0].versao | String | Versão do documento | Não pode ser vazio |
Aviso |
---|
Campos de Datas, embora apresentados como strings no formato JSON(devido ao conceito de serialização), devem ser informados no padrão ISO 8601. Exemplo: |
Resposta
Parâmetro | Tipo | Descrição |
---|---|---|
lista_mensagens | Object | Lista com detalheas das mensagens de retorno |
intervalo_pdv | Number | Intervalo esperado, em minutos, para próxima autenticação e/ou envio de documentos do pdv |
Curl Request
Dica |
---|
$ curl 'http://localhost:8080/services/nfce_resource/enviarXML' -i -X POST -H |
...