Central de Ajuda Quaza Provedores

FacturaSend (PT)

Guia de Configuração FacturaSend + Quaza — Paraguai

Guia de Configuração FacturaSend + Quaza

Os 13 passos para deixar a emissão de Documento Eletrônico funcionando

Este guia leva você do zero até o ponto em que o Quaza emite Faturas Eletrônicas para o SIFEN automaticamente. Tudo está dividido em duas frentes: o que configurar no FacturaSend (portal externo) e o que configurar no Quaza. Cada passo é independente — você consegue fazer um por dia se quiser.

Por que existem dois sistemas? O SIFEN (sistema oficial da SET no Paraguai) só aceita faturas assinadas digitalmente e em formato XML específico. O FacturaSend é o gateway que cuida dessa parte técnica: recebe a fatura do Quaza, assina com o seu certificado digital e transmite ao SIFEN. O Quaza é onde você faz o cobrança normal — quando uma fatura é gerada, o sistema monta o DE e passa para o FacturaSend.

Pré-requisitos antes de começar:

Conta ativa no FacturaSend (console.facturasend.com.py )
Certificado digital válido (arquivo .p12) — emitido pela DOCUSIGN, eFirma ou similar
RUC do contribuinte ativo na SET
Acesso administrativo ao Quaza

Se não tiver o certificado digital ainda, comece por isso — é o item de prazo mais longo (alguns dias até a emissão).

Visão geral dos 13 passos

Onde	Passo	O que faz
FacturaSend	1. Usuário	Criar usuário admin para a empresa
FacturaSend	2. Estabelecimento	Configurar matriz/filiais e formato do KuDE
FacturaSend	3. Ambiente	Selecionar Homologação ou Produção
FacturaSend	4. Certificado	Subir o arquivo .p12 com a senha
FacturaSend	5. API Key	Gerar chave de acesso para o Quaza usar
Quaza	6. Empresa NFe	Colar API Key e Tenant ID na empresa fiscal
Quaza	7. Configuração Fiscal	Definir como gerar notas (automático/manual)
Quaza	8. Permissões	Habilitar Documento Eletrônico para o grupo
Quaza	9. Série Fiscal	Confirmar série "Documento Eletrônico"
Quaza	10. Categorias	Vincular categorias à série DE
Quaza	11. Produtos (IVA)	Configurar IVA dos produtos
Quaza	12. Integração	Criar integração FacturaSend (Client ID/Secret)
FacturaSend	13. Webhooks	Cadastrar 5 URLs do Quaza no FacturaSend

1 Usuário no FacturaSend

FacturaSend → Configuración → Usuarios

O FacturaSend é uma plataforma multi-tenant — cada empresa tem seu próprio espaço (tenant). Antes de qualquer coisa, é preciso criar um usuário admin vinculado à sua empresa.

Acessar console.facturasend.com.py com a credencial fornecida pelo suporte do FacturaSend.
Verificar se você tem perfil Administrador — necessário para os próximos passos.
Se houver mais pessoas na sua equipe que vão operar a fiscal, criar usuários com perfil restrito (operador) para elas.

O acesso inicial: normalmente o suporte do FacturaSend cria o primeiro usuário admin durante a contratação. Se você não tem login, abra ticket pedindo ativação.

2 Configurar o Estabelecimento

FacturaSend → Configuración → Contribuyente Emisor

Aqui você cadastra os dados da matriz (e filiais, se houver). Cada estabelecimento tem um código de 3 dígitos. O default é 001 (matriz). Filiais são 002, 003, etc.

Campo	O que preencher
Establecimiento Nro	3 caracteres. Ex: `001` para matriz.
Denominación	Nome do estabelecimento (ex: `Matriz`, `Filial Asunción`).
Dirección, Departamento, Distrito	Endereço fiscal completo conforme RUC.
Teléfono, Email	Contato oficial do estabelecimento.
Formato Factura	Formato do KuDE: `Oficio`, `A4` ou `Carta`.

Filiais: se a empresa tem mais de uma filial, cadastre cada uma com seu próprio código de 3 dígitos. Cada filial pode ter formato de KuDE diferente. No Quaza, cada DE referencia o estabelecimento de origem.

3 Escolher o Ambiente

FacturaSend → Configuración del Contribuyente → aba Ambiente

O FacturaSend tem três ambientes diferentes. Eles servem para você testar antes de emitir faturas reais:

Ambiente	Para que serve	Reversível?
Homologação FacturaSend	Testes internos do FacturaSend. Não envia ao SIFEN. Útil para validar o fluxo de envio do Quaza sem gastar timbrado.	Sim
Homologação SIFEN	Envia ao SIFEN de testes. Documentos não têm validade fiscal real, mas você consegue ver como ficam aprovados. Requer certificado digital.	Sim
Produção SIFEN	Emissão real e fiscalmente válida. Toda fatura aqui é vinculada ao seu RUC.	NÃO

Atenção crítica: a passagem de Homologação para Produção é irreversível. Depois de produção, qualquer DE emitido vale fiscalmente. Faça os testes em Homologação, valide o fluxo completo (emissão, cancelamento, NC/ND), e só vire para Produção quando tudo estiver azeitado.

4 Subir o Certificado Digital

FacturaSend → Configuración del Contribuyente → aba Certificado

O certificado digital é o que assina as faturas eletrônicas. Sem ele, o SIFEN não aceita os DEs.

Clique em Cargar el Certificado Digital.
Suba o arquivo .p12 emitido pela autoridade certificadora.
Informe a senha (password) do certificado.
Confirme.

Se você não tem o arquivo no formato .p12:

Alguns emissores entregam em .cer + chave separada — abra ticket no FacturaSend pedindo a conversão.
Outros emitem direto na nuvem (eFirma) — abra ticket no FacturaSend para configurar a integração.
Verifique a data de validade antes de subir. Certificado vencido bloqueia a emissão.

Renovação: certificados duram 1, 2 ou 3 anos. Quando vencer, a emissão de DE para automaticamente. Marque no calendário um lembrete 30 dias antes da expiração para não tomar surpresa.

5 Gerar a API Key

FacturaSend → Configuración del Contribuyente → aba API Key

A API Key é a credencial que o Quaza usa para se autenticar no FacturaSend. Cada empresa tem a sua. Ela vai ser usada no próximo passo (configuração do Quaza).

Clique em Generar API Key (se não houver uma).
Copie a chave inteira — você vai precisar dela no Quaza.
Anote também o Tenant ID — é o nome sublinhado em verde na tela (ex: minha-empresa).
A URL base da API é sempre https://api.facturasend.com.py.

Trate como senha: qualquer pessoa com a API Key pode emitir DEs em nome da sua empresa. Não compartilhe por email aberto, planilha, etc. Se vazar, regenere imediatamente (a antiga deixa de funcionar).

6 Configurar a Empresa NFe no Quaza

Quaza → Fiscal → Empresa (NFe) → aba Configuração (Documento Eletrônico)

Agora vamos colar as informações do FacturaSend no Quaza. Abra a empresa fiscal no menu Fiscal → Empresa (NFe), edite, e vá para a aba Configuração (Documento Eletrônico):

#	Campo	O que preencher
1	API Key	Cole a chave gerada no Passo 5.
2	Tenant ID	O nome do tenant do Passo 5 (ex: `minha-empresa`).
3	Estabelecimento	Código de 3 dígitos do Passo 2 (ex: `001`).
—	Informações adicionais	Opcional — texto livre para anotações.

Clicar em Gravar empresa fiscal ao final.

Multi-empresa: se o seu Quaza opera várias empresas (multi-tenant interno), repita esse passo para cada uma — cada empresa tem seu próprio FacturaSend e API Key.

7 Configuração Fiscal Geral

Quaza → Admin → Configuração → aba Fiscal

Aqui você define o comportamento global da emissão fiscal no Quaza:

Campo	Recomendado	O que muda
Gerar notas para	`Pessoa física e jurídica`	Tipos de cliente que recebem DE automaticamente.
Competência	`Passada`	Define se o DE usa o mês anterior ou o atual como competência fiscal.
Natureza da operação	`Venta de mercancía adquirida...`	Texto-padrão da natureza fiscal das vendas.

Não use "Manual": em "Gerar notas", a opção Manual desabilita a geração automática. Os DEs só aparecem se alguém entrar lá e clicar — quase ninguém faz isso na rotina, e os clientes ficam sem fatura. Sempre Pessoa física e jurídica.

8 Permissões do Grupo

Quaza → Admin → Grupo → (editar grupo) → seção Fiscal

Os usuários do Quaza precisam ter permissão para ver e operar o módulo de Documento Eletrônico. Edite o grupo de cada usuário e habilite as ações:

Permissão	O que libera
Listar Documento Eletrônico	Acesso à listagem de DEs.
Adicionar Documento Eletrônico	Criar DE manualmente.
Editar Documento Eletrônico	Alterar DEs em estado Criado.
Remover Documento Eletrônico	Apagar DEs (raramente usado, mas precisa estar habilitado para alguns ajustes).

Quem deve ter: normalmente o grupo "Financeiro", "Fiscal" e "Gerente". O técnico de campo, o atendente de suporte e o vendedor não precisam — eles veem a fatura no contrato, mas não operam o DE.

9 Confirmar a Série Fiscal

Quaza → Fiscal → Série Fiscal

O Quaza separa as faturas em "séries fiscais" para diferenciar tipos de documento. Para o Paraguai, deve existir uma única série chamada Documento Eletrônico — ela é criada automaticamente quando você configura a empresa NFe.

Confira na listagem que ela existe e está com situação Habilitada. Se faltar, criar manualmente.

10 Categorias Fiscais

Quaza → Inventário → Categoria

Cada categoria de produto/serviço precisa estar vinculada à série DE para que o Quaza saiba que produtos dessa categoria geram Documento Eletrônico:

Campo	Configurar para
Série Fiscal	`Documento Eletrônico`
Tipo da Nota	`Documento Eletrônico`

Categorias antigas: se você está migrando de operação só com nota manual para emissão eletrônica, precisará atualizar todas as categorias existentes. Cuidado para não deixar nenhuma fora — produtos órfãos não geram DE.

11 Configurar IVA dos Produtos

Quaza → Fiscal → Produto → aba Documento Eletrônico

Cada produto fiscal precisa ter os dados de IVA preenchidos para passar pelo SIFEN. Sem isso, a fatura é rejeitada com "Alíquota IVA inválida":

Campo	Valor
Tipo Imposto	`IVA`
Forma do IVA	`Gravado IVA` (caso normal de tributação)
Proporção de incidência	`100`
Alíquota IVA	10% (regra geral) ou 5% (alguns serviços)

Para ISP: a maioria dos serviços de internet são Gravado IVA, 10%, 100% incidência. Equipamentos vendidos seguem o mesmo padrão. Para casos especiais (Exonerado, Exento), consultar o contador.

12 Criar a Integração no Quaza

Quaza → Admin → Integração → Adicionar

A integração é o que permite o FacturaSend mandar de volta para o Quaza os webhooks (avisos de aprovação/rejeição). Ela gera duas credenciais que o FacturaSend vai usar para se autenticar.

Clicar em Adicionar.
Identificador: FacturaSend (literal, importante para o sistema reconhecer).
Estado: Habilitado.
Gravar.
O sistema gera automaticamente Client ID (1) e Client Secret (2).

Agora gere o token para usar no webhook:

echo -n "client_id:client_secret" | base64

O token final tem o formato Basic {base64-da-string-acima}. Anote — vai usar no Passo 13.

Trate como senha: Client ID e Client Secret são credenciais sensíveis. Quem tiver eles consegue mandar webhooks para o Quaza fingindo ser o FacturaSend.

13 Cadastrar Webhooks no FacturaSend

FacturaSend → Opciones de la Empresa → Web Hooks

Os webhooks são URLs que o FacturaSend chama em momentos importantes — quando um DE é aprovado, rejeitado, cancelado, etc. Você precisa cadastrar 5 deles, um para cada evento:

#	URL no FacturaSend	Evento que dispara
1	`https://{seu-dominio}/py/fiscal/webhook/facturasend/created.php`	FacturaSend recebeu o DE com sucesso (antes do SIFEN responder).
2	`https://{seu-dominio}/py/fiscal/webhook/facturasend/sifencreated.php`	SIFEN aprovou o DE (passa para "Aprovado" no Quaza).
3	`https://{seu-dominio}/py/fiscal/webhook/facturasend/sifenrejected.php`	SIFEN rejeitou (passa para "Rejeitado SIFEN").
4	`https://{seu-dominio}/py/fiscal/webhook/facturasend/sifencanceled.php`	Cancelamento confirmado pelo SIFEN.
5	`https://{seu-dominio}/py/fiscal/webhook/facturasend/receipted.php`	DE de terceiro recebido contra seu RUC (não é o caso comum).

Em cada webhook, configure também:

Campo	Valor
URL	Conforme tabela acima.
Authorization (cabeçalho)	`Basic {token}` — o token gerado no Passo 12.
Estado	Habilitado.

Validação: o Quaza verifica o cabeçalho Authorization em cada chamada. Se o Basic Auth não bater com a integração cadastrada (Passo 12), retorna 401 — protegendo seu sistema contra requisições falsas.

Sincronização periódica (cron)

Mesmo com webhooks configurados, o Quaza tem uma rotina de segurança que verifica todos os DEs pendentes a cada 10 minutos. Isso protege contra falhas de webhook (rede caída, FacturaSend instável) e garante que nenhum DE fica preso.

O cron já vem habilitado por default no Quaza. Se precisar verificar:

*/10 * * * * /usr/bin/php /caminho/quaza/tarefas/fiscal/consultadocumentoeletronicopy.php

O que ele faz: consulta o FacturaSend perguntando o estado atual dos DEs em situações pendentes (Enviado, Cancelamento pendente). Atualiza só o que mudou. Idempotente — pode rodar várias vezes sem problema. Trabalha em batches de 50 CDCs.

Como testar a configuração

Antes de virar para Produção, confirme que tudo está OK em Homologação:

Passo	O que fazer
1	No Quaza, gerar uma fatura para um cliente de teste.
2	Conferir que o DE foi criado em estado `Criado` em Fiscal → Documento Eletrônico.
3	Clicar em Processar.
4	Em poucos segundos o estado deve mudar para `Aprovado`. Se virou `Rejeitado`, ler o motivo na aba Histórico e corrigir.
5	Clicar em Imprimir e conferir que o KuDE sai com QR Code.
6	Cancelar a fatura de teste para validar o fluxo de cancelamento.

Quando todos os 6 passos funcionam em Homologação, está pronto para virar para Produção. Não esqueça que essa virada é irreversível (Passo 3) — depois, tudo vale fiscalmente.

Troubleshooting

Sintoma	Causa provável	Como resolver
DE fica em "Enviado" e nunca aprova	Webhook do SIFEN não está chegando ou o ambiente está errado.	Verificar webhooks (Passo 13). O cron de 10 min deve atualizar mesmo sem webhook.
Erro "API Key inválida" no Quaza	API Key copiada com espaço extra ou regerada no FacturaSend sem atualizar Quaza.	Voltar ao Passo 5, copiar de novo, colar no Passo 6.
Erro "Tenant não encontrado"	Tenant ID errado.	Conferir o nome sublinhado em verde no FacturaSend (Passo 5) e atualizar no Passo 6.
Erro "Certificado vencido"	Certificado expirou.	Renovar o certificado com a autoridade certificadora e refazer o Passo 4.
Webhook retornando 401	Authorization Basic errado.	Verificar que o token base64 do Passo 12 foi cadastrado no Passo 13 sem espaço extra.
Categorias não geram DE	Falta vincular Série Fiscal e Tipo da Nota.	Conferir Passo 10 — toda categoria precisa.
"Alíquota IVA inválida"	Produto sem IVA configurado.	Voltar ao Passo 11 e configurar o produto.

Perguntas frequentes

Pergunta	Resposta
Posso fazer toda a configuração sozinho?	Sim. Os 13 passos são auto-explicativos com este guia. O que pode demorar é só o certificado digital, que é externo (DOCUSIGN, eFirma, etc.).
Quanto tempo dura a configuração inteira?	Em condições normais (certificado digital em mãos), entre 1h e 4h dependendo do tamanho do catálogo de produtos (Passo 11).
Posso testar sem custos antes de ir para Produção?	Sim. Homologação FacturaSend e Homologação SIFEN são gratuitas — você emite quantos DEs quiser para validar.
Se eu mudar de FacturaSend para outro gateway, dá trabalho?	Sim. Atualmente o Quaza tem integração nativa só com o FacturaSend. Outros gateways exigem desenvolvimento.
Preciso refazer a configuração todo ano?	Não. Só renovar o certificado digital quando vencer (Passo 4). O resto fica.
Quem cadastra os webhooks: eu ou o FacturaSend?	Você. Os webhooks ficam no painel do FacturaSend, mas as URLs e o token vêm do Quaza. O guia (Passo 13) mostra exatamente como.

Próximo passo: operar

Configuração concluída? O próximo passo é aprender a operar o módulo de Documento Eletrônico no dia-a-dia: emitir, consultar, cancelar, e tratar rejeições. Veja o Guia do Documento Eletrônico (Paraguai) .

Pronto. Com os 13 passos completos, o seu Quaza emite Documento Eletrônico para o SIFEN automaticamente — toda fatura gerada para cliente paraguaio vira um DE em estado Criado, basta clicar em Processar. Em caso de problemas durante a configuração, contate o suporte da Quaza com o número do passo que falhou e a mensagem de erro.