AppantasyArthurLai/ezpay-einvoice-skill

O que ezpay-einvoice-skill faz?

Skill do Claude Code para a API de nota fiscal eletrônica (e-invoice) da ezPay（簡單行動支付）de Taiwan — emissão, cancelamento, estorno, consulta, controle de lotes (字軌), criptografia de chave dupla + verificador｜Aplicável em qualquer linguagem.

Funcionalidades

• Emissão de nota fiscal: Cria uma nova nota fiscal eletrônica com dados do comprador, itens e valores.
• Cancelamento de nota fiscal: Cancela uma nota fiscal existente pelo número e data.
• Estorno (allowance): Emite nota de estorno para correção de valores ou devolução.
• Consulta de nota fiscal: Recupera detalhes de uma nota fiscal emitida.
• Gerenciamento de lotes (字軌): Obtém e gerencia lotes de numeração fiscal.
• Criptografia de chave dupla: Gera e valida chaves criptográficas para segurança das transações.
• Verificador: Endpoint para verificação de integridade das notas emitidas.

Pré-requisitos

• Conta ativa na ezPay（簡單行動支付）com acesso à API de e-invoice.
• Chave de API (apiKey) e segredo (apiSecret) fornecidos pela ezPay.
• Número de identificação fiscal (CNPJ) da empresa (merchantId).

Instalação

Não requer instalação adicional. O skill é ativado ao incluir seu conteúdo no arquivo de configuração do agente (ex.: CLAUDE.md, .cursorrules) ou ao referenciá-lo como um skill externo.

Configuração

Defina as seguintes variáveis de ambiente no seu ambiente de desenvolvimento:

export EZPAY_API_KEY="sua_api_key_aqui"
export EZPAY_API_SECRET="seu_api_secret_aqui"
export EZPAY_MERCHANT_ID="seu_merchant_id_aqui"
export EZPAY_ENV="sandbox"  # ou "production"

Exemplos de Uso

1. Emitir uma nota fiscal

import os
from ezpay_invoice import EzpayInvoice

api = EzpayInvoice(
    api_key=os.getenv("EZPAY_API_KEY"),
    api_secret=os.getenv("EZPAY_API_SECRET"),
    merchant_id=os.getenv("EZPAY_MERCHANT_ID"),
    sandbox=True
)

response = api.issue_invoice(
    buyer_identifier="12345678",
    buyer_name="Cliente Exemplo",
    items=[
        {"name": "Produto A", "quantity": 1, "unit_price": 100.00}
    ],
    total_amount=105.00
)

print(response)

2. Cancelar uma nota fiscal

response = api.void_invoice(
    invoice_number="AB12345678",
    invoice_date="2024-03-15",
    reason="Erro na emissão"
)

print(response)

3. Consultar uma nota fiscal

response = api.query_invoice(invoice_number="AB12345678")
print(response)

Documentação da API

A API da ezPay e-invoice segue o padrão RESTful. Endpoints principais:

Método	Endpoint	Descrição
POST	/api/invoice/issue	Emitir nova nota fiscal
POST	/api/invoice/void	Cancelar nota fiscal
POST	/api/invoice/allowance	Emitir nota de estorno
GET	/api/invoice/query	Consultar nota fiscal
GET	/api/invoice/batches	Listar lotes disponíveis

Criptografia de Chave Dupla

A API utiliza criptografia de chave dupla para assinar as requisições. O processo é:

1. Gere uma chave temporária (nonce) e um timestamp.
2. Combine a chave de API, o segredo, o nonce e o timestamp.
3. Gere um HMAC-SHA256 da string combinada.
4. Inclua o hash no header X-Ezpay-Signature.

Exemplo em Node.js:

const crypto = require('crypto');

function generateSignature(apiKey, apiSecret, timestamp, nonce) {
    const message = `${apiKey}:${apiSecret}:${timestamp}:${nonce}`;
    return crypto.createHmac('sha256', apiSecret).update(message).digest('hex');
}

const timestamp = Date.now().toString();
const nonce = crypto.randomBytes(16).toString('hex');
const signature = generateSignature(process.env.EZPAY_API_KEY, process.env.EZPAY_API_SECRET, timestamp, nonce);

Verificador

O verificador permite validar que uma nota fiscal foi emitida corretamente pela ezPay:

curl -X GET "https://sandbox.ezpay.com.tw/api/invoice/verify?invoice_number=AB12345678&merchant_id=SEU_MERCHANT_ID" \
  -H "Authorization: Bearer SEU_TOKEN"

Suporte a Múltiplos Idioas

O skill é independente de linguagem de programação, funcionando com qualquer stack que suporte chamadas HTTP. Exemplos disponíveis em Python, Node.js, Java, PHP e Go.

Licença

Este skill é distribuído sob a licença MIT.