Esta documentação tem como principal objetivo Esta documentação tem como principal objetivo apresentar como deve ser realizada a integração de sistemas diversos com a aplicação web Fiscal CloudProcessos Fiscais. Devido a arquitetura escolhida para o Fiscal CloudProcessos Fiscais, 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:
...
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
...
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://fiscalcloudplataformafiscal.bematechtotvs.com.br/authorizer |
Para ter acesso as recursos da API do Fiscal Cloud Processos Fiscais é necessário que o Estabelecimento e PDV sejam reconhecidos pelo sistema.
Este procedimento é realizado através da autenticação do pdv do estabelecimento.
Ao receber tais informações o Fiscal Cloud Processos Fiscais 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] |
...
Dica |
---|
HTTP/1.1 200 OK |
Neste tópico, apresentamos todos os detalhes de cada um dos serviços RestFul disponíveis na API de integração com o
...
Processos Fiscais.
Ambiente | Url |
---|---|
Produção |
Método: | POST |
Descrição: | Utilize este recurso da API para a emissão da nota fiscal eletronica. |
Modelo JSON (Envio e Retorno): | http://52.5.21.250:8082/api/v1/nfe |
Método: | POST |
Descrição: | Utilize este recurso para cancelar um documento. |
Modelo JSON (Envio e Retorno): | http://52.5.21.250:8082/api/v1/nfe/cancelar |
...
...
Método: | POST |
Descrição: | Utilize este recurso |
para emitir a |
carta de correção do documento. | |
Modelo JSON (Envio e Retorno): | http:// |
52. |
5. |
21. |
250:8082/api/ |
...
v1/nfe/carta-correcao |
Método: | POST |
Descrição: | Utilize este recurso para |
inutilizar uma ou mais numeração. | |
Modelo JSON (Envio e Retorno): | http:// |
52. |
5. |
21. |
250:8082/api/ |
...
v1/nfe/inutilizar |
Método: | POST |
Descrição: | Utilize este recurso para |
consultar a situação do documento fiscal. | |
Modelo JSON (Envio e Retorno): | http:// |
52. |
5. |
21. |
250:8082/api/ |
v1/nfe/consulta-situacao |
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 Processos Fiscais 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
Pivot Table | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||
|
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 |
...
Dica |
---|
HTTP/1.1 200 OK |
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 Processos Fiscais 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:
...
Dica |
---|
HTTP/1.1 200 OK |
O Fiscal Cloud Processos Fiscais permite gerenciar documentos NFC-e através da custódia de arquivos xml.
Os seguintes documentos podem ser armazenados no sistema:
• Emissão Normal
• Emissão em Contingência
• Inutilizados
• Cancelados
• Contingência OFFLINE
...