Documentação API


Introdução

A Myse API foi criada pensando em automatizar e simplificar a emissão de nota fiscal eletrônica (NFe) e nota fiscal do consumidor eletrônica (NFCe) de nossos parceiros. Ela pode ser usada em conjunto com sistemas já existentes (como ERPs, plataformas de ecommerces e etc.), apenas requisitando os recursos necessários e transferindo para ela toda a responsabilidade de emissão e comunicação com o Sefaz.

Trabalhamos com a persistência de clientes, produtos e configurações fiscais, dessa forma a emissão de documentos fiscais fica ainda mais fácil.

Nossa documentação busca detalhar e explanar todos os recursos, mas caso alguma dúvida surja, entre em contato conosco.


Padronização

Nossa API foi projetada utilizando o conceito de serviços REST, charset UTF-8 e formato JSON para troca de mensagens (requisição e resposta).

Tecnologia Descrição
REST Modelo arquitetural que consiste de um conjunto coordenado de restrições aplicadas a componentes, conectores e elementos de dados dentro de um sistema distribuído.
UTF-8 Tipo de codificação Unicode de comprimento variável. Pode representar qualquer caracter Unicode, sendo também compatível com o ASCII.
JSON Formato leve para troca de informações entre aplicações. Embora seja um acrônimo para JavaScript Object Notation, pode ser utilizado independentemente de linguagem de programação.

Para trabalhar em cada recurso, a integração deverá utilizar os quatro principais verbos existentes do protocolo HTTP: GET, POST, PUT e DELETE.

Verbo Objetivo
GET Deverá ser utilizado sempre que o objetivo for obter informações sobre determinado recurso.
Por exemplo: listar clientes ou listar notas fiscais.
POST Deverá ser utilizado sempre que o objetivo for salvar uma nova instância de algum recurso.
Por exemplo: salvar novo cliente ou emitir nova NFCe.
PUT Deverá ser utilizado sempre que o objetivo for alterar ou completar informações sobre determinada instância de algum recurso.
Por exemplo: alterar preço do produto ou alterar endereço do cliente.
DELETE Deverá ser utilizado sempre que o objetivo for remover uma instância de algum recurso.
Por exemplo: excluir cliente ou excluir produto.

Segurança

Todas as requisições de serviços devem ser autenticadas por um Token, garantindo a segurança dos dados de cada cliente. O Token é único de cada empresa, sendo gerado na aba Integração, em Meus Dados, dentro do painel FazNota.

Caso possua acesso ao Painel de Gestão de Contas, é possível gerar Tokens para cada empresa administrada diretamente nele.

No cabeçalho da requisição HTTP o parâmetro Authorization deve conter o valor "Token {token da empresa}", já o parâmetro Content-Type deve conter o valor "application/json".

Authorization: Token {token da empresa}
Content-Type: application/json

Após isso, defina a URI da requisição, verbo HTTP para definir a ação a ser executada no recurso, o conteúdo da mensagem (se for o caso) e analise o retorno.


Recursos

Veja abaixo todos os recursos expostos no momento e como interagir com cada um deles.

Para realizar as requisições de nossa API utilize o link abaixo como ponto de requisição.

https://api.mysebr.com.br/nfemyse-v3/rest/

Status de retorno

Abaixo estão descritos todos os status de retorno do consumo da API, estes status têm como intuito identificar o sucesso, falha ou em que situação a sua requisição se encontra.

Como retorno, o nosso sistema sempre apresentará um dos status abaixo correspondente à situação da requisição e também uma mensagem descrevendo o status. Esta mensagem pode ser utilizada para uma interpretação humana do ocorrido.

Código Representação
001 Realizado o registro de solicitação de emissão para ser executado posteriormente.
002 Sua solicitação de emissão ainda não foi processada e se encontra na fila de processamento.
003 Sua solicitação de emissão está sendo processada neste exato momento.
004 A emissão foi realizada com sucesso, o documento já se encontra no órgão público responsável.
005 Solicitação de busca de dados realizada com sucesso.
010 O cancelamento do documento foi realizado com sucesso, o documento se encontra como cancelado no órgão público responsável.
050 Solicitação recusada pelo sistema, o número de origem já se encontra registrado no sistema.
900 A solicitação de emissão foi recusada pelo órgão público responsável.
999 Ocorreu um erro interno do sistema ao processar a sua solicitação.