Guia de migração — FocusNFE¶
1. Troque o endereço base¶
| Antes | Depois | |
|---|---|---|
| Produção | https://api.focusnfe.com.br |
https://focusnfe.api.veraciti.com.br |
| Homologação | https://homologacao.focusnfe.com.br |
https://focusnfe-sandbox.api.veraciti.com.br |
Os caminhos não mudam: tudo continua sob /v2, e as rotas de arquivo mantêm o mesmo formato
de caminho. Como no provedor, o endereço base + o token é o que seleciona o ambiente. Não
existe campo de ambiente no corpo.
2. Troque a credencial¶
O esquema é o mesmo: HTTP Basic com o token da empresa como nome de usuário e senha em branco.
Você recebe um token por empresa por ambiente, como hoje. Token inválido, ausente ou
desativado responde 401 com corpo text/html HTTP Basic: Access denied. É o mesmo
formato do provedor, então o tratamento de erro do seu cliente continua valendo. Token válido
agindo sobre um CNPJ que não é o dele continua sendo 403 permissao_negada.
3. Ajuste o corpo¶
Os campos são os mesmos, achatados e em português. Dois ajustes cobrem a maioria das integrações:
Adicione os campos de IBS/CBS em todo item. No mínimo, ibs_cbs_situacao_tributaria e
ibs_cbs_classificacao_tributaria. Ver
Validação.
Remova o que está fora do subconjunto. Somos estritos com campos desconhecidos: um campo
fora do subconjunto responde 422 erro_validacao_schema, em vez de ser ignorado em silêncio.
Isso inclui grupos que existem no dicionário do provedor mas não nesta versão. São eles:
partilha de ICMS por UF de destino, ST próprio, combustíveis monofásico, diferimento,
cashback, Imposto Seletivo e ZFM. A lista está na
página de compatibilidade.
Se o seu sistema envia numero, serie ou codigo_unico, leia
Numeração antes: por padrão o número é nosso, como no provedor,
e codigo_unico é sempre nosso.
4. Ponta a ponta¶
Descrição obrigatória em homologação
Em homologação, a descrição do primeiro item precisa ser exatamente
NOTA FISCAL EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL. Várias UFs
rejeitam (373) qualquer outra coisa. Em produção, use a descrição real do produto.
Emissão¶
curl -X POST 'https://focusnfe-sandbox.api.veraciti.com.br/v2/nfce?ref=PEDIDO1234' \
-u 'SEU_TOKEN_AQUI:' \
-H 'Content-Type: application/json' \
-d '{
"cnpj_emitente": "12345678000195",
"data_emissao": "2026-08-04T10:15:00-03:00",
"natureza_operacao": "VENDA AO CONSUMIDOR",
"presenca_comprador": "1",
"modalidade_frete": "9",
"local_destino": "1",
"items": [
{
"numero_item": 1,
"codigo_produto": "7891234",
"descricao": "NOTA FISCAL EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL",
"codigo_ncm": "22021000",
"cfop": "5102",
"unidade_comercial": "UN",
"unidade_tributavel": "UN",
"quantidade_comercial": "1",
"quantidade_tributavel": "1",
"valor_unitario_comercial": "10.00",
"valor_unitario_tributavel": "10.00",
"valor_bruto": "10.00",
"icms_origem": "0",
"icms_situacao_tributaria": "102",
"ibs_cbs_situacao_tributaria": "000",
"ibs_cbs_classificacao_tributaria": "000001",
"ibs_cbs_base_calculo": "10.00",
"ibs_uf_aliquota": "0.10",
"ibs_uf_valor": "0.01",
"ibs_mun_aliquota": "0.00",
"ibs_mun_valor": "0.00",
"ibs_valor_total": "0.01",
"cbs_aliquota": "0.90",
"cbs_valor": "0.09"
}
],
"formas_pagamento": [
{ "forma_pagamento": "01", "valor_pagamento": "10.00" }
]
}'
A emissão é síncrona, e a resposta é 201 nos dois desfechos, como no provedor:
{
"cnpj_emitente": "12345678000195",
"ref": "PEDIDO1234",
"status": "autorizado",
"status_sefaz": "100",
"mensagem_sefaz": "Autorizado o uso da NF-e",
"chave_nfe": "NFe41260812345678000195650010000000121000000011",
"numero": "12",
"serie": "1",
"caminho_xml_nota_fiscal": "/arquivos_development/41260812345678000195650010000000121000000011-nfe.xml",
"caminho_danfe": "/notas_fiscais_consumidor/NFe41260812345678000195650010000000121000000011.html",
"qrcode_url": "https://homologacao.nfce.fazenda.pr.gov.br/nfce/qrcode?p=…",
"url_consulta_nf": "https://homologacao.nfce.fazenda.pr.gov.br/nfce/consulta"
}
Rejeição da SEFAZ vem no mesmo 201, com status: "erro_autorizacao", status_sefaz e
mensagem_sefaz, sem chave nem numeração. Já uma recusa nossa, antes do envio, é 422
com o corpo de validação do provedor.
Os caminhos são relativos, como no provedor: concatene com o endereço base. Em homologação a
raiz é /arquivos_development. Em produção, /arquivos.
Consulta¶
curl 'https://focusnfe-sandbox.api.veraciti.com.br/v2/nfce/PEDIDO1234?completa=1' \
-u 'SEU_TOKEN_AQUI:'
completa=1 acrescenta protocolo e requisicao_nota_fiscal, o eco do que você enviou.
Atenção ao quirk do provedor, que reproduzimos: o eco chama o vetor de itens de itens, em
português, enquanto a emissão o chama de items. Não normalize um para o outro.
Cancelamento¶
Cancele dentro de 30 minutos da autorização, com justificativa de 15 a 255 caracteres:
curl -X DELETE https://focusnfe-sandbox.api.veraciti.com.br/v2/nfce/PEDIDO1234 \
-u 'SEU_TOKEN_AQUI:' \
-H 'Content-Type: application/json' \
-d '{ "justificativa": "Cancelamento a pedido do consumidor" }'
{
"status": "cancelado",
"status_sefaz": "135",
"mensagem_sefaz": "Evento registrado e vinculado a NF-e",
"caminho_xml_cancelamento": "/arquivos_development/41260812345678000195650010000000121000000011-can.xml",
"numero_protocolo": "141260000000456"
}
Uma recusa da SEFAZ vem em banda, com status: "erro_cancelamento" e HTTP 200.
Download dos arquivos¶
curl https://focusnfe-sandbox.api.veraciti.com.br/arquivos_development/4126…0011-nfe.xml \
-u 'SEU_TOKEN_AQUI:' -o documento.xml
curl https://focusnfe-sandbox.api.veraciti.com.br/notas_fiscais_consumidor/NFe4126…0011.html \
-u 'SEU_TOKEN_AQUI:' -o danfe.pdf
O segundo caminho termina em .html, mas serve um PDF. Ver
Compatibilidade.
Checklist¶
- [ ] Endereço base trocado (produção e homologação).
- [ ] Tokens novos, um por empresa por ambiente.
- [ ] Campos de IBS/CBS em todo item.
- [ ] Campos fora do subconjunto removidos. Teste em homologação e leia os
422. - [ ] Descrição de homologação aplicada no ambiente de testes.
- [ ] Tratamento de
caminho_danferevisado, se o seu código lia o HTML. - [ ]
forma_emissao=offlineremovido, se o seu código usava contingência manual. - [ ] Gatilhos recadastrados, se você usa
nfce_contingenciaouinutilizacao.