Histórico da Página
CONTEÚDO
- 01. VISÃO GERAL
- 02. API RESTFUL
- 03. PROTOCOLO HTTP
- 04. MÉTODOS HTTP
- 05. CÓDIGOS DE STATUS HTTP
- 06. COMPRESSÃO HTTP
- 07. NFCE
- 08. RECURSOS DISPONÍVEIS
01. VISÃO GERAL
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.
02. API RESTFUL
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
03. PROTOCOLO HTTP
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. |
05. CÓDIGOS DE STATUS HTTP
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:
...
06. COMPRESSÃO HTTP
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 |
07. PONTOS DE ATENÇÃO
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
07. NFCE
ENDPOINTS
| Ambiente | Url |
|---|---|
| Produção | https://fiscalcloudplataformafiscal.bematechtotvs.com.br/authorizer |
07. RECURSOS DISPONÍVEIS
Autenticação de PDV
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 |
Exemplo de autenticação
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 |
08.RECURSOS DA API
Neste tópico, apresentamos todos os detalhes de cada um dos serviços RestFul disponíveis na API de integração com o Fiscal CloudProcessos Fiscais.
08.1 NF-E
ENDPOINTS
| Ambiente | Url |
|---|---|
| Produção |
08.2 RECURSOS DISPONÍVEIS
Envio de NF-e
Método: | POST |
Descrição: | Utilize este recurso da API para a emissão de uma nova da nota fiscal eletronica. |
Modelo JSON (Envio e Retorno): | http://3452.205 5.0 21.121 250:8082/api/swagger-ui.html#/NFe/emitirUsingPOST v1/nfe |
Cancelamento NF-e
Método: | POST |
Descrição: | Utilize este recurso para cancelar um documento. |
Modelo JSON (Envio e Retorno): | http://3452.205 5.0 21.121 250:8082/api/swagger-ui.html#/NFe/cancelarUsingPOST |
...
v1/nfe/cancelar |
Carta de Correção NF-e
Método: | POST |
Descrição: | Utilize este recurso para inutilizar uma emitir a carta de correção do documento. |
Modelo JSON (Envio e Retorno): | http://52.5.21.250:8082/api/v1/nfe/carta-correcao |
Inutilizar numeração
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 |
Consulta Situação de NF-e:
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 |
09. STATUS DE PDV
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 |
Exemplo de envio do status do PDV
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 |
08. MONITORAMENTO DE CERTIFICADO DIGITAL
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 |
09. CUSTÓDIA DE DOCUMENTOS
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
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas