O sistema Focus NFe é dividido em duas partes, o módulo Web e o Núcleo.
O núcleo é o responsável por toda a lógica puramente inerente à Nota Fiscal Eletrônica, ou seja, a geração dos arquivos XML e DANFe, a comunicação com a receita para autorização, cancelamento e outras operações, a escolha entre servidor normal ou SCAN (contingência) e por aí vai.
Já o Módulo Web é o responsável pela interação com o usuário do sistema, são telas desenhadas para funcionar dentro do navegador e destinadas aos cadastros básicos (pessoas, produtos, etc) e para o preenchimento da Nota Fiscal em si. É responsabilidade do módulo web também toda a lógica de cálculo automatizado de impostos, funcionalidade muito apreciada pelos nossos usuários pois evita a necessidade de preenchimento de dezenas de campos referentes aos vários tributos existentes no Brasil.
Além do uso comum do sistema, ou seja, o preenchimento da NFe nas telas web e envio das notas, existem hoje duas formas de integrar outros sistemas com o Focus NFe. A integração direta e a integração 2 (que nome dar?). Na integração direta é responsabilidade do sistema que está se integrando de preencher todos os dados da nota fiscal, enviar diretamente ao núcleo do Focus NFe e consultar o resultado um tempo depois. Esta integração é explicada aqui (link para um post que explique isso).
O Módulo Web também pode ser integrado com sistemas externos, desta forma o sistema que está se integrando não precisa fazer todos os cálculos de impostos, cadastrando via API os destinatários da nota, os produtos e a nota em si.
Conceitos básicos da API
A API se baseia em domínios e tokens de acesso. Ao contratar o Focus NFe na modalidade “Integração Módulo Web” o programador receberá um identificador de domínio e um token de acesso de nosso suporte técnico. Toda a comunicação deverá ser feita através da utilização destas informações. Veja o exemplo abaixo, ele faz uma busca por uma pessoa com cnpj 07.504.505/0001-32 no domínio 100.
<a href="http://localhost:3000/api/pessoas?domain=1&access_token=J8Lqxw81upY8m0oTyE30ubwh9Umin6wQ&cnpj=03693480614355">https://app.acras.com.br/web_nfe/api/pessoas?domain=100&</a><a href="http://localhost:3000/api/pessoas?domain=1&access_token=J8Lqxw81upY8m0oTyE30ubwh9Umin6wQ&cnpj=03693480614355">access_token=J8Lqxw81upY8m0oTyE30ubwh9Umin6wQ&cnpj=03693480614355</a>
Veja que os dois primeiros parâmetros da URL são o domain e o access_token.
API de pessoas
Índice
sintaxe: [GET] /pessoas
parâmetros: cnpj ou cpf
retorno:
-quando encontrar uma pessoa retorna um xml representando a pessoa e status 200
-quando não encontrar uma pessoa retorna vazio e status 404
Não disponibilizamos uma listagem completa de todas as pessoas cadastradas para evitar solicitações que sobrecarreguem o serviço. Todo índice deverá conter filtragem por CNPJ ou CPF.
Criação
<strong><span style="text-decoration: underline;">sintaxe</span>:</strong> [POST] /pessoas
<span style="text-decoration: underline;"><strong>uso</strong></span><strong>:</strong>
-Todos os parâmetros devem ser enviados como sub-parâmetros de pessoa,
ou seja pessoa['nome'], pessoa['cpf'], etc.
<span style="text-decoration: underline;"><strong>parâmetros</strong></span><strong>:</strong>
-<strong>nome</strong>: o nome da pessoa com até 60 caracteres
-<strong>cpf ou cnpj</strong>: somente um dos dois sendo cpf com 11 ou cnpj com 14 caracteres
-<strong>inscricao_estadual ou isento_inscricao_estadual</strong>: inscricao_estadual com até
14 caracteres ou o isento_inscricao_estadual preenchido com o valor 1 para
indicar que é isento.
-telefone: 10 caracteres exatamente
-email: Endereço de e-mail da pessoa. Se for informado, o Focus NFe irá disparar
um e-mail para esta pessoa sempre que uma NFe seja autorizada para ela.
-habilita_emissao_nfe: 0 - Não, 1 - Sim. Se estiver desabilitado não será possível
emitir NFe para esta pessoa e algumas validações serão desligadas
-logradouro(<strong>obrigatório se habilita_nfe=1</strong>): nome do logradouro
-numero(<strong>obrigatório se habilita_nfe=1</strong>): número do endereço
-complemento: complemento do endereço
-bairro(<strong>obrigatório se habilita_nfe=1</strong>): bairro da pessoa
-municipio(<strong>obrigatório se habilita_nfe=1</strong>): verifique abaixo as duas formas de
preencher o município, se for preenchido codigo_municipio os outros dois
parâmetros serão ignorados
-codigo_municipio: Código IBGE do município
-nome_municipio e uf_municipio: Dois parâmetros, um contendo o nome e outro contendo a UF
-cep(<strong>obrigatório se habilita_nfe=1</strong>): cep do endereçamento da pessoa
-codigo_pais: Código de país conforme a tabela do
<strong> SISBACEN </strong>(<a href="http://www.mdic.gov.br/arquivos/dwnl_1211380426.pdf">http://www.mdic.gov.br/arquivos/dwnl_1211380426.pdf</a>).
Se vazio será assumido código 1058 (Brasil)
<span style="text-decoration: underline;"><strong>retorno</strong></span>:
-quando a pessoa for criada retorna um xml representando a pessoa e status 201 (created)
-quando não criar a pessoa por alguma falha de validação são retornados os erros de
validação e o status 200 (OK)<span class="Apple-style-span" style="font-family: Georgia, 'Times New Roman', 'Bitstream Charter', Times, serif; font-size: 13px; line-height: 19px; white-space: normal;"> </span>
Atualização
<span style="text-decoration: underline;"><strong>sintaxe</strong></span>: [PUT] /pessoas/{id}
<span style="text-decoration: underline;"><strong>parâmetros</strong></span>: são os mesmos parâmetros da criação, apenas repare como na URL utilizada
deve ser passado o id do registro, pois é uma atualização
API de Produtos
Índice
sintaxe: [GET] /produtos
parâmetros: codigo
retorno:
-quando encontrar um produto retorna um xml representando o produto e status 200
-quando não encontrar um produto retorna vazio e status 404
Criação
<strong>sintaxe:</strong> [POST] /produtos
<strong>uso</strong><strong>:</strong>
-Todos os parâmetros devem ser enviados como sub-parâmetros de produto,
ou seja produto['codigo'], produto['descricao'], etc.
<strong>parâmetros</strong><strong>:</strong>
-<strong>codio</strong>: código do produto contendo até 60 caracteres, para integração é obrigatório
-<strong>descricao</strong>: descrição do produto contendo até 120 caracteres
-<strong>codigo_ncm ou capitulo_ncm</strong>: um dos dois onde codigo deve conter exatamente 8 caracteres e capitulo exatamente 2.
Este parâmetro deve ser informado conforme a configuração
-unidade_comercial: Unidade em que o produto é comercializado. Se for vazio será assumido 'un'
-valor_unitario_comercial: Valor unitário do produto
Atualização
<strong>sintaxe:</strong> [PUT] /produtos/{id}
Aqui são aceitos os mesmos parâmetros da criação, observar que o método é o PUT e que deve ser passado o id do registro que está sendo atualizado.
API de Notas Fiscais
<strong>sintaxe</strong>: [POST] /notas_fiscais
<strong>parâmetros</strong>:
-<strong>natureza_operacao</strong>: Descritivo com até 60 caracteres da natureza da operação desta nota fiscal
-<strong>tipo_documento</strong>: ENTRADA | SAIDA
-data_emissao: Data de emissão deste documento fiscal no formato aaaa-mm-dd se vazio é assumido como hoje
-data_entrada_saida: Data de entrada ou saída das mercadorias no formato aaaa-mm-dd
-hora_entrada_saida: Hora de entrada ou saída das mercadorias no formato hh:mm:ss
-cnpj_emitente: CNPJ do emitente. Obrigatório somente para domínios que possuem mais de um emitente, se
houver apenas um o Focus NFe irá escolher automaticamente.
-destinatario_id: id do destinatario desta nota. Este id é adquirido quando se faz a criação ou busca de
uma pessoa pela API.
-enviar: se estiver com o valor 1 efetua o envio para a receita, senão somente grava a nota para envio manual. Este parâmetro deve ser enviado na raiz dos params, ou seja, não fica abaixo do nota_fiscal.