0

API para integração com o módulo Web do Focus NFe

Posted dezembro 11th, 2011 in NFe by ricardo

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.

													

					

					
										


			

	 







Leave a Reply