VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Cupons, vales, pagamentos e NF-e

NF-e do seller

Configura os dados fiscais de emissão e lista as notas fiscais das vendas do seller.

No Brasil toda venda de mercadoria exige uma nota fiscal. A loja usa a Focus NFe para emitir a NF-e. O seller pode informar os próprios dados de emitente para que as notas saiam em nome dele. Todas as rotas exigem o módulo focusnfe.

O token volta por inteiro

GET e PUT em /nfe/config devolvem api_token sem mascarar. Trate a resposta como segredo: não registre em log nem exponha em telas.

Emissão fora desta seção

O seller não emite nota por estas rotas. A emissão ocorre pelo fluxo do pedido, usando a configuração do seller quando está active e a da loja nos demais casos.

Ver configuração fiscal

A NF-e (nota fiscal eletrônica) é emitida por meio da Focus NFe. Cada seller pode ter os próprios dados de emitente (CNPJ, token...). Esta rota lê essa configuração. Sem configuração própria, config vem null e a loja emite com os dados dela.

GET/api/v1/vendor/nfe/configSeller

Configuração de emissão de NF-e do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/nfe/config" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração
json
{
  "config": {
    "id": "9c8210a2-a8b6-4ec9-890b-9c0258d2d99a",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "api_token": "SEU_TOKEN_FOCUSNFE",
    "environment": "homologacao",
    "cnpj": "12345678000195",
    "inscricao_estadual": "123456789",
    "natureza_operacao": "Venda de mercadoria",
    "regime_tributario": 1,
    "razao_social": "Loja Exemplo LTDA",
    "nome_fantasia": "Loja Exemplo",
    "street": "Rua das Flores",
    "number": "123",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "cep": "01310100",
    "active": true,
    "created_at": "2026-10-01T22:52:35Z",
    "updated_at": "2026-10-10T23:15:37Z"
  }
}
200Sem configuração
json
{
  "config": null
}

Campos da resposta

configobject|null

A configuração, ou null.

iduuid
Id da configuração.
vendor_iduuid
Seller.
api_tokenstring
Token da conta do seller na Focus NFe. Atenção: a leitura devolve o token por inteiro.
environmentstring
homologacaoproducao
Ambiente.
cnpjstring
CNPJ do emitente, só dígitos (14).
inscricao_estadualstring
Inscrição estadual.
natureza_operacaostring
Natureza da operação.
regime_tributariointeger
123
Regime tributário: 1 Simples Nacional, 2 Simples com excesso, 3 Regime Normal.
razao_socialstring
Razão social.
nome_fantasiastring
Nome fantasia.
streetstring
Logradouro.
numberstring
Número.
complementstring
Complemento. Omitido se vazio.
neighborhoodstring
Bairro.
citystring
Cidade.
statestring
UF.
cepstring
CEP, só dígitos (até 8).
activeboolean
Se a loja deve emitir com esta configuração. Inativa, as notas saem pela configuração da loja.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O módulo focusnfe está desligado nesta loja.{"error":"module_disabled","module":"focusnfe"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Salvar configuração fiscal

Grava a configuração (cria na primeira vez, substitui nas seguintes). É uma substituição completa: o que não for enviado fica vazio ou zero, e active omitido grava false. CNPJ e CEP aceitam máscara, que é removida.

PUT/api/v1/vendor/nfe/configSeller

Criar ou substituir a configuração de NF-e

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

api_tokenstring
Token da Focus NFe do seller.
environmentstringpadrão: homologacao
homologacaoproducao
Ambiente. Vazio vira homologacao.
cnpjstringobrigatório
CNPJ com 14 dígitos (máscara aceita).
inscricao_estadualstring
Inscrição estadual.
natureza_operacaostring
Natureza da operação. Vazio vira Venda de mercadoria.
regime_tributariointeger
123
1, 2 ou 3.
razao_socialstring
Razão social.
nome_fantasiastring
Nome fantasia.
streetstring
Logradouro.
numberstring
Número.
complementstring
Complemento.
neighborhoodstring
Bairro.
citystring
Cidade.
statestring
UF.
cepstring
CEP com até 8 dígitos (máscara aceita).
activebooleanpadrão: false
Usar esta configuração nas emissões. Omitido = false.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/nfe/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "api_token": "SEU_TOKEN_FOCUSNFE",
  "environment": "homologacao",
  "cnpj": "12.345.678/0001-95",
  "inscricao_estadual": "123456789",
  "regime_tributario": 1,
  "razao_social": "Loja Exemplo LTDA",
  "nome_fantasia": "Loja Exemplo",
  "street": "Rua das Flores",
  "number": "123",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "cep": "01310-100",
  "active": true
}'

Resposta

200Configuração salva
json
{
  "config": {
    "id": "9c8210a2-a8b6-4ec9-890b-9c0258d2d99a",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "api_token": "SEU_TOKEN_FOCUSNFE",
    "environment": "homologacao",
    "cnpj": "12345678000195",
    "inscricao_estadual": "123456789",
    "natureza_operacao": "Venda de mercadoria",
    "regime_tributario": 1,
    "razao_social": "Loja Exemplo LTDA",
    "nome_fantasia": "Loja Exemplo",
    "street": "Rua das Flores",
    "number": "123",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "cep": "01310100",
    "active": true,
    "created_at": "2026-10-01T22:52:35Z",
    "updated_at": "2026-10-10T23:15:37Z"
  }
}

Campos da resposta

configobject

A configuração gravada.

iduuid
Id da configuração.
vendor_iduuid
Seller.
api_tokenstring
Token da conta do seller na Focus NFe. Atenção: a leitura devolve o token por inteiro.
environmentstring
homologacaoproducao
Ambiente.
cnpjstring
CNPJ do emitente, só dígitos (14).
inscricao_estadualstring
Inscrição estadual.
natureza_operacaostring
Natureza da operação.
regime_tributariointeger
123
Regime tributário: 1 Simples Nacional, 2 Simples com excesso, 3 Regime Normal.
razao_socialstring
Razão social.
nome_fantasiastring
Nome fantasia.
streetstring
Logradouro.
numberstring
Número.
complementstring
Complemento. Omitido se vazio.
neighborhoodstring
Bairro.
citystring
Cidade.
statestring
UF.
cepstring
CEP, só dígitos (até 8).
activeboolean
Se a loja deve emitir com esta configuração. Inativa, as notas saem pela configuração da loja.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
400JSON inválido, ambiente fora da lista, CNPJ sem 14 dígitos ou CEP com mais de 8. O texto fica em detail, em inglês.{"error":"failed to save vendor nfe config","detail":"cnpj must have exactly 14 digits (got 5)"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O módulo focusnfe está desligado nesta loja.{"error":"module_disabled","module":"focusnfe"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Listar notas emitidas

Lista as notas fiscais das vendas do seller, com situação, chave e links do XML e do DANFE (PDF). A emissão em si não passa por aqui: ela acontece pelo fluxo do pedido; esta rota só lê.

GET/api/v1/vendor/nfeSeller

NF-e emitidas para as vendas do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

statusstring
processandoautorizadoerrocanceladodenegadoinutilizado
Filtra por situação. Um valor desconhecido é tratado como processando, sem aviso.
order_iduuid
Só as notas deste pedido.
searchstring
Busca parcial no id do pedido, ref, número e chave.
date_fromstring
Criadas a partir de (data ou RFC 3339).
date_tostring
Criadas até (inclusive o dia).
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, 1 a 100.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/nfe?status=autorizado&page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Notas
json
{
  "records": [
    {
      "id": "ea743a1f-f53c-4f30-af9f-de703162cbd8",
      "order_id": "c539063e-e752-41d7-a94c-215468d3f761",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "ref": "VENDDOR_a1b2c3d4",
      "status": "autorizado",
      "chave_nfe": "35261012345678000195550010000001231234567890",
      "numero": "123",
      "serie": "1",
      "xml_url": "https://homologacao.focusnfe.com.br/arquivos/exemplo.xml",
      "danfe_url": "https://homologacao.focusnfe.com.br/arquivos/exemplo.pdf",
      "issued_at": "2026-10-10T13:00:00Z",
      "created_at": "2026-10-10T12:58:00Z",
      "updated_at": "2026-10-10T13:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

recordsobject[]

Notas da página.

iduuid
Id do registro.
order_iduuid
Pedido.
vendor_iduuid
Seller.
refstring
Referência única enviada à Focus NFe.
statusstring
processandoautorizadoerrocanceladodenegadoinutilizado
Situação por extenso.
chave_nfestring
Chave de acesso de 44 dígitos, após autorizada.
numerostring
Número da nota.
seriestring
Série.
xml_urlstring
Link do XML assinado.
danfe_urlstring
Link do DANFE (PDF).
error_msgstring
Códigos e motivos de rejeição da SEFAZ, em erro.
error_messagestring
Motivo legível da rejeição, em erro.
cancel_reasonstring
Justificativa do cancelamento.
canceled_atstring
Quando foi cancelada.
issued_atstring
Quando foi autorizada.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
totalinteger
Total.
pageinteger
Página.
per_pageinteger
Tamanho.
total_pagesinteger
Páginas.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}
403O módulo focusnfe está desligado nesta loja.{"error":"module_disabled","module":"focusnfe"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Veja também

  • Planos disponíveis
  • Visão geral
Anterior
Formas de pagamento do seller
Próxima
Planos disponíveis
Nesta página
  • Ver configuração fiscal
  • Exemplo de requisição
  • Resposta
  • Erros
  • Salvar configuração fiscal
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar notas emitidas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também