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.
https://app.acras.com.br/web_nfe/api/pessoas?domain=100&access_token=J8Lqxw81upY8m0oTyE30ubwh9Umin6wQ&cnpj=03693480614355
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
sintaxe: [POST] /pessoas
uso:
-Todos os parâmetros devem ser enviados como sub-parâmetros de pessoa,
ou seja pessoa['nome'], pessoa['cpf'], etc.
parâmetros:
-nome: o nome da pessoa com até 60 caracteres
-cpf ou cnpj: somente um dos dois sendo cpf com 11 ou cnpj com 14 caracteres
-inscricao_estadual ou isento_inscricao_estadual: 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(obrigatório se habilita_nfe=1): nome do logradouro
-numero(obrigatório se habilita_nfe=1): número do endereço
-complemento: complemento do endereço
-bairro(obrigatório se habilita_nfe=1): bairro da pessoa
-municipio(obrigatório se habilita_nfe=1): 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(obrigatório se habilita_nfe=1): cep do endereçamento da pessoa
-codigo_pais: Código de país conforme a tabela do
SISBACEN (http://www.mdic.gov.br/arquivos/dwnl_1211380426.pdf).
Se vazio será assumido código 1058 (Brasil)
retorno:
-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)
Atualização
sintaxe: [PUT] /pessoas/{id}
parâmetros: 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
sintaxe: [POST] /produtos
uso:
-Todos os parâmetros devem ser enviados como sub-parâmetros de produto,
ou seja produto['codigo'], produto['descricao'], etc.
parâmetros:
-codio: código do produto contendo até 60 caracteres, para integração é obrigatório
-descricao: descrição do produto contendo até 120 caracteres
-codigo_ncm ou capitulo_ncm: 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
sintaxe: [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
sintaxe: [POST] /notas_fiscais
parâmetros:
-natureza_operacao: Descritivo com até 60 caracteres da natureza da operação desta nota fiscal
-tipo_documento: 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.
